Working in template.md

fadado · Aug 15, 2016 · 489f5a8 · 489f5a8
1 parent 70cd5a7
commit 489f5a8
Show file tree

Hide file tree

Showing 6 changed files with 196 additions and 38 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -136,6 +136,8 @@ $(DESTINATION)/index.html: $(CONTENT)/home.md $(COMMON) \
 	$(JQT) -d $< $(STRUCTURE)/default.html > $@
 
 $(DESTINATION)/engine.html: $(CONTENT)/FLOW.md
+$(DESTINATION)/index.html: $(CONTENT)/EXAMPLE.md
+$(DESTINATION)/template.html: $(CONTENT)/EXAMPLE.md
 
 define Target
 $(DESTINATION)/$(1).html: $(CONTENT)/$(1).md $(STRUCTURE)/$(2).html $(COMMON) \

diff --git a/docs/content/EXAMPLE.md b/docs/content/EXAMPLE.md
@@ -0,0 +1,30 @@
+<#
+ # Template example
+ #>
+
+```html
+<html lang='{{.lang}}'>
+<head>
+    {# block comments #}
+    <title>{{.title | gsub("<[^>]*>"; "")}}</title>
+    <meta name='date' content='{{.updated//empty}}' />
+    {# implicit loop if several authors #}
+    {% .author | sort[] %}<meta name='author' content='{{.}}' />
+    {# include files in preprocessing stage #}
+    <%include "head.html">
+</head>
+<body>
+    <h1>{{.title}}</h1>
+    <h2>{{.subtitle//empty}}</h2> {# line vanishes if subtitle not defined #}
+    <ul>
+        {% range(.n) %} {# loop from 0 to .n-1 #}
+            <li>{{.}}</li>
+        {% end %}
+    </ul>
+</body>
+</html>
+```
+
+<#
+vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown
+#>
diff --git a/docs/content/document.md b/docs/content/document.md
@@ -6,7 +6,7 @@ updated: "2016-08-13T07:48:26Z"
 <%include "macros.m">&
 <%include "LINKS.md">&
 
-## Process
+## General operation
 
 _jqt_ will transform your MarkDown documents to HTML using
 [Pandoc][PANDOC], but before that [GPP][GPP] is used to preprocess the
@@ -49,10 +49,20 @@ as you can see on the top of this page.
 
 #### Syntax of macros
 
+Macro definition:
+
 ```
 <%define sc
     <span style="font-variant:small-caps;">$1</span>
->
+>&
+```
+
+Macro call examples:
+
+```
+<%sc 'A title in small caps'>
+
+<%include "LINKS.md">&
 ```
 
 #### Skips
@@ -80,6 +90,8 @@ Fenced code blocks with tildes (~~~) or backticks (```)
 ```
 ~~~
 
+This table summarize all the skips available:
+
  Delimiters     Place                   Macro expansion     Delimiters removed  Content removed
 -------------   -----                   ---------------     ------------------  ---------------
 &#60;# #>       Text                    No                  Yes                 Yes
@@ -90,7 +102,7 @@ Fenced code blocks with tildes (~~~) or backticks (```)
 &#96;``         Text                    No                  No                  No
 &#126;~~        Text                    No                  No                  No
 
-Table: **Semantics for all skips**
+Table: **Semantics for all MarkDown skips**
 
 ### HTML Generation
 

diff --git a/docs/content/home.md b/docs/content/home.md
@@ -49,28 +49,7 @@ script and some metadata and content in YAML or JSON format&hellip; and the magi
 And, how do the _syntactic sugar_ looks like?  Do you think the following
 example looks like a template?
 
-```html
-<html lang='{{.lang}}'>
-<head>
-    {# block comments #}
-    <title>{{.title | gsub("<[^>]*>"; "")}}</title>
-    <meta name='date' content='{{.updated//empty}}' />
-    {# implicit loop if several authors #}
-    {% .author | sort[] %}<meta name='author' content='{{.}}' />
-    {# include files in preprocessing stage #}
-    <%include "head.html">
-</head>
-<body>
-    <h1>{{.title}}</h1>
-    <h2>{{.subtitle//empty}}</h2> {# line vanishes if subtitle not defined #}
-    <ul>
-        {% range(.n) %} {# loop from 0 to .n-1 #}
-            <li>{{.}}</li>
-        {% end %}
-    </ul>
-</body>
-</html>
-```
+<%include "EXAMPLE.md">&
 
 ### Status
 

diff --git a/docs/content/metadata.md b/docs/content/metadata.md
@@ -6,7 +6,7 @@ updated: "2016-08-13T07:48:26Z"
 <%include "macros.m">&
 <%include "LINKS.md">&
 
-## Process
+## General operation
 
 _jqt_ will
 
@@ -16,11 +16,43 @@ This is described on the bottom of this diagram:
 
 <%include "FLOW.md">
 
-
-## Processing
+## Data XXXXXX
 
 ### Preprocessing
 
+The JSON input content is preprocessed using [GPP][GPP]. All the expected options are available,
+like defining new macros, include other files, etc. YAML input is not preprocessed.
+
+The main preprocessor use to remove comments in the CPP style.
+
+#### Syntax of macros
+
+Macro definition:
+
+```
+<!define X X>&
+```
+
+Macro call examples:
+
+```
+...
+```
+
+#### Skips
+
+JSON input is preprocessed like MarkDown input, but the skips available are no the same.
+This table summarize all the skips available:
+
+ Delimiters     Place   Macro expansion     Delimiters removed  Content removed
+-------------   -----   ---------------     ------------------  ---------------
+/* */           Text    No                  Yes                 Yes
+// \n           Text    No                  Yes                 Yes
+` `             Text    No                  Yes                 No
+" "             Text    Yes                 No                  No
+
+Table: **Semantics for all JSON skips**
+
 ## Other utilities
 
 When preparing metadata sometimes you need to mix files in several formats, or you

diff --git a/docs/content/template.md b/docs/content/template.md
@@ -6,31 +6,134 @@ updated: "2016-08-13T07:48:26Z"
 <%include "macros.m">&
 <%include "LINKS.md">&
 
-## Process
-
-_jqt_ will
+## General operation
 
+_jqt_ will transform your templates into _jq_ scripts, but before that
+[GPP][GPP] is used to preprocess them. The generated script will be executed,
+in the render stage, to generate the final HTML document while consuming the
+merged JSON inputs.
 This is described on the top of this diagram:
 
 <%include "FLOW.md">
 
-### Main _jqt_ features
+## Syntax
+
+A template is a file with UTF-8-encoded text, with a few kinds of delimited
+statements intermixed.  This is a complete template example:
+
+<%include "EXAMPLE.md">&
+
+Main features:
 
-* Each line of text in the template is a generator.
-* Interpolation of expressions using the `{{...}}` syntactic sugar.
-* Statements with _jq_ code inside `{%...%}`.
 * One line statements begin with optional space and `{%...%}`. The rest of the
   line is in the nested block.
 * Multiline blocks begin with optional space and `{%...%}`.
 * Multiline blocks finish with optional space and `{% end %}`.
 * Raw blocks are enclode between `{% raw %}` and `{%%}` marks.
 * The input metadata provided to _jq_ is available in the dot (`.`) and the global variable `M$`.
 
-## Processing
-
 ### Preprocessing
 
-### Execution by `jq`
+Templates are preprocessed using [GPP][GPP]. All the expected options are available,
+like defining new macros, include other files, etc.
+
+#### Syntax of macros
+
+Macro definition:
+
+```
+<%define HEAD_TITLE
+  <title>{{.front.title}} &ndash; {{.site.title}}</title>
+>&
+```
+
+Macro call examples:
+
+```
+<meta name="generator" content="jqt v<%include "../VERSION">"/>
+
+<%include "default.html">
+
+<%partial analytics 'UA-82432866-1'>&
+```
+
+Conditional macro call:
+
+```
+<%ifndef HEAD_TITLE>&
+    <title>{{.front.title}}</title>
+<%else><%call HEAD_TITLE><%endif>&
+```
+
+#### Skips
+
+Some fragments of text are skipped during macro expansion.
+
+```
+<# block comments, removed, must end in newline (also removed) #>
+```
+
+```
+Continuation lines using ampersand (removed with the newline character)&
+```
+
+Strings are copied to the output, but evaluation of macros inside strings can
+be disabled.  String delimiters can be copied, or not, to the output.
+
+~~~
+<%sc 'single quoted strings, only available in user defined macro calls'>
+<%sc "double quoted strings, only available in user defined macro calls'>
+<!-- XML comments, not removed -->
+All the jqt template tags: {#...#}, {%...%}, {{...}} 
+~~~
+
+Templates are preprocessed like MarkDown input, but the skips available are no the same.
+This table summarize all the skips available:
+
+ Delimiters     Place                   Macro expansion     Delimiters removed  Content removed
+-------------   -----                   ---------------     ------------------  ---------------
+&#60;# #>       Text                    No                  Yes                 Yes
+' '             User defined macros     No                  Yes                 No
+" "             User defined macros     Yes                 Yes                 No
+&lt;!-- -->     Text                    No                  No                  No
+{{ }}           Text                    No                  No                  No
+{% %}           Text                    No                  No                  No
+{# #}           Text                    No                  No                  No
+
+Table: **Semantics for all template skips**
+
+### _jq_ fragments
+
+The delimiters used by _jqt_ are as follows:
+
+Delimiters  Purpose
+----------  -----------------------------------
+{# ... #}   comments not included in the output
+{{ ... }}   expressions to evaluate and print
+{% ... %}   control statements
+
+Table: **Delimiters used in _jqt_ templates**
+
+The text inside the expressions and control delimiters is normal _jq_ code, when as
+a bonus, the `M$` global variable point to `jq` JSON input (the initial `.`
+&ndash;dot&ndash;).
+
+## Template evaluation
+
+You can pass to `jqt` the following template options to include or import external _jq_ modules:
+
+-L DIRECTORY
+
+:   Append *DIRECTORY* to the end of the jq list of directories to be searched
+for included and imported modules.
+
+-i MODULE
+
+:   Include the jq *MODULE* in the render stage.
+
+-j MODULE:NAME
+
+:   Import the jq *MODULE* in the render stage.
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown