Proper documentation - Githubissues

janwirth commented 9 years ago

[ ] API (phpRuntime options)
[x] Tests
[x] Contributing

janwirth commented 9 years ago

I suppose using this platform for documentation. It features GitHub integration.

ivankravchenko commented 9 years ago

I'm not sure how rtfd platform can bring a value for now. Describe in more detail this and what is essential in 'Contributing' section.

janwirth commented 9 years ago

I guess you are right about the rtfd platform, that would be overkill as this is mostly jade. Yet still we have to document the phpRuntime options, and how functions are called inside tags.

Contributing is mainly to keep a consistent quality standard throughout this library: https://github.com/jenius/accord/blob/master/contributing.md

ivankravchenko commented 9 years ago

Of course, PHP runtime code, extractor code, detailed options and usage should be well documented. Thanks for pointing on well-formed 'Contributing' section.

OnkelTem commented 9 years ago

Meanwhie, would you explain what exactly jade2php generates?

Rendering this simple template:

doctype html
html(lang!="$language")
  head
    !=$head

using: ./bin/jade2php --pretty --omit-php-runtim --omit-php-extractor html.jade results to:

<?php error_reporting(E_ALL & ~E_NOTICE);function attr($name, $value = true, $escaped = true) {if (!empty($value)) {echo " $name=\"$value\""
;}}function attrs() {$args = func_get_args();$attrs = array();foreach ($args as $arg) {foreach ($arg as $key => $value) {if ($key == 'class'
) {if (!isset($attrs[$key])) $attrs[$key] = array();$attrs[$key] = array_merge($attrs[$key], is_array($value) ? $value : explode(' ', $value
));} else {$attrs[$key] = $value;}}}foreach ($attrs as $key => $value) {if ($key == 'class') {attr_class($value);} else {attr($key, $value);
}}}function attr_class() {$classes = array();$args = func_get_args();foreach ($args as $arg) {if (empty($arg) || is_array($arg) && count($ar
g) == 0) continue;$classes = array_merge($classes, is_array($arg) ? $arg : array($arg));}$classes = array_filter($classes);if (count($classe
s) > 0) attr('class', join(' ', $classes));}function add() {$result = '';$args = func_get_args();$concat = false;foreach ($args as $arg) {if
 ($concat || is_string($arg)) {$concat = true;$result .= $arg;} elseif (is_numeric($arg)) {if ($result === '') $result = 0;$result += $arg;}
}return $result;}?><!DOCTYPE html><html lang="$language"><head><?= $$head ?></head></html>

UPDATE

Fixed "--omit-php-runtim" in command line, now the output is much nicer:

<!DOCTYPE html><html lang="$language"><head><?= $$head ?></head></html>

but still I don't get how to make it look like:

<!DOCTYPE html>
  <html lang="<?php echo $language?>">
    <head>
      <?php echo $head ?>
    </head>
  </html>

i.e.:

with newlines and proper indentation
with <?php tags and echo (or print) instead of <?=
with resolved attributes

Thanks in advance!

ivankravchenko commented 9 years ago

1, 2. this is --pretty-related, #14.

What do you mean at "resolved attributes"? Could you mind to describe at code level with input and output?

janwirth commented 9 years ago

@OnkelTem you should write jade in the regular syntax, e.g. your $variable must not have a sigil (the dollar sign). Just go with variable. Jade2Php will then automatically wrap your variable inside the htmlspecialchars() function.

OnkelTem commented 9 years ago

Guys, I'm trying to figure out the difference between jade-php and jade2php. Form the source code point of view, while jade-php is 30-lines jade's Compile-callback implementation, jade2php is huge. Would you explain jade2php purpose and idea?

@FranzSkuffka I see, ok :)

ivankravchenko commented 9 years ago

jade2php strives to be as compatible with original jade code as possible, while jade-php don't. I made and used jade2php to write interoperable code (can be used with original Jade and with PHP). HTML output is also byte-to-byte same as with usage of original Jade preprocessor.

While writing jade-php-ish Jade code, you can't use it without jade-php.

ivankravchenko commented 9 years ago

One more important part – jade2php is extensively unit-tested. There also some edge cases and work to do, but I could say that jade2php is ready to be used (and open for contributions).

kevindice commented 9 years ago

I might be interested in helping document this.

ivankravchenko commented 9 years ago

@kevindice, you're welcome. Let do this via usual Fork → Pull Request?

janwirth commented 8 years ago

@ivankravchenko I just created http://pug2php.netlify.com/ which is a small demo app. What do you think?

@kevindice Are you still interested in creating a documentation?

Repo: https://github.com/FranzSkuffka/pug2php-www @ivankravchenko do you want me to transfer this to se7ensky?

dsifford commented 8 years ago

So I'm interested in the gulp plugin.. Unfortunately there is no documentation whatsoever for it (not even a readme.md).

Am I able to pass args using gulp?

dsifford commented 8 years ago

Scratch my last... Read through the source file and it looks like the options should be given in camelCase rather than kebab-case...

Docs would still be handy though.

SE7ENSKY / jade2php

Proper documentation #10