diff --git a/CHANGES b/CHANGES index 2a04ade..fc8dd7b 100644 --- a/CHANGES +++ b/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 diff --git a/VERSION b/VERSION index 6c6aa7c..341cf11 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.0 \ No newline at end of file +0.2.0 \ No newline at end of file diff --git a/bin/jqt b/bin/jqt index c6dd812..518d895 100755 --- a/bin/jqt +++ b/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##*/} diff --git a/docs/content/LINKS.md b/docs/content/LINKS.md index 2171667..589486c 100644 --- a/docs/content/LINKS.md +++ b/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/ diff --git a/docs/content/document.md b/docs/content/document.md index 1140bb2..6ae19da 100644 --- a/docs/content/document.md +++ b/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 $1 ->& +> ``` Predefined macros and user define macros have the same call sequence: @@ -94,8 +93,7 @@ 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 @@ -103,7 +101,7 @@ 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: ~~~ -<%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 (```) diff --git a/docs/content/metadata.md b/docs/content/metadata.md index 4f27997..df8a923 100644 --- a/docs/content/metadata.md +++ b/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 diff --git a/docs/content/opt/f.md b/docs/content/opt/f.md index 601aa18..7b3524d 100644 --- a/docs/content/opt/f.md +++ b/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 diff --git a/docs/content/opt/n.md b/docs/content/opt/n.md index de69c6b..90247fb 100644 --- a/docs/content/opt/n.md +++ b/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 diff --git a/docs/content/template.md b/docs/content/template.md index 70d735b..ee93c9c 100644 --- a/docs/content/template.md +++ b/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 + +> +``` + +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,17 +100,16 @@ And in the derived template you define a macro for the desired block, and includ ``` <%define HEAD_TITLE {{.front.title}} – {{.site.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 @@ -105,7 +117,7 @@ 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: ~~~ -<%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: * One line actions: lines beginning with optional space, followed by a `{%...%}` snippet and more text. * Multiline actions: 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 diff --git a/docs/site.yaml b/docs/site.yaml index ba0efc4..8a57721 100644 --- a/docs/site.yaml +++ b/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 diff --git a/jqt.1.gz b/jqt.1.gz index 57e3b51..10d7b4d 100644 Binary files a/jqt.1.gz and b/jqt.1.gz differ