Version bump to 0.2.0

CHANGES

@@ -1,3 +1,28 @@
+Version 0.2.0:
+ - Finished site structure and minimal documentation
+ - Better content sections
+ - Better skip tables
+ - Man page ok
+ - Modularized options
+ - Completed document.md first version
+ - Fusion of sub-makefiles
+ - Added analytics
+ - Integrated yq
+ - Completed hello.md and engine.md first versions.
+ - Refactorized macros
+ - Started documentation blueprint
+ - Created auxiliar MD files
+ - Revised help information
+ - Do not minify HTML
+ - Implement the block concept
+ - Trailing line in snippets removed
+ - Only two global objects: .front and .body
+ - Classify files in directories
+ - Refactoring several files, added local macros, etc.
+ - Refactoring global pipes
+ - Link to releases
+ - Macro process CSS
+
 Version 0.1.0
  - In principio
 

VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

bin/jqt

@@ -2,7 +2,7 @@
 
 # jqt - jq based web template engine
 
-declare -r VERSION='0.1.0'
+declare -r VERSION='0.2.0'
 declare -r DATADIR='/usr/local/share'
 
 declare -r SELF=${0##*/}

docs/content/LINKS.md

@@ -6,6 +6,7 @@
 [JQ]: https://stedolan.github.io/jq/
 [REPO]: https://github.com/fadado/jqt
 [GPP]: https://logological.org/gpp
+[GPPMAN]: https://files.nothingisreal.com/software/gpp/gpp.html
 [PANDOC]: http://pandoc.org/
 [BASH]: https://www.gnu.org/software/bash/
 [SED]: https://www.gnu.org/software/sed/

docs/content/document.md

@@ -8,14 +8,14 @@ updated: "2016-08-17T10:34:16Z"
 
 ## General operation
 
-_jqt_ will transform your [MarkDown][MARKDOWN] documents to HTML using Pandoc,
-but before that [GPP][GPP] is used to preprocess the documents. Pandoc's output
+_jqt_ transforms [MarkDown][MARKDOWN] documents to HTML using Pandoc,
+but before that [GPP][GPP] is used to preprocess them. Pandoc's output
 is then merged with the [YAML][YAML] front matter and other input metadata before be sended
 to the render stage.  This is described on the middle of this diagram:
 
 <%include "FLOW.md">
 
-When invoking `jqt` you can use the following options to influence the document
+When invoking `jqt` you can use the following options to influence document
 conversion:
 
 <%include "opt/4.md">
@@ -26,14 +26,13 @@ conversion:
 
 ## File structure
 
-Document files contains MarkDown text preceded by an optional YAML front matter.
+Document files contain MarkDown text preceded by an optional YAML front matter.
 
 ### Front matter
 
-Pandoc accepts YAML metadata intermixed with the MarkDown content. _jqt_ will
-extract the YAML front matter, located at the very beginning of the file,
-convert the top level scalar elements to HTML,
-and inject it into the render stage under a global JSON object named `.front`.
+Pandoc accepts YAML metadata intermixed with MarkDown content. _jqt_ 
+extracts the YAML front matter, located at the very beginning of the file,
+and injects it into the render stage under a global JSON object named `.front`.
 
 ### Body
 
@@ -84,7 +83,7 @@ Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2
 ```
 <%define sc
     <span style="font-variant:small-caps;">$1</span>
->&
+>
 ```
 
 Predefined macros and user define macros have the same call sequence:
@@ -94,16 +93,15 @@ Predefined macros and user define macros have the same call sequence:
 <%sc 'A title in small caps'>
 ```
 
-Warning: you must read the [GPP manual](https://files.nothingisreal.com/software/gpp/gpp.html)
-if you want to know all the gory details.
+Warning: you must read the [GPP manual][GPPMAN] if you want to know all the gory details.
 
 #### Skips
 
 Some fragments of text are skipped during macro expansion, like comments,
 continuation lines and arbitrary but delimited strings of characters:
 
 ```
-<# block comments, removed, must end in newline (also removed) #>
+<# Block comments, removed, must end in newline (also removed) #>
 Continuation lines using an ampersand just before the newline character&
 ```
 
@@ -112,8 +110,8 @@ be enabled or disabled.  String delimiters can be copied, or not, to the output:
 
 ~~~
 <!-- XML comments -->
-<%sc 'single quoted strings, only available in user defined macro calls'>
-<%sc "double quoted strings, only available in user defined macro calls'>
+<%sc 'Single quoted strings, only available in user defined macro calls'>
+<%sc "Double quoted strings, only available in user defined macro calls'>
 Inline code `inside backticks`
 ```
 Fenced code blocks with tildes (~~~) or backticks (```)

docs/content/metadata.md

@@ -8,10 +8,13 @@ updated: "2016-08-13T07:48:26Z"
 
 ## General operation
 
-You can provide metadata in the document front matter to be inserted when
-rendering the template. Also, `jqt` will accept in the command line  additional
-files in [YAML][YAML] or [JSON][JSON] format to be merged with
-the front matter. This is described on the bottom of this diagram:
+_jqt_ is designed to combine one template with one [MarkDown][MARKDOWN] document and a
+[data model](https://en.wikipedia.org/wiki/Data_model) to
+produce the final HTML result.
+To define the data model you can provide metadata in the document front matter to be inserted when
+rendering the template. Also, `jqt` accepts additional files in the command line
+in [YAML][YAML] or [JSON][JSON] format to be merged with
+the document front matter. This is described on the bottom of this diagram:
 
 <%include "FLOW.md">
 
@@ -28,14 +31,15 @@ metadata and influence JSON preprocessing:
 
 ### YAML
 
-Document front matter metadata and additional input YAML files will be converted to
+Document front matter metadata and additional input YAML files are converted to
 JSON and merged to be the `jq` input in the render stage.
 
 ### JSON
 
-Additional JSON input can be provided in external files. The files are
-preprocessed using [GPP][GPP], and all the expected options in a macro processor are available, like
-defining new macros, include other files, etc.
+Additional JSON files can be provided and are merged with front matter metadata
+to be the `jq` input in the render stage.  The files are preprocessed using
+[GPP][GPP], and all the expected options in a macro processor are available,
+like defining new macros, include other files, etc.
 
 #### Macro calls
 
@@ -47,7 +51,7 @@ for predefined macros and for user defined macros:
 * The user defined macro names for calls without arguments are preceded with
   the character `&` and the macro calls finishes with the character `;`.
 * The user defined macro names for calls with arguments are preceded with the
-  character `&`, followed by the character `(`, followed with arguments separated by
+  character `&`, then followed by the character `(`, accept arguments separated by
   commas (`,`), and the macro calls finishes with the characters `);`.  
 
 The more common predefined macros have this syntax:
@@ -77,17 +81,19 @@ Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2
 { "price": "&price(100);" }
 ```
 
+Warning: you must read the [GPP manual][GPPMAN] if you want to know all the gory details.
+
 #### Skips
 
 The main use of the preprocessor is to remove comments in the CPP style:
 
 ```
-/* block comments */
-// line comments
+/* Block comments */
+// Line comments
 ```
 
 Double quoted strings are also defined as skips, and backticks can be used to
-disable macro expansion (inside double quoted strings are ignored).
+disable macro expansion (inside double quoted strings backticks are ignored).
 This table summarize all the available skips in JSON files:
 
  Delimiters         Macro expansion     Delimiters removed  Content removed
@@ -129,8 +135,7 @@ As a wrappers to `jq` you have the following utilities shipped with _jqt_:
 * `cq`, apply `jq` to CSV input files.
 * `yq`, apply `jq` to YAML input files.
 
-These utilities imitate at maximum the `jq` command line interface, for example
-not requiring redirection of input:
+These utilities imitate at maximum the `jq` command line interface:
 
 ```
 $ yq '.store.book[2]' tests/data/store.yaml
@@ -150,7 +155,7 @@ $ yq --json -c '.store.book[2]' tests/data/store.yaml
 {"category":"fiction","price":8.99,"author":"Herman Melville",...
 ```
 
-Read the output of `yq --help` for more information.
+Read the output of `yq --help` and `cq --help` for more information.
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

docs/content/opt/f.md

@@ -1,5 +1,5 @@
 -f NAME
-:    Set name for YAML document metadata in _jq_ scripts (defaults to 'front').
+:    Define the name for YAML document metadata in _jq_ scripts (defaults to `front`).
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

docs/content/opt/n.md

@@ -1,5 +1,5 @@
 -n NAME
-:    Set name for converted document in _jq_ scripts (defaults to 'body').
+:    Define the name for converted document in _jq_ scripts (defaults to `body`).
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

docs/content/template.md

@@ -10,13 +10,13 @@ updated: "2016-08-13T07:48:26Z"
 
 _jqt_ will transform your template into a [_jq_][JQ]  script, but before that
 [GPP][GPP] is used to preprocess them. The generated script will be combined
-with the document and metadata inputs, in the render stage, to produce the
+with the document and metadata inputs in the render stage to produce the
 final HTML document.
 This is described on the top of this diagram:
 
 <%include "FLOW.md">
 
-When invoking `jqt` you can use the following options to modify the template
+When invoking `jqt` you can use the following options to modify template
 rendering:
 
 <%include "opt/D.md">
@@ -72,6 +72,19 @@ The more common predefined macros have this syntax:
 
 Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2`, etc.):
 
+```
+<%define stylesheet
+    <link rel="stylesheet" type="text/css" href="$1"/>
+>
+```
+
+Predefined macros and user define macros have the same call sequence:
+
+```
+<%include "head.html">
+<%stylesheet jqt.css>
+```
+
 With these simple tools is possible to emulate features considered advanced in some template engines,
 like template inheritance (also known as _blocks_). For example, in the base template (assume it is named `default.html`)
 you must put this conditional macro call:
@@ -87,25 +100,24 @@ And in the derived template you define a macro for the desired block, and includ
 ```
 <%define HEAD_TITLE
   <title>{{.front.title}} &ndash; {{.site.title}}</title>
->&
+>
 <%include "default.html">
 ```
 
 In addition to GPP predefined macros _jqt_ define in the file `libjqt.m`,
 always included in the render stage, a little library of macros. The
 more useful will be perhaps `<%partial name arg...>`, to include a template
-file passing arguments to it, and `<%call name arg...>`, to call a macro by name.
+file passing arguments to it and `<%call name arg...>`, to call a macro by name.
 
-Warning: you must read the [GPP manual](https://files.nothingisreal.com/software/gpp/gpp.html)
-if you want to know all the gory details.
+Warning: you must read the [GPP manual][GPPMAN] if you want to know all the gory details.
 
 #### Skips
 
 Some fragments of text are skipped during macro expansion, like comments,
 continuation lines and arbitrary but delimited strings of characters:
 
 ```
-<# block comments, removed, must end in newline (also removed) #>
+<# Block comments, removed, must end in newline (also removed) #>
 Continuation lines using an ampersand just before the newline character&
 ```
 
@@ -114,9 +126,9 @@ be enabled or disabled.  String delimiters can be copied, or not, to the output:
 
 ~~~
 <!-- XML comments -->
-<%sc 'single quoted strings, only available in user defined macro calls'>
-<%sc "double quoted strings, only available in user defined macro calls'>
-All the jqt template delimited regions: {#...#}, {%...%}, {{...}} 
+<%sc 'Single quoted strings, only available in user defined macro calls'>
+<%sc "Double quoted strings, only available in user defined macro calls'>
+All jqt template delimited regions: {#...#}, {%...%}, {{...}} 
 ~~~
 
 This table summarize all the available template skips:
@@ -146,9 +158,9 @@ The delimiters used by _jqt_ are as follows:
 
 Delimiters    Purpose
 ----------    -----------------------------------
-`{{ ... }}`   expressions to evaluate and print
-`{% ... %}`   actions for conditional and evaluation and loops
-`{# ... #}`   comments not included in the output
+`{{ ... }}`   Expressions to evaluate and print
+`{% ... %}`   Actions for conditional and evaluation and loops
+`{# ... #}`   Comments not included in the output
 
 Table: **Delimiters used in _jqt_ templates**
 
@@ -170,7 +182,7 @@ There are two kinds of actions:
 * <dfn>One line actions</dfn>: lines beginning with optional space, followed by a
   `{%...%}` snippet and more text.
 * <dfn>Multiline actions</dfn>: first line beginning with optional space, followed by an opening `{%...%}` snippet and a newline;
-  zero or more template lines; final line  beginning with optional space,  the ending `{% end %}` snippets and a newline.
+  then zero or more template lines; final line  beginning with optional space,  the ending `{% end %}` snippet and a newline.
   Multiline actions can nest and contain expressions and one line actions.
 
 The evaluation rules for one line actions are as follows:
@@ -182,12 +194,12 @@ The evaluation rules for one line actions are as follows:
 
 The evaluation rules for multiline actions are as follows:
 
-* If the opening snippet evaluates to `empty` the all the lines until the ending snippet vanishes.
+* If the opening snippet evaluates to `empty` all lines until the ending snippet disappear.
 * Otherwise, for each value produced by the opening snippet the lines until the ending snippet
   are evaluated with the value assigned to the dot (`.`). The initial dot is
   still available in the global variable `M$`.
 
-<# Warning: raw blocks not documented #>
+<# Warning: raw blocks are not documented because they are CONTENT! #>
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

docs/site.yaml

@@ -22,12 +22,12 @@ menu:
 - URL: ./engine.html
   id: content/engine
   name: Engine
-- URL: ./document.html
-  id: content/document
-  name: Document
 - URL: ./template.html
   id: content/template
   name: Template
+- URL: ./document.html
+  id: content/document
+  name: Document
 - URL: ./metadata.html
   id: content/metadata
   name: Metadata