Merge branch 'mac'

docs/Makefile

@@ -68,7 +68,7 @@ Common := \
 	$(Layouts)/default.html		\
 	$(Content)/LINKS.txt		\
 	filters.jq			\
-	macros/markup.m			\
+	content/markup.m		\
 
 # Files to "build"
 Home := index

docs/content/content.md

@@ -5,7 +5,7 @@ description: jqt transforms MarkDown documents to HTML using Pandoc.
 keywords:  jqt, markdown, pandoc, gpp, preprocessing, authoring content
 updated: "2016-08-28T10:27:09Z"
 ---
-<%include macros/markup.m>&
+<%include content/markup.m>&
 <%include content/LINKS.txt>&
 
 # Authoring content
@@ -16,7 +16,7 @@ _MarkDown_ promises and delivers exactly this.
 
 ## General operation
 
-_jqt_ transforms [MarkDown][MARKDOWN] documents to HTML using [Pandoc][PANDOC],
+<%cite jqt> transforms [MarkDown][MARKDOWN] documents to HTML using [Pandoc][PANDOC],
 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:
@@ -43,13 +43,13 @@ Document files contain MarkDown text preceded by an optional YAML front matter.
 
 ### Front matter
 
-_jqt_ extracts the YAML front matter, located at the very beginning of the file,
+<%cite 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 `.page`.
 
 ### Body
 
 Pandoc translates the document body to HTML,
-and _jqt_ injects it into the render stage under the global JSON scalar 
+and <%cite jqt> injects it into the render stage under the global JSON scalar 
 `.page._content`. If the document contains fenced code blocks specifying the language of
 the code block, the related highlight CSS code will be in the scalar `.page._highlight`. Also, the
 HTML table of contents is available in the scalar `.page._toc`, and the path to the document
@@ -60,7 +60,7 @@ file in the scalar `.page._path`.
 <details>
 
 <summary>
-_jqt_ offers also a transformation that can also be considered a kind of preprocessing.
+<%cite 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>
 
@@ -106,7 +106,7 @@ as you can see in this paragraph and on the top of these pages.
 
 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
+the input MarkDown document. The macro syntax used by <%cite 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:
@@ -194,7 +194,7 @@ is, the ampersand and the newline are removed and effectively ignored).
 
 ### Pandoc’s Markdown
 
-_jqt_ accept as input format for documents the [Pandoc's MarkDown](http://pandoc.org/MANUAL.html#pandocs-markdown)
+<%cite 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

docs/content/data.md

@@ -5,7 +5,7 @@ description: jqt combines one template with one MarkDown document and a data mod
 keywords:  jqt, JSON, YAML, gpp, preprocessing, data model
 updated: "2016-08-28T10:27:09Z"
 ---
-<%include macros/markup.m>&
+<%include content/markup.m>&
 <%include content/LINKS.txt>&
 
 # Data model
@@ -16,7 +16,7 @@ a way to represent them: this is the data model.
 
 ## General operation
 
-_jqt_ is designed to combine one template with one [MarkDown][MARKDOWN] document and a
+<%cite 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
@@ -44,7 +44,7 @@ data and influence JSON preprocessing:
 
 ## Data formats
 
-_jqt_ accepts metadata in [YAML][YAML] and [JSON][JSON] formats.
+<%cite jqt> accepts metadata in [YAML][YAML] and [JSON][JSON] formats.
 
 ### YAML and JSON
 
@@ -72,7 +72,7 @@ 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
+The macro syntax used by <%cite 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 `&`.
 Here are some of the predefined macros:
 
@@ -147,7 +147,7 @@ is, the ampersand and the newline are removed and effectively ignored).
 
 #### CSS preprocessor
 
-_jqt_ offers an standalone CSS preprocessor. Macros can be defined, files included, etc.
+<%cite jqt> offers an standalone CSS preprocessor. Macros can be defined, files included, etc.
 
 <details>
 
@@ -167,7 +167,7 @@ The CSS minimization is not extremely aggressive, but is safe and fast.
 ### Data conversion
 
 When preparing data inputs sometimes you need to mix files in several formats.
-To make easy the integration of data from several sources _jqt_ comes with the
+To make easy the integration of data from several sources <%cite jqt> comes with the
 following utilities to convert between CSV, JSON and YAML formats:
 
 * `csv2json`
@@ -184,7 +184,7 @@ argument and write to standard output.
 
 Sometimes you want to apply queries in the _jq_ style to CSV or YAML files,
 in the same style as _jq_ processes JSON data.
-As wrappers to `jq` you have the following utilities shipped with _jqt_:
+As wrappers to `jq` you have the following utilities shipped with <%cite jqt>:
 
 * `cq`, apply `jq` to CSV input files.
 * `yq`, apply `jq` to YAML input files.

docs/content/engine.md

@@ -5,23 +5,23 @@ description: jqt orchestrates several shell utilities to transform MarkDown text
 keywords:  jqt, jq, YAML, gpp, preprocessing, template engine
 updated: "2016-08-28T10:27:09Z"
 ---
-<%include macros/markup.m>&
+<%include content/markup.m>&
 <%include content/LINKS.txt>&
 
 # Template engine
 
 As the [Wikipedia says](https://en.wikipedia.org/wiki/Template_processor),
 <q><i>a template engine is
 software designed to combine one or more templates with a data model to produce
-one or more result documents</i></q>. _jqt_ fully satisfies this definition.
+one or more result documents</i></q>. <%cite jqt> fully satisfies this definition.
 
 ## Implementation
 
-_jqt_ orchestrates several shell utilities to transform [MarkDown][MARKDOWN] text and
+<%cite jqt> orchestrates several shell utilities to transform [MarkDown][MARKDOWN] text and
 [YAML][YAML] or [JSON][JSON] data into a final HTML page. The transformation is driven by a template,
 where HTML is mixed with [_jq_][JQ] snippets to implement the transformation logic.
 This diagram shows how document, template and data inputs (on the left) are combined by
-_jqt_ to produce the final HTML output:
+<%cite jqt> to produce the final HTML output:
 
 <%include content/FLOW.txt>
 
@@ -36,7 +36,7 @@ and `yaml` ([PyYAML](http://pyyaml.org/) implementation).
 The project uses [GNU Make][MAKE] on several development activities, but `make`
 is not necessary to run `jqt`.
 
-## Invoking _jqt_
+## Invoking <%cite jqt>
 
 ### Synopsis
 
@@ -75,13 +75,13 @@ arguments.  The usage possibilities are:
 
 ## Preprocessing
 
-One distinctive feature of _jqt_ is the text expansion, using [GPP][GPP], applied to almost
+One distinctive feature of <%cite jqt> is the text expansion, using [GPP][GPP], applied to almost
 all kinds of input files.
-Also, _jqt_ can be used as a standalone
+Also, <%cite jqt> can be used as a standalone
 preprocessor thanks to the `-P` option.
 
-_jqt_ uses two different syntaxes for macros, one for
-[_jqt_ templates](./structure.html#preprocessing) and
+<%cite jqt> uses two different syntaxes for macros, one for
+[<%cite jqt> templates](./structure.html#preprocessing) and
 [MarkDown documents](./content.html#preprocessing)
 and another for [JSON and CSS](./data.html#preprocessing) files. 
 The following table summarizes the syntax of macro calls:

docs/content/home.md

@@ -5,7 +5,7 @@ description: Could be jq the basis for a web template engine?
 keywords:  jqt, jq, template engine
 updated: "2016-08-28T10:27:09Z"
 ---
-<%include macros/markup.m>&
+<%include content/markup.m>&
 <%include content/LINKS.txt>&
 
 # Welcome
@@ -44,11 +44,11 @@ separated with the comma operator:
 In these examples the strings expand, vanish, or multiply without any
 explicit `if` or `for`!
 
-## _jqt_
+## <%cite jqt>
 
 To write [_jq_][JQ] scripts using strings with interpolations is not the idea we have
 for a template language. We need some syntactic sugar, and this is provided by
-_jqt_: you write templates in a very fashionable style, the templates
+<%cite jqt>: you write templates in a very fashionable style, the templates
 are translated into a [_jq_][JQ] script and then `jq` is feed with the created
 script and some content and data in [JSON][JSON] format&hellip; and the magic is done!
 
@@ -61,9 +61,9 @@ example seems to be a template?
 
 ### Status
 
-This site is built using _jqt_, and is itself in his implementation a kind of
-tutorial about _jqt_.
-If you want to learn how to use _jqt_ see all the different sections of this site:
+This site is built using <%cite jqt>, and is itself in his implementation a kind of
+tutorial about <%cite jqt>.
+If you want to learn how to use <%cite jqt> see all the different sections of this site:
 
 * [Template engine](./engine.html)
 * [Page structure](./structure.html)
@@ -73,7 +73,7 @@ If you want to learn how to use _jqt_ see all the different sections of this sit
 And don’t forget to study this documentation source code in the repository
 [`docs`](https://github.com/fadado/jqt/tree/master/docs) directory!
 
-_jqt_ is developed under the _Fedora_ Linux
+<%cite jqt> is developed under the _Fedora_ Linux
 distribution, and a lot of portability issues are expected at this stage of
 development. Please, use the project [GitHub repository][REPO] features if you
 want to collaborate or send any kind of questions.

docs/macros/markup.m → docs/content/markup.m

@@ -13,6 +13,11 @@
  #        <%cite 'text with spaces'>
  #>&
 <%define cite <cite>$1</cite>>&
+<# dfn -- HTML dfn element
+ # Usage: <%dfn word>
+ #        <%dfn 'text with spaces'>
+ #>&
+<%define dfn <dfn>$1</dfn>>&
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=perl
 #>&

docs/content/structure.md

@@ -5,7 +5,7 @@ description: Web pages structure is defined by the HTML markup.
 keywords:  jqt, jq, gpp, preprocessing, template engine
 updated: "2016-08-28T10:27:09Z"
 ---
-<%include macros/markup.m>&
+<%include content/markup.m>&
 <%include content/LINKS.txt>&
 
 # Page structure
@@ -15,9 +15,9 @@ transformation of that content in the final pages must be completely automatic.
 
 ## General operation
 
-Web pages structure is defined by the HTML markup, and using _jqt_ it is
+Web pages structure is defined by the HTML markup, and using <%cite jqt> it is
 added to the input content and data using a template.
-_jqt_ transforms templates into [_jq_][JQ] scripts, but before that
+<%cite jqt> transforms templates into [_jq_][JQ] scripts, but before that
 [GPP][GPP] is used to preprocess them. The generated script will be combined
 with the document and data inputs in the render stage to produce the
 final HTML page.
@@ -43,8 +43,8 @@ rendering:
 ## Template syntax
 
 A template is a text file with intermixed snippets of [_jq_][JQ] code. Snippets can be
-<dfn>expressions</dfn> (delimited by `{{` and `}}`), which get replaced with
-values when a template is rendered and <dfn>actions</dfn> (delimited by `{%` and `%}`), which control the logic of the
+<%dfn expressions> (delimited by `{{` and `}}`), which get replaced with
+values when a template is rendered and <%dfn actions> (delimited by `{%` and `%}`), which control the logic of the
 template.  Comments (delimited by `{#` and `#}`) are ignored and not copied to the output.
 This is a complete template example:
 
@@ -65,7 +65,7 @@ as you can see in the internal code of this page.
 
 #### Macro calls
 
-The macro syntax used by _jqt_ in templates and MarkDown documents precedes macro names with the characters `<%`
+The macro syntax used by <%cite jqt> in templates and MarkDown documents precedes macro names with the characters `<%`
 and finishes the macro calls with the character `>`.
 Here are some of the predefined macros:
 
@@ -121,7 +121,7 @@ before include the base template:
 <%include default.html>
 ```
 
-In addition to [GPP][GPP] predefined macros _jqt_ define some macros to be
+In addition to [GPP][GPP] predefined macros <%cite jqt> define some macros to be
 included in the render stage. 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.
@@ -162,7 +162,7 @@ This table summarizes all the available skips:
 `{%` `%}`           No                  No                  No
 `{#` `#}`           No                  No                  No
 
-Table: **Semantics for all _jqt_ template skips**
+Table: **Semantics for all <%cite jqt> template skips**
 
 [^1]: An ampersand followed by a newline is treated as a line continuation (that
 is, the ampersand and the newline are removed and effectively ignored).
@@ -173,15 +173,15 @@ is, the ampersand and the newline are removed and effectively ignored).
 
 The input text for a template is UTF-8 text with intermixed snippets of [_jq_][JQ] 
 code. Snippets can be _expressions_, _actions_ and _comments_.  The delimiters
-used by _jqt_ are as follows:
+used by <%cite jqt> are as follows:
 
 Delimiters    Purpose
 ----------    -----------------------------------
 `{{ ... }}`   Expressions to evaluate
 `{% ... %}`   Actions for conditional evaluation and loops
 `{# ... #}`   Comments not included in the output
 
-Table: **Delimiters used in _jqt_ templates**
+Table: **Delimiters used in <%cite jqt> templates**
 
 #### Expressions
 
@@ -201,9 +201,9 @@ cartesian product is generated!
 
 There are two kinds of actions:
 
-* <dfn>One line actions</dfn>: lines beginning with optional space, followed by a
+* <%dfn 'One line actions'>: lines beginning with optional space, followed by a
   `{%...%}` snippet and more text.
-* <dfn>Multiline actions</dfn>: initial line prefixed with optional space,
+* <%dfn 'Multiline actions'>: initial line prefixed with optional space,
   followed by an opening `{%...%}` snippet and a newline character
   immediately after the character `}`;
   then zero or more template lines; final line prefixed with optional space,

docs/layouts/default.html

@@ -1,5 +1,4 @@
 <# Default layout #>&
-<%include "macros/markup.m">&
 <!DOCTYPE html>
 <!-- this document uses polyglot markup (well formed XHTML5)  -->
 <html id="{{.page._id}}" xmlns="http://www.w3.org/1999/xhtml" lang="{{.page.lang//.site.lang}}" xml:lang="{{.page.lang//.site.lang}}">