From 61aafbef7473743150f8084716042cde004bf23e Mon Sep 17 00:00:00 2001 From: Joan Josep Ordinas Rosa Date: Thu, 18 Aug 2016 18:42:58 +0200 Subject: [PATCH] Version bump to 0.2.0 --- CHANGES | 25 ++++++++++++++++++++++ VERSION | 2 +- bin/jqt | 2 +- docs/content/LINKS.md | 1 + docs/content/document.md | 26 +++++++++++------------ docs/content/metadata.md | 35 ++++++++++++++++++------------- docs/content/opt/f.md | 2 +- docs/content/opt/n.md | 2 +- docs/content/template.md | 44 +++++++++++++++++++++++++-------------- docs/site.yaml | 6 +++--- jqt.1.gz | Bin 1294 -> 1294 bytes 11 files changed, 93 insertions(+), 52 deletions(-) diff --git a/CHANGES b/CHANGES index 2a04ade..fc8dd7b 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,28 @@ +Version 0.2.0: + - Finished site structure and minimal documentation + - Better content sections + - Better skip tables + - Man page ok + - Modularized options + - Completed document.md first version + - Fusion of sub-makefiles + - Added analytics + - Integrated yq + - Completed hello.md and engine.md first versions. + - Refactorized macros + - Started documentation blueprint + - Created auxiliar MD files + - Revised help information + - Do not minify HTML + - Implement the block concept + - Trailing line in snippets removed + - Only two global objects: .front and .body + - Classify files in directories + - Refactoring several files, added local macros, etc. + - Refactoring global pipes + - Link to releases + - Macro process CSS + Version 0.1.0 - In principio diff --git a/VERSION b/VERSION index 6c6aa7c..341cf11 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.0 \ No newline at end of file +0.2.0 \ No newline at end of file diff --git a/bin/jqt b/bin/jqt index c6dd812..518d895 100755 --- a/bin/jqt +++ b/bin/jqt @@ -2,7 +2,7 @@ # jqt - jq based web template engine -declare -r VERSION='0.1.0' +declare -r VERSION='0.2.0' declare -r DATADIR='/usr/local/share' declare -r SELF=${0##*/} diff --git a/docs/content/LINKS.md b/docs/content/LINKS.md index 2171667..589486c 100644 --- a/docs/content/LINKS.md +++ b/docs/content/LINKS.md @@ -6,6 +6,7 @@ [JQ]: https://stedolan.github.io/jq/ [REPO]: https://github.com/fadado/jqt [GPP]: https://logological.org/gpp +[GPPMAN]: https://files.nothingisreal.com/software/gpp/gpp.html [PANDOC]: http://pandoc.org/ [BASH]: https://www.gnu.org/software/bash/ [SED]: https://www.gnu.org/software/sed/ diff --git a/docs/content/document.md b/docs/content/document.md index 1140bb2..6ae19da 100644 --- a/docs/content/document.md +++ b/docs/content/document.md @@ -8,14 +8,14 @@ updated: "2016-08-17T10:34:16Z" ## General operation -_jqt_ will transform your [MarkDown][MARKDOWN] documents to HTML using Pandoc, -but before that [GPP][GPP] is used to preprocess the documents. Pandoc's output +_jqt_ transforms [MarkDown][MARKDOWN] documents to HTML using Pandoc, +but before that [GPP][GPP] is used to preprocess them. Pandoc's output is then merged with the [YAML][YAML] front matter and other input metadata before be sended to the render stage. This is described on the middle of this diagram: <%include "FLOW.md"> -When invoking `jqt` you can use the following options to influence the document +When invoking `jqt` you can use the following options to influence document conversion: <%include "opt/4.md"> @@ -26,14 +26,13 @@ conversion: ## File structure -Document files contains MarkDown text preceded by an optional YAML front matter. +Document files contain MarkDown text preceded by an optional YAML front matter. ### Front matter -Pandoc accepts YAML metadata intermixed with the MarkDown content. _jqt_ will -extract the YAML front matter, located at the very beginning of the file, -convert the top level scalar elements to HTML, -and inject it into the render stage under a global JSON object named `.front`. +Pandoc accepts YAML metadata intermixed with MarkDown content. _jqt_ +extracts the YAML front matter, located at the very beginning of the file, +and injects it into the render stage under a global JSON object named `.front`. ### Body @@ -84,7 +83,7 @@ Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2 ``` <%define sc $1 ->& +> ``` Predefined macros and user define macros have the same call sequence: @@ -94,8 +93,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](https://files.nothingisreal.com/software/gpp/gpp.html) -if you want to know all the gory details. +Warning: you must read the [GPP manual][GPPMAN] if you want to know all the gory details. #### Skips @@ -103,7 +101,7 @@ Some fragments of text are skipped during macro expansion, like comments, continuation lines and arbitrary but delimited strings of characters: ``` -<# block comments, removed, must end in newline (also removed) #> +<# Block comments, removed, must end in newline (also removed) #> Continuation lines using an ampersand just before the newline character& ``` @@ -112,8 +110,8 @@ be enabled or disabled. String delimiters can be copied, or not, to the output: ~~~ -<%sc 'single quoted strings, only available in user defined macro calls'> -<%sc "double quoted strings, only available in user defined macro calls'> +<%sc 'Single 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 (```) diff --git a/docs/content/metadata.md b/docs/content/metadata.md index 4f27997..df8a923 100644 --- a/docs/content/metadata.md +++ b/docs/content/metadata.md @@ -8,10 +8,13 @@ updated: "2016-08-13T07:48:26Z" ## General operation -You can provide metadata in the document front matter to be inserted when -rendering the template. Also, `jqt` will accept in the command line additional -files in [YAML][YAML] or [JSON][JSON] format to be merged with -the front matter. This is described on the bottom of this diagram: +_jqt_ is designed to combine one template with one [MarkDown][MARKDOWN] document and a +[data model](https://en.wikipedia.org/wiki/Data_model) to +produce the final HTML result. +To define the data model you can provide metadata in the document front matter to be inserted when +rendering the template. Also, `jqt` accepts additional files in the command line +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.md"> @@ -28,14 +31,15 @@ metadata and influence JSON preprocessing: ### YAML -Document front matter metadata and additional input YAML files will be converted to +Document front matter metadata and additional input YAML files are converted to JSON and merged to be the `jq` input in the render stage. ### JSON -Additional JSON input can be provided in external files. The files are -preprocessed using [GPP][GPP], and all the expected options in a macro processor are available, like -defining new macros, include other files, etc. +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 macro processor are available, +like defining new macros, include other files, etc. #### Macro calls @@ -47,7 +51,7 @@ for predefined macros and for user defined macros: * The user defined macro names for calls without arguments are preceded with the character `&` and the macro calls finishes with the character `;`. * The user defined macro names for calls with arguments are preceded with the - character `&`, followed by the character `(`, followed with arguments separated by + character `&`, then followed by the character `(`, accept arguments separated by commas (`,`), and the macro calls finishes with the characters `);`. The more common predefined macros have this syntax: @@ -77,17 +81,19 @@ Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2 { "price": "&price(100);" } ``` +Warning: you must read 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: ``` -/* block comments */ -// line comments +/* Block comments */ +// Line comments ``` Double quoted strings are also defined as skips, and backticks can be used to -disable macro expansion (inside double quoted strings are ignored). +disable macro expansion (inside double quoted strings backticks are ignored). This table summarize all the available skips in JSON files: Delimiters Macro expansion Delimiters removed Content removed @@ -129,8 +135,7 @@ As a 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. -These utilities imitate at maximum the `jq` command line interface, for example -not requiring redirection of input: +These utilities imitate at maximum the `jq` command line interface: ``` $ yq '.store.book[2]' tests/data/store.yaml @@ -150,7 +155,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` for more information. +Read the output of `yq --help` and `cq --help` for more information. <# vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown diff --git a/docs/content/opt/f.md b/docs/content/opt/f.md index 601aa18..7b3524d 100644 --- a/docs/content/opt/f.md +++ b/docs/content/opt/f.md @@ -1,5 +1,5 @@ -f NAME -: Set name for YAML document metadata in _jq_ scripts (defaults to 'front'). +: Define the name for YAML document metadata in _jq_ scripts (defaults to `front`). <# vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown diff --git a/docs/content/opt/n.md b/docs/content/opt/n.md index de69c6b..90247fb 100644 --- a/docs/content/opt/n.md +++ b/docs/content/opt/n.md @@ -1,5 +1,5 @@ -n NAME -: Set name for converted document in _jq_ scripts (defaults to 'body'). +: Define the name for converted document in _jq_ scripts (defaults to `body`). <# vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown diff --git a/docs/content/template.md b/docs/content/template.md index 70d735b..ee93c9c 100644 --- a/docs/content/template.md +++ b/docs/content/template.md @@ -10,13 +10,13 @@ updated: "2016-08-13T07:48:26Z" _jqt_ will transform your template into a [_jq_][JQ] script, but before that [GPP][GPP] is used to preprocess them. The generated script will be combined -with the document and metadata inputs, in the render stage, to produce the +with the document and metadata inputs in the render stage to produce the final HTML document. This is described on the top of this diagram: <%include "FLOW.md"> -When invoking `jqt` you can use the following options to modify the template +When invoking `jqt` you can use the following options to modify template rendering: <%include "opt/D.md"> @@ -72,6 +72,19 @@ The more common predefined macros have this syntax: Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2`, etc.): +``` +<%define stylesheet + +> +``` + +Predefined macros and user define macros have the same call sequence: + +``` +<%include "head.html"> +<%stylesheet jqt.css> +``` + With these simple tools is possible to emulate features considered advanced in some template engines, like template inheritance (also known as _blocks_). For example, in the base template (assume it is named `default.html`) you must put this conditional macro call: @@ -87,17 +100,16 @@ And in the derived template you define a macro for the desired block, and includ ``` <%define HEAD_TITLE {{.front.title}} – {{.site.title}} ->& +> <%include "default.html"> ``` In addition to GPP predefined macros _jqt_ define in the file `libjqt.m`, always included in the render stage, a little library of macros. The more useful will be perhaps `<%partial name arg...>`, to include a template -file passing arguments to it, and `<%call name arg...>`, to call a macro by name. +file passing arguments to it and `<%call name arg...>`, to call a macro by name. -Warning: you must read the [GPP manual](https://files.nothingisreal.com/software/gpp/gpp.html) -if you want to know all the gory details. +Warning: you must read the [GPP manual][GPPMAN] if you want to know all the gory details. #### Skips @@ -105,7 +117,7 @@ Some fragments of text are skipped during macro expansion, like comments, continuation lines and arbitrary but delimited strings of characters: ``` -<# block comments, removed, must end in newline (also removed) #> +<# Block comments, removed, must end in newline (also removed) #> Continuation lines using an ampersand just before the newline character& ``` @@ -114,9 +126,9 @@ be enabled or disabled. String delimiters can be copied, or not, to the output: ~~~ -<%sc 'single quoted strings, only available in user defined macro calls'> -<%sc "double quoted strings, only available in user defined macro calls'> -All the jqt template delimited regions: {#...#}, {%...%}, {{...}} +<%sc 'Single quoted strings, only available in user defined macro calls'> +<%sc "Double quoted strings, only available in user defined macro calls'> +All jqt template delimited regions: {#...#}, {%...%}, {{...}} ~~~ This table summarize all the available template skips: @@ -146,9 +158,9 @@ The delimiters used by _jqt_ are as follows: Delimiters Purpose ---------- ----------------------------------- -`{{ ... }}` expressions to evaluate and print -`{% ... %}` actions for conditional and evaluation and loops -`{# ... #}` comments not included in the output +`{{ ... }}` Expressions to evaluate and print +`{% ... %}` Actions for conditional and evaluation and loops +`{# ... #}` Comments not included in the output Table: **Delimiters used in _jqt_ templates** @@ -170,7 +182,7 @@ There are two kinds of actions: * One line actions: lines beginning with optional space, followed by a `{%...%}` snippet and more text. * Multiline actions: first line beginning with optional space, followed by an opening `{%...%}` snippet and a newline; - zero or more template lines; final line beginning with optional space, the ending `{% end %}` snippets and a newline. + then zero or more template lines; final line beginning with optional space, the ending `{% end %}` snippet and a newline. Multiline actions can nest and contain expressions and one line actions. The evaluation rules for one line actions are as follows: @@ -182,12 +194,12 @@ The evaluation rules for one line actions are as follows: The evaluation rules for multiline actions are as follows: -* If the opening snippet evaluates to `empty` the all the lines until the ending snippet vanishes. +* If the opening snippet evaluates to `empty` all lines until the ending snippet disappear. * Otherwise, for each value produced by the opening snippet the lines until the ending snippet are evaluated with the value assigned to the dot (`.`). The initial dot is still available in the global variable `M$`. -<# Warning: raw blocks not documented #> +<# Warning: raw blocks are not documented because they are CONTENT! #> <# vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown diff --git a/docs/site.yaml b/docs/site.yaml index ba0efc4..8a57721 100644 --- a/docs/site.yaml +++ b/docs/site.yaml @@ -22,12 +22,12 @@ menu: - URL: ./engine.html id: content/engine name: Engine -- URL: ./document.html - id: content/document - name: Document - URL: ./template.html id: content/template name: Template +- URL: ./document.html + id: content/document + name: Document - URL: ./metadata.html id: content/metadata name: Metadata diff --git a/jqt.1.gz b/jqt.1.gz index 57e3b514c46f58cdd5b668a60fee6eea5dcadf08..10d7b4da89271f65cd9afb8ef7ef490f0aad2fb1 100644 GIT binary patch literal 1294 zcmV+p1@ZbHiwFREp|)251FcuxQtLJlzSmRia1}b>!0F*!FqCOXQWA!cGzrWwkPF#f zC!)4xB$=O1U#PFqC+kYKLqbeA)6)w=By0aZ?e}@(O?$9&@%wZKb`I&UmCxbJ!QnUh zdV@*}nZkkh#XF$&!z1`yV+haagTW+=xk12mE>hfK-lPXttwEQ0qY=B0?#^ZpkB0uw z;QkKN8Emt5#*^Et;b_vIY&y7;nW04V3{F6#k%$paL7~oLLx($XK%e%@M^-;z^O*&^ zbF2IPgK|t;ShUpd=6u{h2-E0O1<&F(>3r`GgGZgBs5v{MNthvN7@y0+||%Ty<3t zDVY=w?4b`lbj!Mzv|9myM}|_gxn>Gi_TRxk2N=F&)Jk-{m7h8skab_^P6Jc49OXw@ z(&f4+lH7*mvc@hd)MEv^lqU#uJB6cV#R(c-HgHjR)nb7XnbE8fV#JBGx`ehpb2->E zb@}#6Y%0oZVl&5-7-#H;>$fE)6&39+ixi*R{B&KAh3(uz6<9}T0`HYdv~;0JgmaBa zA3FVUw>=$>Z&{1DLmYP1E_Yqgmh}rOqan!X-7OMwvCzboh=oF7V5BOA!bi%TTU7}i zz#JZJ-vpu2>MM=l$>k@rNZ@%B)9J9Zb|Pco^@k9oZO zk62N_5+T??h}9t!IxQ70Wm=FJaw^GpouDmYY|42m9`jnhCjV=u8aR96agG*K=|2#r z>%v!)LHaTCN$!YZ7V0Ja>sb#=*0YNBz6@VKBK_!7(tp1gRzB+DWNf79J-h6(5t+yU zco1M_t18Eh8cRibpU5X%7f`46Rlpjn$rhpi^i5YVf)$9?Rb$wc#*nhF0(Zr0+0oT( z$?c}l!18Uql)>ulO#@do1gsd-7+^bbIRrFwt(vh6c-+(ruCPfnQZp7l{qqu%Cz^$L zEdDHJ2{*ynHgf$i&$8ME+~$)0wmU7l@cVrJL>Ug;D1a~A&On9UZp)C$Kf69JM&bz~ zoD0*-eImThQ6Iy}!kA1SH=A>sw{qVLWYUa?iJ^1>i({wGP3wBv8;&<;%V(nOvl4WF zZm_$MJf#nf84OiOqoIbe)SR6>$YS~HJmDg?kxq*#tvwvwj{E1msq@{I*{c%sg@J$m zw!b5eKJw_Tr$G`HivUym10i?KX}fXIpH|z@2x#)!bz)}e*KXhMpWWW?|Lh&S9jQdZ zy@Tyfif$KLmy_XJ*#vRpaMy<1gEE0~y$Q`ik_u%+krki|biEb4EzqazU%~eT2SyD5 E0D1*~LjV8( literal 1294 zcmV+p1@ZbHiwFP?uC!MG1Fcuva^gl1eb-lX`N>YL!A^Gb;M%x?fh=qpLx6Ra%kVHr z4U8jc~QT?f0YX?InJK%TyDR9OsvWbWm<)7j7(RwVAy8wiRLt7O~#59(|%#W&@ubiQVqpY6YZ0S5wp$WTg1Z>6UW2M)Rq$Z2Scl7oNn z63O*e6x2pgStGYB*uy0^6$um4QfSzOny?jR5seZ>2Q1%w9qx^ULWpe*GKL8eeDP|BDH*xKR_2tgDzPHk<=VorAvxfFnkw| zPa==7Ov5;jfHug^)c7K4FzkFm_4Uhx&Jd{FJ5;>#-XJ9}Tc}3cO{wj~r@EhHO55+# zc>W);g256Y+CeC&Ln!hrD!t2CfCln<#0I{OPkhU^B8Y8wr;BTgiwo+jT$HJ!wN0f9 z4^MzHr5Gg_)BZM#ppN7!1%XAhaB?|9TKGyZu4A0bc`9%7+D=XWS5FOz;7-IjJ51H$ z2AFPBUX2H7P0xej&|41UP2+!azb{nu_-eb4zS{2JPJoq;Iy+e~(zshU^)-Ts3Q2?^ zXD+OA#Hf+f;P^z{@iu9ChOZ3PNKM`#_pjb=MK1&eq;=8QV2aVBtf>f(PUjH}<(;O63Q=0-PT6^giN)AB3BG3Z{L_Lxg|!RPnhYG zw7q&vt^9PiGP_h{C8Es;Mz z%zaiO#h2lXhC0GHXlSgA2tMAZV)^ST5i)j`PK(K`Jse$)`=5GKue+_XM=e)tOaJ`s z{yThlO=Dx*4UktXLr&eFg4`FUtHwcpT5Z#Qh-vG<)0k_&c6)Ysb~QWvsd4mlq+$tw z`?|jo-7dAxC&Q<(0rCFvfiwAzN(ajIE;MTe8p_Zj&wwt_Z9K!<0eu?$3#Wk+g*puY E0KD^oz5oCK