diff --git a/Makefile b/Makefile index d86fac2..8875ff3 100644 --- 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 index 1399df4..108bd53 100755 --- 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 index 2932b06..b1a6863 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -61,14 +61,14 @@ 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 @@ -76,9 +76,9 @@ 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 index 23f8019..50950ac 100644 --- 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 +

{{.snippets.title}}

+``` + +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 index 55dfb96..1f036a7 100644 --- 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 index 768dd49..43ff105 100644 --- 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 index a780363..0ee6193 100644 --- 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 index 958a3e2..3f09bbc 100644 --- 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