Minor editions

fadado · Mar 27, 2017 · 1df3978 · 1df3978
1 parent 4783e5a
commit 1df3978
Show file tree

Hide file tree

Showing 11 changed files with 102 additions and 554 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 _jqt_ is a web template engine that uses [_jq_](https://stedolan.github.io/jq/) as expression language.
 
 If you want to learn to use _jqt_, read the documentation at
-<https://fadado.github.io/jqt/>. This documentation is generated using _jqt_ from the `docs/`
+<https://fadado.github.io/jqt/>. The documentation is generated using _jqt_ in the `docs`
 folder of this repository.
 
 The tools used in the implementation of _jqt_ are:

diff --git a/bin/jqt b/bin/jqt
@@ -2,7 +2,7 @@
 
 # jqt - jq based web template engine
 
-declare -r VERSION='0.3.0'
+declare -r VERSION='0.4.0'
 declare -r DATADIR='/usr/local/share'
 
 declare -r SELF=${0##*/}
@@ -34,22 +34,24 @@ function mkpipe
 {
     local -r LOCK="${TMPDIR}/mkpipe-lock"
     local -i i=0
+
+    # seize lock
     until { : > $LOCK; } 2>/dev/null; do
         sleep 0.01;
         i+=1
         (( i < 100 )) || {
-            echo 1>&2 "$SELF: Bored waiting a lock to open"
+            echo 1>&2 "$SELF: Bored waiting to open a lock"
             kill -s TERM $$ || kill -s KILL $$
         }
     done
-
-    local n="${TMPDIR}/$RANDOM"
-    while [[ -e $n ]]; do n="${TMPDIR}/$RANDOM"; done
-    mkfifo --mode 600 $n
-
+    # protected section
+    local name="${TMPDIR}/$RANDOM"
+    while [[ -e $name ]]; do name="${TMPDIR}/$RANDOM"; done
+    mkfifo --mode 600 $name
+    # release lock
     rm -f $LOCK
 
-    echo -n $n
+    echo -n $name
 }
 
 ########################################################################
@@ -199,19 +201,6 @@ function expand_json
     echo    # always generate almost one line!!!
 }
 
-css_min2()
-{
-	sed '
-# join rules in one big line
-/[^@]\+{$/,/}$/ {
-	:loop
-	N;
-	/}$/! b loop
-	s/\n//g
-}
-'
-
-}
 # < stdin > stdout
 function expand_css
 {
@@ -572,63 +561,38 @@ EOF
 
 function pandoc_options
 {
-    cat <<EOF
-Pandoc options:
-    --base-header-level=NUMBER                        --latexmathml[=URL]
-    --bibliography=FILE                               --mathjax[=URL]
-    --citation-abbreviations=FILE                     --mathml[=URL]
-    --columns=NUMBER                                  --mimetex[=URL]
-    --csl=FILE                                        --no-highlight
-    --email-obfuscation=none|javascript|references    --normalize
-    --file-scope                                      --number-offset=NUMBER[,NUMBER,...]
-    --gladtex                                         --number-sections
-    --highlight-style=STYLE                           --preserve-tabs
-    --html-q-tags                                     --section-divs
-    --id-prefix=STRING                                --tab-stop=NUMBER
-    --indented-code-classes=CLASSES                   --toc-depth=NUMBER
-    --jsmath[=URL]                                    --webtex[=URL]
-    --katex[=URL]                                     --wrap=[auto|none|preserve]
-    --katex-stylesheet
+echo 'Pandoc options:'
+    cat <<'EOF' | pr -e --omit-pagination --indent=4 --width=100 --columns=2
+--base-header-level=NUMBER
+--bibliography=FILE
+--citation-abbreviations=FILE
+--columns=NUMBER
+--csl=FILE
+--email-obfuscation=none|javascript|references
+--file-scope
+--gladtex
+--highlight-style=STYLE
+--html-q-tags
+--id-prefix=STRING
+--indented-code-classes=CLASSES
+--jsmath[=URL]
+--katex[=URL]
+--katex-stylesheet
+--latexmathml[=URL]
+--mathjax[=URL]
+--mathml[=URL]
+--mimetex[=URL]
+--no-highlight
+--normalize
+--number-offset=NUMBER[,NUMBER,...]
+--number-sections
+--preserve-tabs
+--section-divs
+--tab-stop=NUMBER
+--toc-depth=NUMBER
+--webtex[=URL]
+--wrap=[auto|none|preserve]'
 EOF
-    exit
-
-    # !!!
-    local opt
-
-    echo 'Pandoc options:'
-    for opt in \
-        '--base-header-level=NUMBER' \
-        '--bibliography=FILE' \
-        '--citation-abbreviations=FILE' \
-        '--columns=NUMBER' \
-        '--csl=FILE' \
-        '--email-obfuscation=none|javascript|references' \
-        '--file-scope' \
-        '--gladtex' \
-        '--highlight-style=STYLE' \
-        '--html-q-tags' \
-        '--id-prefix=STRING' \
-        '--indented-code-classes=CLASSES' \
-        '--jsmath[=URL]' \
-        '--katex[=URL]' \
-        '--katex-stylesheet' \
-        '--latexmathml[=URL]' \
-        '--mathjax[=URL]' \
-        '--mathml[=URL]' \
-        '--mimetex[=URL]' \
-        '--no-highlight' \
-        '--normalize' \
-        '--number-offset=NUMBER[,NUMBER,...]' \
-        '--number-sections' \
-        '--preserve-tabs' \
-        '--section-divs' \
-        '--tab-stop=NUMBER' \
-        '--toc-depth=NUMBER' \
-        '--webtex[=URL]' \
-        '--wrap=[auto|none|preserve]'
-    do echo "$opt"
-    done | pr -e --omit-pagination --indent=4 --width=100 --columns=2
-
     exit 0
 }
 

diff --git a/docs/content/content.md b/docs/content/content.md
@@ -44,11 +44,11 @@ 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,
-and injcontent. ects it into the render stage under a global JSON object named `.page`.
+and injects it into the render stage under a global JSON object named `.page`.
 
 ### Body
 
-Pandoc converts the document body to HTML,
+Pandoc translates the document body to HTML,
 and _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
@@ -141,7 +141,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][GPPMAN] if you want to know all the gory details.
+Warning: you must see the [GPP manual][GPPMAN] if you want to know all the gory details.
 
 #### Skips
 
@@ -155,12 +155,13 @@ just before the newline character
 ```
 
 _Strings_ are copied to the output, but evaluation of macros inside strings can
-be enabled or disabled.  String delimiters can be copied, or not, to the output:
+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'>
+<%sc "Double quoted strings, only available in user defined macro calls">
 Inline code `inside backticks`
 ```
 Fenced code blocks with tildes (~~~) or backticks (```)
@@ -193,7 +194,7 @@ is, the ampersand and the newline are removed and effectively ignored).
 
 _jqt_ accept as input format 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 transitional HTML.  When running `jqt` the following
+disabled, and produces by default transitional HTML.  When running `jqt` the following
 Pandoc long options can be specified in
 the command line and will be forwarded untouched to `pandoc`:
 

diff --git a/docs/content/data.md b/docs/content/data.md
@@ -11,7 +11,7 @@ updated: "2016-08-28T10:27:09Z"
 # Data model
 
 The simplest page always resides on a website, where there is a complex web of
-relationships between pages… as we have to imagine these relationships, we need
+relationships between pages. As we have to imagine these relationships, we need
 a way to represent them: this is the data model.
 
 ## General operation
@@ -44,9 +44,9 @@ data and influence JSON preprocessing:
 
 ## Data formats
 
-### YAML
+### YAML and JSON
 
-Document front matter metadata and additional input YAML files are converted to
+Documents front matter metadata and additional input YAML files are converted to
 JSON and merged to be the `jq` input in the render stage. No preprocessing is
 applied  to YAML data.
 
@@ -59,12 +59,13 @@ are provided:
 * `.page._path`: the input document pathname as provided to `jqt`.
 * `.page._toc`: the rendered input document table of contents.
 
-### JSON
-
 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 preprocessor are available,
-like defining new macros, include other files, etc.
+to be the `jq` input in the render stage.
+
+### JSON preprocessing
+
+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.
 
 #### Macro calls
 
@@ -107,7 +108,7 @@ but named arguments are also possible:
 { "price": "&price(100)" }
 ```
 
-Warning: you must read the [GPP manual][GPPMAN] if you want to know all the gory details.
+Warning: you must see the [GPP manual][GPPMAN] if you want to know all the gory details.
 
 #### Skips
 
@@ -158,7 +159,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 a wrappers to `jq` you have the following utilities shipped with _jqt_:
+As 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.
@@ -183,7 +184,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` and `cq --help` for more information.
+See the output of `yq --help` and `cq --help` for more information.
 
 ### Process front matter
 

diff --git a/docs/content/engine.md b/docs/content/engine.md
@@ -47,16 +47,16 @@ $ sudo dnf -y install make general-purpose-preprocessor jq pandoc PyYAML
 ```
 
 After clone or [download](https://github.com/fadado/jqt/releases) _jqt_ you can
-install it by hand executing a few orders on the _jqt_ top directory:
+manually install it executing a few commands on the _jqt_ top directory:
 
 ```zsh
 $ sudo mkdir -p /usr/local/bin /usr/local/share/jqt
 $ sudo cp bin/* /usr/local/bin
 $ sudo cp share/* /usr/local/share/jqt
-$ [[ $PATH =~ /usr/local/bin ]] || echo 'You must edit your PATH'
+$ [[ $PATH =~ /usr/local/bin ]] || echo 'Add /usr/local/bin to your PATH'
 ```
 
-If you know how to use `make` please read the `Makefile` located in the _jqt_
+If you know how to use `make` please see the `Makefile` located in the _jqt_
 top directory and run `make install` if you agree with the things that will
 happen. You can also change the installation directory:
 
@@ -106,24 +106,25 @@ arguments.  The usage possibilities are:
 
 ## Preprocessing
 
-One distinctive feature of _jqt_ is the text expansion applied to almost
+One distinctive feature of _jqt_ is the text expansion, using `gpp`, applied to almost
 all kinds of input files.
 Also, _jqt_ can be used as a standalone
 preprocessor thanks to the `-P` option.
 
-### Kinds of preprocessing
+### Files preprocessed
 
-The sections about
-[templates](./structure.html#preprocessing),
-[documents](./content.html#preprocessing) and [data](./data.html#json) cover in
-detail their usage of the preprocessor for _jqt_ templates, MarkDown documents
-and JSON data files.
+The pages about templates, documents and data cover in
+detail the usage of the preprocessor for
+[_jqt_ templates](./structure.html#preprocessing),
+[MarkDown documents](./content.html#preprocessing)
+and [JSON data files](./data.html#json).  _jqt_ can also expand CSS style sheets;  this is documented
+in the following section because it is outside the normal _jqt_ processing work flow.
 
 <details>
 
 <summary>
-_jqt_ also offers an standalone CSS preprocessor, and a transformation that can
-also be be considered a kind of preprocessing. The option `-T` allows the use
+_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>
 
@@ -133,8 +134,7 @@ of YAML files for collections of MarkDown snippets:
 
 ### CSS preprocessing
 
-_jqt_ can also expand CSS style sheets.  This is documented in this
-section because it is outside the normal _jqt_ processing work flow.
+_jqt_ offers an standalone CSS preprocessor. Macros can be defined, files included, etc.
 
 <details>
 
@@ -147,7 +147,7 @@ To enable CSS preprocessing the `-P` option must be used with the `css` or `css-
 </details>
 
 You can minify the CSS style sheet choosing the `css-min` option.
-The CSS minimization is not extremely aggressive, but is safe and sufficient.
+The CSS minimization is not extremely aggressive, but is safe and fast.
 
 #### Macro calls
 
@@ -183,11 +183,13 @@ The more used features are the inclusion on external files and the definition of
 { color: &Blue; }
 ```
 
-Warning: you must read the [GPP manual][GPPMAN] if you want to know all the gory details.
+Warning: you must see 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:
+Some fragments of text are skipped during macro expansion, like comments and
+other delimited strings of characters.  One use of the preprocessor is to
+remove in CSS files comments in the style of C and C++ languages:
 
 ```CPP
 /* Block comments */