General edition

fadado · Mar 30, 2017 · 979c380 · 979c380
1 parent 07fd553
commit 979c380
Show file tree

Hide file tree

Showing 21 changed files with 114 additions and 105 deletions.
diff --git a/docs/blocks/body/markup.html b/docs/blocks/body/markup.html
@@ -1,6 +1,6 @@
 <#######################################################################
  # Body
- ######################################################################>
+ ######################################################################>&
 <main class="#body">
   <%ifndef BODY_BLOCK>&
     <%include blocks/content/markup.html>&
@@ -10,5 +10,4 @@
 </main>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
-
+#>&
diff --git a/docs/blocks/content/markup.html b/docs/blocks/content/markup.html
@@ -1,10 +1,9 @@
 <#######################################################################
  # Content
- ######################################################################>
+ ######################################################################>&
 <article class="$content">
   {{.page._content}}
 </article>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
-
+#>&
diff --git a/docs/blocks/footer/markup.html b/docs/blocks/footer/markup.html
@@ -1,11 +1,10 @@
 <#######################################################################
  # Footer
- ######################################################################>
+ ######################################################################>&
 <footer class="#footer">
   <%include blocks/license/markup.html>&
   <%include blocks/repository/markup.html>&
 </footer>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
-
+#>&
diff --git a/docs/blocks/header/markup.html b/docs/blocks/header/markup.html
@@ -1,6 +1,6 @@
 <#######################################################################
  # Header
- ######################################################################>
+ ######################################################################>&
 <header class="#header">
   <nav>
     <%include blocks/logo/markup.html>&
@@ -9,5 +9,4 @@
 </header>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
-
+#>&
diff --git a/docs/blocks/license/markup.html b/docs/blocks/license/markup.html
@@ -1,9 +1,9 @@
 <#######################################################################
  # License
- ######################################################################>
+ ######################################################################>&
 <section class="license">
   {{.snippets.footer}}
 </section>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
+#>&
diff --git a/docs/blocks/logo/markup.html b/docs/blocks/logo/markup.html
@@ -1,8 +1,7 @@
 <#######################################################################
  # Logo
- ######################################################################>
+ ######################################################################>&
 <span class="logo"><a href="index.html">{{.site.logo}}</a><span class="logo__version">v<%include ../VERSION></span></span>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
-
+#>&
diff --git a/docs/blocks/menu-bar/markup.html b/docs/blocks/menu-bar/markup.html
@@ -1,13 +1,13 @@
 <#######################################################################
  # Menu Bar
- ######################################################################>
+ ######################################################################>&
 <ol class="menu-bar">
 {% .site.menu[] %}
-  <li class='menu-bar__item {{if .path==$M.page._path then "menu-bar__item--current" else "" end}}'>
+  <li class='menu-bar__item {{if .path==$M.page._path then "menu-bar__item_current" else "" end}}'>
     <a href="{{.URL}}">{{.name}}</a>
   </li>
 {% end %}
 </ol>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
+#>&
diff --git a/docs/blocks/repository/markup.html b/docs/blocks/repository/markup.html
@@ -1,6 +1,6 @@
 <#######################################################################
  # Repository
- ######################################################################>
+ ######################################################################>&
 <ol class="repository">
   <li class="repository__section"><a href="https://github.com/fadado/jqt">code</a></li>
   <li class="repository__section"><a href="https://github.com/fadado/jqt/issues">issues</a></li>
@@ -9,5 +9,4 @@
 </ol>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
-
+#>&
diff --git a/docs/blocks/toc/markup.html b/docs/blocks/toc/markup.html
@@ -1,11 +1,10 @@
 <#######################################################################
  # Toc
- ######################################################################>
+ ######################################################################>&
 <nav class="#panel -side-right toc">
   <p class="toc__title">{{.snippets."toc-title"}}</p>
   {{.page._toc}}
 </nav>
 <#
 vim:ts=2:sw=2:ai:et:fileencoding=utf8:syntax=html
-#>
-
+#>&
diff --git a/docs/content/EXAMPLE.txt b/docs/content/EXAMPLE.txt
@@ -1,29 +1,30 @@
 <#
  # Template example
