Modularized options

fadado · Aug 16, 2016 · 731d2e1 · 731d2e1
1 parent 489f5a8
commit 731d2e1
Show file tree

Hide file tree

Showing 29 changed files with 320 additions and 141 deletions.
diff --git a/bin/jqt b/bin/jqt
@@ -437,20 +437,23 @@ function die
 
 function help
 {
-    cat <<EOF
-$SELF - jq based web template engine [version $VERSION]
-$USAGE
+    cat <<'EOF'
+jqt - jq based web template engine [version 0.1.0]
+
+Usage: jqt [options] < infile > result
+ jqt [options] infile > result
+ jqt [options] infile result
 
 Preprocessor options:
     -D NAME=VAL
         Define the user macro NAME as equal to VAL.
     -I DIRECTORY
-        Append DIRECTORY to the end of the preprocessor list of directories to be
-        searched for include files.
+        Append DIRECTORY to the end of the preprocessor list of
+        directories to be searched for include files.
 Template options:
     -L DIRECTORY
-        Append DIRECTORY to the end of the jq list of directories to be searched for
-        included and imported modules.
+        Append DIRECTORY to the end of the jq list of directories to be
+        searched for included and imported modules.
     -i MODULE
         Include the jq MODULE in the render stage.
     -j MODULE:NAME
@@ -460,25 +463,36 @@ Document options:
         Set output HTML version (HTML4 / HTML5).
     -d FILE
         Read content document from FILE.
-    -p  Print list of Pandoc accepted options.
 Metadata options:
     -M NAME:FILE
-        Add a FILE in JSON or YAML format to the input metadata at the top level (NAME is
-        ignored but must be present and unique).
+        Add a FILE in YAML or JSON format to the input metadata at the top
+        level (NAME is ignored but must be present and unique).
     -m NAME:FILE
-        Add a FILE in JSON or YAML format to the input metadata as a value of object NAME.
+        Add a FILE in YAML or JSON format to the input metadata as a value
+        of object NAME.
 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  Stops MarkDown processing after generating HTML (outputs several HTML fragments).
-    -P  Stops MarkDown processing after preprocessing stage (outputs the expanded
-        MarkDown).
-    -S  Stops template processing before the render stage (outputs the jq script).
+    -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
+        Stops MarkDown processing after generating HTML (outputs several
+        HTML fragments).
+    -P
+        Stops MarkDown processing after preprocessing stage (outputs the
+        expanded MarkDown).
+    -S
+        Stops template processing before the render stage (outputs the jq
+        script).
 Information options:
     -h, --help
         Display this message.
-    -V  Display version information.
+    -p
+        Print list of Pandoc accepted options.
+    -V
+        Display version information.
 EOF
     exit 0
 }
@@ -487,16 +501,11 @@ EOF
 #
 #?Document options:
 #?    -e
-#?        Extract YAML front matter to stdout.
 #?    -r
-#?        Remove front matter from MarkDown.
 #?    -t
-#?        Test presence of front matter in MarkDown.
 #?Metadata options:
 #?    -f NAME
-#?        Set name for YAML document metadata (defaults to 'front').
 #?    -n NAME
