From 81e9886a8976b6177e4ba1ad25caa4e2c52139f7 Mon Sep 17 00:00:00 2001 From: Joan Josep Ordinas Rosa Date: Sun, 14 Aug 2016 11:12:38 +0200 Subject: [PATCH] Completed hello.md and engine.md first versions. --- docs/Makefile | 94 +++++++++-------- docs/content/FLOW.md | 2 +- docs/content/LINKS.md | 3 + docs/content/document.md | 40 ++++++++ docs/content/engine.md | 124 +++++++++++++++++++---- docs/content/home.md | 16 +-- docs/content/template.md | 6 +- docs/{style => presentation}/github.css | 0 docs/{style => presentation}/jqt.css | 3 + docs/{layouts => structure}/default.html | 0 docs/{layouts => structure}/footer.html | 0 docs/{layouts => structure}/head.html | 0 docs/{layouts => structure}/page.html | 0 make.d/setup.make | 1 + 14 files changed, 212 insertions(+), 77 deletions(-) rename docs/{style => presentation}/github.css (100%) rename docs/{style => presentation}/jqt.css (96%) rename docs/{layouts => structure}/default.html (100%) rename docs/{layouts => structure}/footer.html (100%) rename docs/{layouts => structure}/head.html (100%) rename docs/{layouts => structure}/page.html (100%) diff --git a/docs/Makefile b/docs/Makefile index dce7309..165c7a8 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/content/FLOW.md b/docs/content/FLOW.md index e1a2c3d..191446f 100644 --- a/docs/content/FLOW.md +++ b/docs/content/FLOW.md @@ -3,7 +3,7 @@ #> ``` - jqt +------+ +-------+ jq + jqt +------+ +-------+ jq script Template +----------->|expand|-->|convert|-------------------------------+ +------+ +-------+ | | diff --git a/docs/content/LINKS.md b/docs/content/LINKS.md index 754e284..6706eb2 100644 --- a/docs/content/LINKS.md +++ b/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 diff --git a/docs/content/document.md b/docs/content/document.md index eeea7c5..40cedf2 100644 --- a/docs/content/document.md +++ b/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 + $1 +> +``` + +``` +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'> + +Fenced code blocks with tildes (~~~) or backticks (```) +``` + ### HTML Generation ## Pandoc options diff --git a/docs/content/engine.md b/docs/content/engine.md index 72eaf8c..ea3346e 100644 --- a/docs/content/engine.md +++ b/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,39 +85,90 @@ 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 +
+ {{.snippets.footer}} +
+ ... + ``` -: 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 | + "
", + " \(.snippets.footer)", + "
", + ... + ``` -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). + ## jq templates + + The jq template language will be called jqt. + The tools used in theimplementation of jqt are: + ``` + +-H + +: Stops MarkDown processing after generating HTML (outputs several HTML fragments). + + ``` + $ jqt -Icontent -H content/engine.md +

Could be jq the + basis for a web template engine? Let's explore…

+

jq

+ ... + ``` + +-C + +: Stops processing before the render stage (outputs full JSON data model). + + ``` + $ jqt -I layouts -C -d content/home.md layouts/default.html + { + "body": " 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` @@ -125,15 +176,46 @@ called by `jqt` are: * `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 diff --git a/docs/content/home.md b/docs/content/home.md index cf61fa6..73b4e3b 100644 --- a/docs/content/home.md +++ b/docs/content/home.md @@ -5,14 +5,14 @@ updated: "2016-08-13T07:48:26Z" <%include "site.m">& <%include "LINKS.md">& -Could be [<%cite jq>][JQ] the basis for a web template engine? +Could be [_jq_][JQ] the basis for a web template engine? Let's explore… -## <%cite 'jq'> +## _jq_ -<%cite jq> have nice features as string interpolation and implicit backtracking. +_jq_ have nice features as string interpolation and implicit backtracking. Mixed with the help of some syntactic sugar a powerful template engine appear. -Imagine the following simple strings, in the middle of a <%cite jq> program, +Imagine the following simple strings, in the middle of a _jq_ program, separated with the comma operator: ### Simple expansion @@ -36,12 +36,12 @@ separated with the comma operator: In these examples the strings expand, vanish, or multiply without any explicit `if` or `for`! -## <%cite jqt> +## _jqt_ -To write <%cite jq> scripts using strings with interpolations is not the idea we have +To write _jq_ scripts using strings with interpolations is not the idea we have for a template language. We need some syntactic sugar, and this is provided to you by -<%cite jqt>. You write templates in a very fashionable style, the templates -are translated into a <%cite jq> script and then `jq` is feed with the created +_jqt_. You write templates in a very fashionable style, the templates +are translated into a _jq_ script and then `jq` is feed with the created script and some metadata and content in JSON or YAML format… and the magic is done! ### Syntactic sugar diff --git a/docs/content/template.md b/docs/content/template.md index 3483b07..9672437 100644 --- a/docs/content/template.md +++ b/docs/content/template.md @@ -6,17 +6,17 @@ updated: "2016-08-13T07:48:26Z" <%include "site.m">& <%include "LINKS.md">& -### Main <%cite jqt> features +### Main _jqt_ features * Each line of text in the template is a generator. * Interpolation of expressions using the `{{...}}` syntactic sugar. -* Statements with <%cite jq> code inside `{%...%}`. +* Statements with _jq_ code inside `{%...%}`. * One line statements begin with optional space and `{%...%}`. The rest of the line is in the nested block. * Multiline blocks begin with optional space and `{%...%}`. * Multiline blocks finish with optional space and `{% end %}`. * Raw blocks are enclode between `{% raw %}` and `{%%}` marks. -* The input metadata provided to <%cite jq> is available in the dot (`.`) and the global variable `M$`. +* The input metadata provided to _jq_ is available in the dot (`.`) and the global variable `M$`. ## Processing diff --git a/docs/style/github.css b/docs/presentation/github.css similarity index 100% rename from docs/style/github.css rename to docs/presentation/github.css diff --git a/docs/style/jqt.css b/docs/presentation/jqt.css similarity index 96% rename from docs/style/jqt.css rename to docs/presentation/jqt.css index 2fd9b40..f07ad14 100644 --- a/docs/style/jqt.css +++ b/docs/presentation/jqt.css @@ -90,5 +90,8 @@ color: #4183c4; text-align: center; } +#FOOTER div.github a { + font-variant: small-caps; +} // vim:ts=4:sw=4:ai:noet:fileencoding=utf-8:syntax=css diff --git a/docs/layouts/default.html b/docs/structure/default.html similarity index 100% rename from docs/layouts/default.html rename to docs/structure/default.html diff --git a/docs/layouts/footer.html b/docs/structure/footer.html similarity index 100% rename from docs/layouts/footer.html rename to docs/structure/footer.html diff --git a/docs/layouts/head.html b/docs/structure/head.html similarity index 100% rename from docs/layouts/head.html rename to docs/structure/head.html diff --git a/docs/layouts/page.html b/docs/structure/page.html similarity index 100% rename from docs/layouts/page.html rename to docs/structure/page.html diff --git a/make.d/setup.make b/make.d/setup.make index 6051c5e..75243cf 100644 --- a/make.d/setup.make +++ b/make.d/setup.make @@ -11,5 +11,6 @@ setup: @rpm -q --quiet general-purpose-preprocessor || sudo dnf -y install general-purpose-preprocessor @rpm -q --quiet jq || sudo dnf -y install jq @rpm -q --quiet pandoc || sudo dnf -y install pandoc + @test -d /usr/share/doc/PyYAML || sudo dnf -y install PyYAML # vim:ai:sw=8:ts=8:noet:syntax=make