- #>
+ #>&
 
-```html
+```
 <html lang='{{.page.lang//.site.lang}}'>
 <head>
     <title>{{.page.title | gsub("<[^>]*>"; "")}}</title>
-    {# include files in preprocessing stage #}
+    {# include files in preprocessing stage: #}
     <%include "head.html">
     <meta name="generator" content="jqt v<%include "../VERSION">"/>
-    {# optional line #}
+    {# optional line: #}
     <meta name='dcterms.modified' content='{{.page.updated//empty}}' />
-    {# implicit loop for all authors #}
+    {# implicit loop for all authors: #}
     {% .page.author | sort[] %}<meta name='author' content='{{.}}' />
 </head>
 <body>
     <h1>{{.page.title}}</h1>
     <div id="CONTENT">
         {{.page._content}}
     </div>
+    {# macro calls: #}
     <%partial analytics 'UA-82432866-1'>
 </body>
 </html>
 ```
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown
-#>
+#>&
diff --git a/docs/content/FLOW.txt b/docs/content/FLOW.txt
@@ -1,6 +1,6 @@
 <#
  # Flow diagram
- #>
+ #>&
 
 <figure style="margin:0; padding:0;clear:both;">
 <figcaption style="text-align:center; font-weight: bold;">jqt workflow</figcaption>
@@ -17,14 +17,14 @@ Document +----------->|expand|-->|markup|--+          |merge|-------->|render|--
                                              metadata  |   |
            JSON       +------+                         |   |
          +----------->|expand|-------------------------+   |
-    Data   YAML       +------+                             |
-         +-------------------------------------------------+
-           YAML snippets         +------+                  |
+    Data   YAML       +------+                             |     CSS  +------+ 
+         +-------------------------------------------------+    +---->|expand|------> Style
+           YAML snippets         +------+                  |          +------+
          +---------------------->|markup|------------------+
                                  +------+
 ```
 </figure>
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown
-#>
+#>&
diff --git a/docs/content/LINKS.txt b/docs/content/LINKS.txt
@@ -1,6 +1,6 @@
 <#
  # Global links
-#>
+#>&
 
 [JQT]: https://fadado.github.io/jqt/
 [JQ]: https://stedolan.github.io/jq/
@@ -17,4 +17,4 @@
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown
-#>
+#>&
diff --git a/docs/content/content.md b/docs/content/content.md
@@ -17,7 +17,7 @@ _MarkDown_ promises and delivers exactly this.
 ## General operation
 
 _jqt_ transforms [MarkDown][MARKDOWN] documents to HTML using Pandoc,
-but before that [GPP][GPP] is used to preprocess them. Pandoc's output
+but before that [`gpp`][GPP] is used to preprocess them. Pandoc's output
 is then merged with the [YAML][YAML] front matter metadata and other input data before be sended
 to the render stage.  This is described on the middle of this diagram:
 
@@ -60,7 +60,8 @@ file in the scalar `.page._path`.
 <details>
 
 <summary>
-`jqt` `-T` option allows the use of YAML files for collections of MarkDown snippets:
+_jqt_ offers also a transformation that can also be considered a kind of preprocessing.
+The option `-T` allows the use of YAML files for collections of MarkDown snippets:
 </summary>
 
 <%include content/opt/T.txt>
@@ -96,21 +97,21 @@ and the second does the proper conversion to HTML.
 
 ### Preprocessing
 
-The MarkDown input content is preprocessed using [GPP][GPP]. All the expected options in a preprocessor are available,
+The MarkDown input content is preprocessed using [`gpp`][GPP]. All the expected options in a preprocessor are available,
 like defining new macros, include other files, etc. For example, a macro call
 like `<%include "../VERSION">` will expand to he string <code><%include "../VERSION"></code>
 as you can see in this paragraph and on the top of these pages.
 
 #### Macro calls
 
-All the power of GPP is available to help you when
+All the power of [GPP][GPP] is available to help you when
 [transcluding](https://en.wikipedia.org/wiki/Wikipedia:Transclusion)
 the input MarkDown document. The macro syntax used by _jqt_ in templates and input documents
 precedes macro names with the characters `<%` and finishes the macro calls with
 the character `>`. 
 Here are some of the predefined macros:
 
-```HTML
+```
 <%defeval x y>
 <%define x y>
 <%elif expr>
@@ -126,18 +127,18 @@ Here are some of the predefined macros:
 <%undef x>
 ```
 
-Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2`, etc.),
-but named arguments are also possible:
+Inside macro definitions parameters are prefixed by a dollar (`$1`, `$2`, etc.),
+but named parameters are also possible:
 
-```HTML
+```
 <%define sc
     <span style="font-variant:small-caps;">$1</span>
 >
 ```
 
 Predefined macros and user define macros have the same call sequence:
 
-```HTML
+```
 <%include content/LINKS.txt>
 <%sc 'A title in small caps'>
 ```
@@ -149,7 +150,7 @@ Warning: you must see the [GPP manual][GPPMAN] if you want to know all the gory
 Some fragments of text are skipped during macro expansion, like comments,
 continuation lines and arbitrary but delimited strings of characters:
 
-```HTML
+```
 <# Block comments, removed, must end in newline (also removed) #>
 Continuation lines using an ampersand &
 just before the newline character
@@ -159,7 +160,7 @@ _Strings_ are copied to the output, but evaluation of macros inside strings can
 be enabled or disabled depending on the type of string.  Also, string delimiters can
 be copied, or not, to the output:
 
-~~~HTML
+~~~
 <!-- XML comments -->
 <%sc 'Single quoted strings, only available in user defined macro calls'>
 <%sc "Double quoted strings, only available in user defined macro calls">
@@ -193,7 +194,7 @@ is, the ampersand and the newline are removed and effectively ignored).
 
 ### Pandoc’s Markdown
 
-_jqt_ accept as input format the [Pandoc's MarkDown](http://pandoc.org/MANUAL.html#pandocs-markdown)
+_jqt_ accept as input format for documents the [Pandoc's MarkDown](http://pandoc.org/MANUAL.html#pandocs-markdown)
 variant, with the <a href="http://pandoc.org/MANUAL.html#extension-pandoc_title_block">title block extension</a>
 disabled, and produces by default transitional HTML.  When running `jqt` the following
 Pandoc long options can be specified in

diff --git a/docs/content/data.md b/docs/content/data.md
@@ -44,6 +44,8 @@ data and influence JSON preprocessing:
 
 ## Data formats
 
+_jqt_ accepts metadata in [YAML][YAML] and [JSON][JSON] formats.
+
 ### YAML and JSON
 
 Documents front matter metadata and additional input YAML files are converted to
@@ -64,14 +66,14 @@ to be the `jq` input in the render stage.
 
 ### Preprocessing
 
-JSON files are preprocessed using [GPP][GPP], and all the expected options in a
+JSON files are preprocessed using [`gpp`][GPP], and all the expected options in a
 preprocessor are available, like defining new macros, include other files, etc.
 CSS files are also preprocessed with the same macros syntax used in JSON files.
 
 #### Macro calls
 
 The macro syntax used by _jqt_ in JSON and CSS files is very similar to the syntax used by the traditional
-TeX language macro processor, but changing the prefix character `\\` by `&`.
+TeX language macro processor, but changing the prefix character `\` by `&`.
 Here are some of the predefined macros:
 
 ```
@@ -90,19 +92,19 @@ Here are some of the predefined macros:
 &undef{x}
 ```
 
-Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2`, etc.),
-but named arguments are also possible.
+Inside macro definitions numeric parameters are prefixed by a dollar (`$1`, `$2`, etc.),
+but named parameters, prefixed with the `&` character, are also possible.
 The more used features are the inclusion on external files and the definition of simple constants:
 
-```JSON
+```
 // JSON example
 &define{eur}{\u20AC}
 &define{price}{$1 &euro}
 
 { "price": "&price{100}" }
 ```
 
-```CSS
+```
 // CSS example
 &include{theme.css}
 &define{Blue}{#0000FF}