-#?        Set name for converted document (defaults to 'body').
 
 function pandoc_options
 {

diff --git a/docs/Makefile b/docs/Makefile
@@ -68,6 +68,19 @@ JQT := jqt \
 	-msnippets:$(CACHE)/snippets.json \
 	--toc-depth=3 \
 
+# Macro process MarkDown
+MPMD := gpp --nostdinc \
+	+sccc '&\n' '' '' \
+	+sccc '<\#' '\#>\n' '' \
+	+siqi "'" "'" '' \
+	+siQi '"' '"' '' \
+	+ssss '<!--' '-->' '' \
+	+ssss '`' '`' '' \
+	+ssss '\n```' '\n```' '' \
+	+ssss '\n~~~' '\n~~~' '' \
+	-U '<%' '>' '\B' '\B' '\W>' '<' '>' '$$' '' \
+	-M '<%' '>' '\B' '\B' '\W>' '<' '>' \
+
 # Macro process CSS
 MPCSS := gpp --nostdinc \
 	+c '/*' '*/' \
@@ -76,7 +89,7 @@ MPCSS := gpp --nostdinc \
 	-M '&' ';' '(' ',' ');' '(' ')' \
 
 # Minify CSS
-CSSMIN  := sed 's/^[ \t]\+//;s/[ \t]\$$//;/^$$/d;s/[\t ]*\([{}:,;>+~]\)[\t ]*/\1/g'
+CSSMIN := sed 's/^[ \t]\+//;s/[ \t]\$$//;/^$$/d;s/[\t ]*\([{}:,;>+~]\)[\t ]*/\1/g'
 
 # Common sources for all targets
 COMMON := \
@@ -152,6 +165,13 @@ $(DESTINATION)/jqt.css: $(PRESENTATION)/jqt.css $(PRESENTATION)/github.css
 	$(info ==> $@)
 	$(MPCSS) $< | $(CSSMIN) > $@
 
+# Help text
+/tmp/help: $(CONTENT)/help.txt
+	$(MPMD) -I. -I$(CONTENT) $<  \
+	| pandoc --from markdown --to plain - \
+	| sed '1,7b;/^$$/d;s/_\([A-Z]\+\)_/\1/g;/^[^A-Z]/s/^/    /' \
+	> $@
+
 ########################################################################
 # Utilities
 ########################################################################

diff --git a/docs/content/document.md b/docs/content/document.md
@@ -16,6 +16,14 @@ This is described on the middle of this diagram:
 
 <%include "FLOW.md">
 
+You can pass the following options to `jqt` to modify document evaluation:
+
+<%include "opt/4.md">
+<%include "opt/D.md">
+<%include "opt/I.md">
+<%include "opt/d.md">
+<%include "opt/n.md">
+
 ## Document structure
 
 Documents contains MarkDown text with an optional YAML front matter.

diff --git a/docs/content/engine.md b/docs/content/engine.md
@@ -33,130 +33,95 @@ Usage: jqt [options] < infile > result
 
 #### Preprocessor options
 
--D NAME=VAL
-
-:   Define the user macro *NAME* as equal to *VAL*.
-
--I DIRECTORY
-
-:   Append *DIRECTORY* to the end of the preprocessor list of directories to be
-searched for include files.
-
+<%include "opt/D.md">
+<%include "opt/I.md">
 
 #### Template options
 
--L DIRECTORY
-
-:   Append *DIRECTORY* to the end of the jq list of directories to be searched
-for included and imported modules.
-
--i MODULE
-
-:   Include the jq *MODULE* in the render stage.
-
--j MODULE:NAME
-
-:   Import the jq *MODULE* in the render stage.
+<%include "opt/L.md">
+<%include "opt/i.md">
+<%include "opt/j.md">
 
 #### Document options
 
--4, -5
-
-:   Set output HTML version (HTML4 / HTML5).
-
--d FILE
-
-:   Read content document from *FILE*.
-
--p
-
-:   Print list of Pandoc accepted options.
+<%include "opt/4.md">
+<%include "opt/d.md">
+<%include "opt/n.md">
 
 #### Metadata options
 
--M NAME:FILE
-
-:   Add a *FILE* in YAML or JSON format to the input metadata at the top level
-(*NAME* is ignored but must be present and unique).
-
--m NAME:FILE
-
-:   Add a *FILE* in YAML or JSON format to the input metadata as a value of object *NAME*.
+<%include "opt/M.md">
+<%include "opt/f.md">
+<%include "opt/m.md">
 
 #### Debugging options
 
--E
+<%include "opt/E.md">
 
-:   Stops template processing after the preprocessing stage (outputs the
-expanded template).
-
-    ```
-    $ jqt -E layouts/footer.html 
-    <div style="text-align:center;">
-    {{.snippets.footer}}
-    </div>
-    ...
-    ```
-
--S
-
-:   Stops template processing before the render stage (outputs the jq script).
+```
+$ jqt -E layouts/footer.html 
+<div style="text-align:center;">
+{{.snippets.footer}}
+</div>
+...
+```
 
-    ```
-    $ jqt -S docs/layouts/footer.html 
-    import "libjqt" as jqt;
-    . as $M |
-    "<div style=\"text-align:center;\">",
-    "  \(.snippets.footer)",
-    "</div>",
-    ...
-    ```
+<%include "opt/S.md">
 
--P
+```
+$ jqt -S docs/layouts/footer.html 
+import "libjqt" as jqt;
+. as $M |
+"<div style=\"text-align:center;\">",
+"  \(.snippets.footer)",
+"</div>",
+...
+```
 
-:   Stops MarkDown processing after preprocessing stage (outputs the expanded
-MarkDown).
+<%include "opt/P.md">
 
-    ```
-    $ jqt -P content/engine.md 
-    ---
-    title: jqt · the jq template engine
-    baseURL: https://fadado.github.com/jqt/
-    lang: en
-    ---
+```
+$ jqt -P content/engine.md 
+---
+title: jqt · the jq template engine
+baseURL: https://fadado.github.com/jqt/
+lang: en
+---
 
-    ## <cite>jq</cite> templates
+## <cite>jq</cite> templates
 
-    The <cite>jq</cite> template language will be called <cite>jqt</cite>.  
-    The tools used in the implementation of <cite>jqt</cite> are:
-    ```
+The <cite>jq</cite> template language will be called <cite>jqt</cite>.  
+The tools used in the implementation of <cite>jqt</cite> are:
+```
 
--H
+<%include "opt/H.md">
 
-:   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>
+...
+```
 
-    ```
-    $ 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>
-    ...
-    ```
+<%include "opt/C.md">
 
--C
+```
+$ jqt -I layouts -C -d content/home.md layouts/default.html 
+{
+    "body": "<!DOCTYPE html ...
+    "front": {
+        "front-matter": false,
+        ...
+    }
+}
+```
 
-:   Stops processing before the render stage (outputs full JSON data model).
+#### Information options
 
-    ```
-    $ jqt -I layouts -C -d content/home.md layouts/default.html 
-    {
-        "body": "<!DOCTYPE html ...
-        "front": {
-            "front-matter": false,
-            ...
-        }
-    }
-    ```
+<%include "opt/h.md">
+<%include "opt/p.md">
+<%include "opt/V.md">
 
 ## Implementation
 

diff --git a/docs/content/help.txt b/docs/content/help.txt
@@ -0,0 +1,41 @@
+jqt - jq based web template engine [version <%include "../VERSION">]
+
+Usage: jqt [options] < infile > result\
+       jqt [options] infile > result\
+       jqt [options] infile result
+
+Preprocessor options:
+
+<%include "opt/D.md">
+<%include "opt/I.md">
+
+Template options:
+
+<%include "opt/L.md">
+<%include "opt/i.md">
+<%include "opt/j.md">
+
+Document options:
+
+<%include "opt/4.md">
+<%include "opt/d.md">
+
+Metadata options:
+
+<%include "opt/M.md">
+<%include "opt/m.md">
+
+Debugging options:
+
+<%include "opt/C.md">
+<%include "opt/E.md">
+<%include "opt/H.md">
+<%include "opt/P.md">
+<%include "opt/S.md">
+
+Information options:
+
+<%include "opt/h.md">
+<%include "opt/p.md">
+<%include "opt/V.md">
+