Completed hello.md and engine.md first versions.

docs/Makefile

@@ -1,4 +1,4 @@
-# jqt documentation site management
+# jqt site documentation management
 
 ########################################################################
 # Prerequisites
@@ -50,55 +50,60 @@ SHELL := /bin/bash
 # Variables
 ########################################################################
 
+# Output directories
+CACHE := .jqt
+DESTINATION := /tmp/jqt
+
+# Directories for input files
+CONTENT := ./content
+STRUCTURE := ./structure
+PRESENTATION := ./presentation
+
 # Global objects available in jq scripts:
-#	.site		defined in the jqt call
-#	.snippets	defined in the jqt call
 #	.body		predefined by jqt
 #	.front		predefined by jqt
+#	.site		defined in the jqt call
+#	.snippets	defined in the jqt call
 
-# Some directories
-CACHE=.jqt
-DESTINATION = /tmp/jqt
-CONTENT=./content
-LAYOUTS=./layouts
-
-# Commands
-JQT = jqt \
-      -I$(LAYOUTS) \
-      -I$(CONTENT) \
-      --toc-depth=3 \
-      -isite \
-      -msite:$(CACHE)/site.json \
-      -msnippets:$(CACHE)/snippets.json
-
-MPCSS = gpp --nostdinc \
+# The template engine
+JQT := jqt \
+	-I$(STRUCTURE) \
+	-I$(CONTENT) \
+	-isite \
+	-msite:$(CACHE)/site.json \
+	-msnippets:$(CACHE)/snippets.json \
+	--toc-depth=3 \
+
+# Macro process CSS
+MPCSS := gpp --nostdinc \
 	+c '/*' '*/' \
 	+c '//' '\n' \
 	-U '&' ';' '(' ',' ');' '(' ')' '\$$' '' \
-	-M '&' ';' '(' ',' ');' '(' ')'
+	-M '&' ';' '(' ',' ');' '(' ')' \
 
-CSSMIN  = sed 's/^[ \t]\+//;s/[ \t]\$$//;/^$$/d;s/[\t ]*\([{}:,;>+~]\)[\t ]*/\1/g'
+# Minify CSS
+CSSMIN  := sed 's/^[ \t]\+//;s/[ \t]\$$//;/^$$/d;s/[\t ]*\([{}:,;>+~]\)[\t ]*/\1/g'
 
 # Common sources for all targets
-COMMON = \
+COMMON := \
 	$(CACHE)/site.json \
 	$(CACHE)/snippets.json \
-	$(LAYOUTS)/default.html \
-	$(LAYOUTS)/head.html \
-	$(LAYOUTS)/footer.html \
+	$(STRUCTURE)/default.html \
+	$(STRUCTURE)/head.html \
+	$(STRUCTURE)/footer.html \
 	$(CONTENT)/LINKS.md \
 	site.m \
 	site.jq \
 
-# Targets
-TARGETS = \
-	$(DESTINATION)/README.md	\
-	$(DESTINATION)/document.html	\
-	$(DESTINATION)/engine.html	\
-	$(DESTINATION)/index.html	\
-	$(DESTINATION)/metadata.html	\
-	$(DESTINATION)/template.html	\
-	$(DESTINATION)/jqt.css	\
+# Files to "build"
+TARGETS := \
+	$(DESTINATION)/README.md \
+	$(DESTINATION)/document.html \
+	$(DESTINATION)/engine.html \
+	$(DESTINATION)/index.html \
+	$(DESTINATION)/metadata.html \
+	$(DESTINATION)/template.html \
+	$(DESTINATION)/jqt.css \
 
 ########################################################################
 # Rules
@@ -116,28 +121,29 @@ $(DESTINATION)/README.md: README.md | $(DESTINATION)
 $(CACHE)/site.json: site.yaml | $(CACHE)
 	yaml2json < $< > $@
 
+$(CACHE)/snippets.pandoc: private id=^\([a-zA-Z_-]\+\)
 $(CACHE)/snippets.pandoc: $(CONTENT)/snippets.yaml | $(CACHE)
-	sed '/^\([a-zA-Z_-]\+\): *[>|]/{s/^\([a-zA-Z_-]\+\):.*/\1: >\n  $$\1$$/;b;};/^\([a-zA-Z_-]\+\): *[^#]/{s/^\([a-zA-Z_-]\+\):.*/\1: $$\1$$/;b;};d;' $< > $@
+	sed '/$(id): *[>|]/{s/$(id):.*/\1: >\n  $$\1$$/;b;};/$(id): *[^#]/{s/$(id):.*/\1: $$\1$$/;b;};d;' \
+	< $< > $@
 
 $(CACHE)/snippets.json: $(CONTENT)/snippets.yaml $(CACHE)/snippets.pandoc | $(CACHE)
