Snippets documented better

fadado · Sep 6, 2016 · 077bfc1 · 077bfc1
1 parent e2532ce
commit 077bfc1
Show file tree

Hide file tree

Showing 8 changed files with 102 additions and 57 deletions.
diff --git a/Makefile b/Makefile
@@ -113,7 +113,7 @@ install:
 uninstall:
 	$(SUDO) rm --verbose --force -- $(addprefix $(prefix)/,$(wildcard bin/*))
 	$(SUDO) rm --verbose --force -- $(mandir)/man1/jqt.1.gz
-	test -d $(datadir)/$(project) \
+	test -d $(datadir)/$(project)					  \
 	&& $(SUDO) rm --verbose --force --recursive $(datadir)/$(project) \
 	|| true
 

diff --git a/bin/jqt b/bin/jqt
@@ -207,6 +207,7 @@ function expand_css
     local -r -a meta=( -M '\n&' '\n' '\b'  '\b'  '\n' '(' ')' )
     local -r -a skips=(
         +cccc '&\n' ''          # continuation line (& and \n removed)
+        +cccc '\\n' ''          # continuation line (\ and \n removed)
         +cccc '/*' '*/'         # multiline comment
         +cccc '//' '\n'         # line comment 
         +sqqq '`' '`' '\'       # literal string; like sh single quotes

diff --git a/docs/Makefile b/docs/Makefile
@@ -61,24 +61,24 @@ Layouts := ./layouts
 
 # Common sources for all targets
 Common := \
-	$(Meta)/config.json \
-	$(Meta)/snippets.json \
-	$(Layouts)/default.html \
-	$(Layouts)/head.html \
-	$(Layouts)/footer.html \
-	$(Content)/LINKS.txt \
-	filters.jq \
-	macros.m \
+	$(Meta)/config.json		\
+	$(Meta)/snippets.json		\
+	$(Layouts)/default.html		\
+	$(Layouts)/head.html		\
+	$(Layouts)/footer.html		\
+	$(Content)/LINKS.txt		\
+	filters.jq			\
+	macros.m			\
 
 # Files to "build"
 Home := index
 Pages := content data engine structure 
 Files := README.md jqt.css
 ManPage := ../jqt.1.gz
 Targets := \
-	$(ManPage) \
-	$(foreach f,$(Files),$(Destination)/$(f)) \
-	$(foreach p,$(Home) $(Pages),$(Destination)/$(p).html)
+	$(foreach f,$(Files),$(Destination)/$(f))		\
+	$(foreach p,$(Home) $(Pages),$(Destination)/$(p).html)	\
+	$(ManPage)						\
 
 ########################################################################
 # Commands
@@ -87,15 +87,15 @@ Targets := \
 # The template engine (.site and .snippets defined in the jqt call)
 JQT = jqt $(JQTFLAGS)
 JQTFLAGS := \
-	-I$(Layouts) \
-	-I$(Content) \
-	-ifilters \
-	-msite:$(Meta)/config.json \
-	-msnippets:$(Meta)/snippets.json \
-	--toc-depth=4 \
+	-I$(Layouts)				\
+	-I$(Content)				\
+	-ifilters				\
+	-msite:$(Meta)/config.json		\
+	-msnippets:$(Meta)/snippets.json	\
+	--toc-depth=4				\
 
 # Validate output pages (disable or redefine as you like)
-XHTMLValid := test -f /etc/xml/xhtml1-dtds.xml \
+XHTMLValid := test -f /etc/xml/xhtml1-dtds.xml			 \
 		&& xmllint --noout --valid $(Destination)/*.html \
 		&& echo 'XHTML valid!'
 # Uncomment to disable XML validation
@@ -150,28 +150,29 @@ $(Destination)/jqt.css: $(Styles)/jqt.css $(Styles)/github.css
 
 # Man page (to be build without callig `jqt`!)
 GPP_MD := \
-	-U '<%' '>' '\B' '\B' '\W>' '<' '>' '$$' '' \
-	-M '<%' '>' '\B' '\B' '\W>' '<' '>' \
-	+sccc '&\n' '' '' \
-	+sccc '<\#' '\#>\n' '' \
-	+siqi "'" "'" '\' \
-	+siQi '"' '"' '\' \
-	+ssss '<!--' '-->' '' \
-	+ssss '`'  '`' '' \
-	+ssss '\n```' '\n```' '' \
-	+ssss '\n~~~' '\n~~~' '' \
+	-U '<%' '>' '\B' '\B' '\W>' '<' '>' '$$' ''	\
+	-M '<%' '>' '\B' '\B' '\W>' '<' '>'		\
+	+sccc '&\n' '' ''				\
+	+sccc '\\n' '' ''				\
+	+sccc '<\#' '\#>\n' ''				\
+	+siqi "'" "'" '\'				\
+	+siQi '"' '"' '\'				\
+	+ssss '<!--' '-->' ''				\
+	+ssss '`'  '`' ''				\
+	+ssss '\n```' '\n```' ''			\
+	+ssss '\n~~~' '\n~~~' ''			\
     
 $(ManPage): $(Content)/jqt.1.markdown
 	$(info ==> $@)
-	gpp $(GPP_MD) -I$(Content) <$<  \
-	| pandoc --standalone --from markdown --to man \
+	gpp $(GPP_MD) -I$(Content) <$<			\
+	| pandoc --standalone --from markdown --to man	\
 	| gzip > $@
 
 # Help text
 /tmp/help: $(Content)/help.markdown
-	jqt -P MarkDown -I$(Content) <$<  \
-	| pandoc --from markdown --to plain - \
-	| sed '1,7b;/^$$/d;s/_\([A-Z]\+\)_/\1/g;/^[^A-Z]/s/^/    /' \
+	jqt -P MarkDown -I$(Content) <$<				\
+	| pandoc --from markdown --to plain -				\
+	| sed '1,7b;/^$$/d;s/_\([A-Z]\+\)_/\1/g;/^[^A-Z]/s/^/    /'	\
 	> $@
 
 ########################################################################

diff --git a/docs/content/content.md b/docs/content/content.md
@@ -40,6 +40,34 @@ the code block, the related highlight CSS code will be in the scalar `.page._hig
 HTML table of contents is available in the scalar `.page._toc`, and the path to the document
 file in the scalar `.page._path`.
 
+### MarkDown snippets
+
+`jqt` `-T` option allows the use of YAML files for collections of MarkDown snippets:
+
+<%include opt/T.txt>
+
+This feature can be used to collect multiple text snippets in only one file.
+The MarkDown can be transformed to HTML and put in a new YAML or JSON file
+with a command like this:
+
+```zsh
+jqt -T -- text.yaml | yaml2json > snippets.json
+```
+
+Then this converted file can be loaded by `jqt` in succesive calls:
+
+```zsh
+jqt -m snippets:snippets.json ...
+```
+
+Template files can expand the snippets without never containing raw content:
+
+```HTML
+<h1>{{.snippets.title}}</h1>
+```
+
+This allows the absolute separation of structure and content, as it should be.
+
 ## Document syntax
 
 Document's conversion has two stages. In the first the text is preprocessed,
@@ -56,9 +84,9 @@ as you can see in this paragraph and on the top of these pages.
 
 All the power of 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 input documents precedes macro names with the characters `<%`
-and finishes the macro calls with the character `>`.
-The more common predefined macros have this syntax:
+the input MarkDown document. The macro syntax used by _jqt_ in input documents
+precedes macro names with the characters `<%` and finishes the macro calls with
+the character `>`.  The more common predefined macros have this syntax:
 
 ```
 <%defeval x y>

diff --git a/docs/content/data.md b/docs/content/data.md
@@ -15,17 +15,17 @@ rendering the template. Also, `jqt` accepts additional data files in the command
 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.txt">
+<%include FLOW.txt>
 
 When invoking `jqt` you can use the following options to define the additional input
 data and influence JSON preprocessing:
 
-<%include "opt/D.txt">
-<%include "opt/I.txt">
-<%include "opt/M.txt">
-<%include "opt/m.txt">
-<%include "opt/n.txt">
-<%include "opt/T.txt">
+<%include opt/D.txt>
+<%include opt/I.txt>
+<%include opt/M.txt>
+<%include opt/m.txt>
+<%include opt/n.txt>
+<%include opt/T.txt>
 
 ## Data formats
 
@@ -174,9 +174,9 @@ Read the output of `yq --help` and `cq --help` for more information.
 When invoking `jqt` you can use the following options to extract, remove or
 test the presence of front matter data in the input document:
 
-<%include "opt/e.txt">
-<%include "opt/r.txt">
-<%include "opt/t.txt">
+<%include opt/e.txt>
+<%include opt/r.txt>
+<%include opt/t.txt>
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

diff --git a/docs/content/engine.md b/docs/content/engine.md
@@ -5,7 +5,7 @@ updated: "2016-08-28T10:27:09Z"
 <%include macros.m>&
 <%include LINKS.txt>&
 
-## General operation
+## Engine implementation
 
 _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,
@@ -105,16 +105,18 @@ preprocessor thanks to the `-P` option.
 The sections about
 [templates](./structure.html#preprocessing),
 [documents](./content.html#preprocessing) and [data](./data.html#json) cover in
-detail their usage of the preprocessor.
+detail their usage of the preprocessor for _jqt_ templates, MarkDown documents
+and JSON data files.
 
-_jqt_ offers a transformation that can also be be considered a kind of preprocessing. The option
-`-T` allows the use of YAML files for collections of MarkDown snippets:
+_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
+of YAML files for collections of MarkDown snippets:
 
 <%include opt/T.txt>
 
 ### CSS preprocessing
 
-As a bonus, _jqt_ can also expand CSS style sheets.  This is documented in this
+_jqt_ can also expand CSS style sheets.  This is documented in this
 section because it is outside the normal _jqt_ processing work flow.
 
 To enable CSS preprocessing the `-P` option must be used with the `css` or `css-min` options:
@@ -175,8 +177,9 @@ This table summarizes all the available skips in CSS files:
  Delimiters         Macro expansion     Delimiters removed  Content removed
 -------------       ---------------     ------------------  ---------------
 `&\n`[^1]           No                  Yes                 There is no content
+`\\n`[^2]           No                  Yes                 There is no content
 `/*` `*/`           No                  Yes                 Yes
-`//` `\n`[^2]       No                  Yes                 Yes
+`//` `\n`[^3]       No                  Yes                 Yes
 `` ` `` `` ` ``     No                  Yes                 No
 `"` `"`             No                  No                  No
 `'` `'`             No                  No                  No
@@ -185,7 +188,9 @@ Table: **Semantics for all CSS 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).
-[^2]: This represents a newline character.
+[^2]: A backslash followed by a newline is treated as a line continuation (that
+is, the backslash and the newline are removed and effectively ignored).
+[^3]: This represents a newline character.
 
 <#
 vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown

diff --git a/docs/content/home.md b/docs/content/home.md
@@ -52,8 +52,18 @@ example seems to be a template?
 
 ### Status
 
-If you want to learn to use _jqt_,  [read this documentation][JQT]
-and [install _jqt_](./engine.html#installation).
+This site is built using _jqt_, and is itself in his implementation a kind of
+tutorial about _jqt_.
+If you want to learn to use _jqt_ [install _jqt_](./engine.html#installation) and
+read all the different site sections:
+
+* [Template engine](./engine.html)
+* [Page structure](./structure.html)
+* [Authoring content](./content.html)
+* [Data model](./data.html)
+
+And don't forget to study the source code under the [docs directory](https://github.com/fadado/jqt/tree/master/docs)!
+
 _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

diff --git a/docs/styles/jqt.css b/docs/styles/jqt.css
@@ -39,7 +39,7 @@
 }
 
 #MENU li.logo a:hover {	// "picture"
-	text-decoration: overline;
+	color: #4183c4;
 }
 
 #MENU li.logo span {	// version