-	pandoc --from markdown --to html --template=$(CACHE)/snippets.pandoc $< | yaml2json > $@
+	pandoc --from markdown --to html --template=$(CACHE)/snippets.pandoc $< \
+	| yaml2json > $@
 
 # Pages
 $(DESTINATION)/index.html: $(CONTENT)/home.md $(COMMON) | $(DESTINATION)
-	$(JQT) -d $< $(LAYOUTS)/default.html > $@
+	$(JQT) -d $< $(STRUCTURE)/default.html > $@
 
 define Page
-$(DESTINATION)/$(1).html: $(CONTENT)/$(1).md $(LAYOUTS)/page.html $(COMMON) $(CONTENT)/FLOW.md | $(DESTINATION)
-	$$(JQT) -d $$< $(LAYOUTS)/page.html > $$@
+$(DESTINATION)/$(1).html: $(CONTENT)/$(1).md $(STRUCTURE)/page.html $(COMMON) $(CONTENT)/FLOW.md | $(DESTINATION)
+	$$(JQT) -d $$< $(STRUCTURE)/page.html > $$@
 endef
 
-$(eval $(call Page,engine))
-$(eval $(call Page,document))
-$(eval $(call Page,metadata))
-$(eval $(call Page,template))
+PAGES := engine document metadata template
+$(foreach page,$(PAGES),$(eval $(call Page,$(page))))
 
 # CSS
-$(DESTINATION)/jqt.css: style/jqt.css style/github.css
+$(DESTINATION)/jqt.css: $(PRESENTATION)/jqt.css $(PRESENTATION)/github.css
 	$(MPCSS) $< | $(CSSMIN) > $@
 
 # Main

docs/content/FLOW.md

@@ -3,7 +3,7 @@
  #>
 
 ```
-           jqt        +------+   +-------+  jq
+           jqt        +------+   +-------+  jq script
 Template +----------->|expand|-->|convert|-------------------------------+
                       +------+   +-------+                               |
                                                                          |

docs/content/LINKS.md

@@ -7,6 +7,9 @@
 [REPO]: https://github.com/fadado/jqt
 [GPP]: https://logological.org/gpp
 [PANDOC]: http://pandoc.org/
+[BASH]: https://www.gnu.org/software/bash/
+[SED]: https://www.gnu.org/software/sed/
+[MAKE]: https://www.gnu.org/software/make/
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

docs/content/document.md

@@ -16,6 +16,46 @@ updated: "2016-08-13T07:48:26Z"
 
 ### Preprocessing
 
+The MarkDown input content is preprocessed using `gpp`
+
+#### Syntax of macros
+
+```
+<%define sc
+    <span style="font-variant:small-caps;">$1</span>
+>
+```
+
+```
+continuation lines using ampersand&
+```
+
+#### Skips
+
+##### Comments
+
+Comments are no cpied to the output.
+
+Macros evaluation inside comments is disabled.
+
+```
+<# block comments, removed, including terminating new-line #>
+```
+
+##### Strings
+
+Strings are copied to the output, but evaluation of macros inside strings can
+be is disabled.
+
+String delimiters can be copied, or not, to the output.
+
+```
+<%sc 'single quoted strings only in macro calls'>
+<%sc "double quoted strings, expanding macros inside, only in macro calls'>
+<!-- XML comments, not removed -->
+Fenced code blocks with tildes (~~~) or backticks (```)
+```
+
 ### HTML Generation
 
 ## Pandoc options

docs/content/engine.md

@@ -8,15 +8,15 @@ updated: "2016-08-13T07:48:26Z"
 
 ## General operation
 
-<%cite jqt> orchestrates several shell utilities to transform MarkDown text and
+_jqt_ orchestrates several shell utilities to transform MarkDown text and
 YAML or JSON data into a final HTML document. The transformation is driven by a template,
-where HTML is mixed with <%cite jq> snippets to implement the transformation logic.
+where HTML is mixed with _jq_ snippets to implement the transformation logic.
 This diagram shows how document, template and metadata inputs are combined by
-<%cite jqt> to produce the final HTML output.
+_jqt_ to produce the final HTML output.
 
 <%include "FLOW.md">
 
-## The `jqt`command
+## Invoking _jqt_
 
 ### Syntax
 
@@ -85,55 +85,137 @@ for included and imported modules.
 
 #### Debugging options
 
--C
-
-:   Stops processing before the render stage (outputs full JSON data model).
-
 -E
 
 :   Stops template processing after the preprocessing stage (outputs the
 expanded template).
 
--H
+    ```
+    $ jqt -E layouts/footer.html 
+    <div style="text-align:center;">
+    {{.snippets.footer}}
+    </div>
+    ...
+    ```
 
-:   Stops MarkDown processing after generating HTML (outputs several HTML fragments).
+-S
+
+:   Stops template processing before the render stage (outputs the jq script).
+
+    ```
+    $ jqt -S docs/layouts/footer.html 
+    import "libjqt" as jqt;
+    . as $M |
+    "<div style=\"text-align:center;\">",
+    "  \(.snippets.footer)",
+    "</div>",
+    ...
+    ```
 
 -P
 
 :   Stops MarkDown processing after preprocessing stage (outputs the expanded
 MarkDown).
 
--S
+    ```
+    $ jqt -P content/engine.md 
+    ---
+    title: jqt · the jq template engine
+    baseURL: https://fadado.github.com/jqt/
+    lang: en
+    ---
 
-:   Stops template processing before the render stage (outputs the jq script).
+    ## <cite>jq</cite> templates
+
+    The <cite>jq</cite> template language will be called <cite>jqt</cite>.  
+    The tools used in theimplementation of <cite>jqt</cite> are:
+    ```
+
+-H
+
+:   Stops MarkDown processing after generating HTML (outputs several HTML fragments).
+
+    ```
+    $ jqt -Icontent -H content/engine.md 
+    <p>Could be <a href="https://stedolan.github.io/jq/"><em>jq</em></a> the
+    basis for a web template engine? Let's explore…</p>
+    <h2 id="jq"><em>jq</em></h2>
+    ...
+    ```
+
+-C
+
+:   Stops processing before the render stage (outputs full JSON data model).
+
+    ```
+    $ jqt -I layouts -C -d content/home.md layouts/default.html 
+    {
+        "body": "<!DOCTYPE html ...
+        "front": {
+            "front-matter": false,
+            ...
+        }
+    }
+    ```
 
 ## Implementation
 
-The main tools used by <%cite jqt> are:
+The command `jqt` is a shell script executed by `bash`.
+`jqt` has been tested with [Bash 4.3][BASH], [GNU sed 4.2][SED], [GPP 2.24][GPP],
+[jq 1.5][JQ] and [Pandoc 1.13][PANDOC]. Also is used a small Python snippet which depends
+on the modules `json` and `yaml`.
 
-* [Bash](https://www.gnu.org/software/bash/), [sed](https://www.gnu.org/software/sed/) and other shell tools.
-* [GPP][GPP], a general-purpose preprocessor.
-* [jq][JQ], a lightweight and flexible command-line JSON processor.
-* [Pandoc][PANDOC], a universal document converter.
+The project uses [GNU Make][MAKE] on several development activities, but `make`
+is not necessary to run `jqt`.
 
-The command `jqt` is an script executed by `bash`. The external shell commands
-called by `jqt` are:
+All external shell commands called by `jqt` are:
 
 * `cat`
 * `gpp`
 * `jq`
 * `mkdir`
 * `mkfifo`
 * `pandoc`
-* `python` (with `json` and `yaml` modules)
+* `python`
 * `rm`
 * `sed`
 * `sleep`
 * `tee`
 
+Under a recent <%cite Fedora> <%cite Linux> distribution the following commands will install
+all the extra software _jqt_ needs:
+
+```zsh
+$ sudo dnf -y install make general-purpose-preprocessor jq pandoc PyYAML
+```
+
 ## Installation
 
-...
+If you know how to use `make` please read the `Makefile` located in the _jqt_
+top directory and run `make install` if you agree with the thinks that will
+happen. You can also change the installation directory:
+
+```zsh
+$ sudo make install prefix=/your/installation/path
+```
+
+You can also install _jqt_ by hand with few orders like:
+
+
+```zsh
+$ sudo mkdir -p /usr/local/bin /usr/local/share/jqt
+$ sudo cp bin/jqt /usr/local/bin
+$ sudo chmod +x /usr/local/bin/jqt
+$ sudo cp share/* /usr/local/share/jqt
+```
+
+If you are using a recent <%cite Fedora> <%cite Linux> distribution or similar
+`make` will also help you to install all the extra software _jqt_ needs:
+
+```zsh
+$ sudo make setup
+```
+
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown