diff --git a/docs/content/document.md b/docs/content/document.md index 1f6e934..1140bb2 100644 --- a/docs/content/document.md +++ b/docs/content/document.md @@ -15,7 +15,7 @@ to the render stage. This is described on the middle of this diagram: <%include "FLOW.md"> -When invoking `jqt` you cas use the following options to influence the document +When invoking `jqt` you can use the following options to influence the document conversion: <%include "opt/4.md"> @@ -31,7 +31,7 @@ Document files contains 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 begining of the file, +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`. @@ -50,7 +50,7 @@ and the second does the proper conversion to HTML. ### Preprocessing -The MarkDown input content is preprocessed using [GPP][GPP]. All the expected options are available, +The MarkDown input content is preprocessed using [GPP][GPP]. All the expected options in a macro processor are available, like defining new macros, include other files, etc. For example, a macro call like `<%include "../VERSION">` will expand to he string <%include "../VERSION"> as you can see in this paragraph and on the top of these pages. diff --git a/docs/content/engine.md b/docs/content/engine.md index 3d54312..c239500 100644 --- a/docs/content/engine.md +++ b/docs/content/engine.md @@ -55,7 +55,7 @@ happen. You can also change the installation directory: $ sudo make install prefix=/your/installation/path ``` -But if you choose a directory diferent of `/usr/local/share` for the shared data +But if you choose a directory different of `/usr/local/share` for the shared data you must still edit the parameter `DATADIR` definition in the `bin/jqt` file. ## Invoking _jqt_ diff --git a/docs/content/metadata.md b/docs/content/metadata.md index d52fd0b..4f27997 100644 --- a/docs/content/metadata.md +++ b/docs/content/metadata.md @@ -10,7 +10,7 @@ updated: "2016-08-13T07:48:26Z" 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] to be merged with +files in [YAML][YAML] or [JSON][JSON] format to be merged with the front matter. This is described on the bottom of this diagram: <%include "FLOW.md"> @@ -34,7 +34,7 @@ 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 are available, like +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 @@ -42,11 +42,12 @@ defining new macros, include other files, etc. The macro syntax used by _jqt_ in JSON files is different for predefined macros and for user defined macros: -* The predefined macro names are preceded with the characters <! and the macro calls finishes with the character `>`. -* 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 witht arguments are preceded with the - character `&`, followed by the character `(`, with arguments separated by +* The predefined macro names are preceded with the characters + <! and the macro calls finishes with the character `>`. +* 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 commas (`,`), and the macro calls finishes with the characters `);`. The more common predefined macros have this syntax: @@ -69,6 +70,13 @@ The more common predefined macros have this syntax: Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2`, etc.): +``` + + + +{ "price": "&price(100);" } +``` + #### Skips The main use of the preprocessor is to remove comments in the CPP style: @@ -78,6 +86,8 @@ The main use of the preprocessor is to remove comments in the CPP style: // 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). This table summarize all the available skips in JSON files: Delimiters Macro expansion Delimiters removed Content removed @@ -97,7 +107,7 @@ is, the backslash and the newline are removed and effectively ignored). ### Data conversion When preparing data inputs sometimes you need to mix files in several formats. -To make easy integrate metadata from several sources _jqt_ comes with the +To make easy the integration of metadata from several sources _jqt_ comes with the following utilities to convert between CSV, JSON and YAML formats: * `csv2json` @@ -116,8 +126,8 @@ Sometimes you want to apply queries in the _jq_ style to CSV or YAML files, in the same style as _jq_ processes JSON data. As a wrappers to `jq` you have the following utilities shipped with _jqt_: -* `cq` -* `yq` +* `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: diff --git a/docs/content/template.md b/docs/content/template.md index 16e54a7..70d735b 100644 --- a/docs/content/template.md +++ b/docs/content/template.md @@ -16,7 +16,7 @@ This is described on the top of this diagram: <%include "FLOW.md"> -When invoking `jqt` you cas use the following options to modify the template +When invoking `jqt` you can use the following options to modify the template rendering: <%include "opt/D.md"> @@ -37,7 +37,7 @@ This is a complete template example: ### Preprocessing -Templates are preprocessed using [GPP][GPP]. All the expected options are available, +Templates are preprocessed using [GPP][GPP]. All the expected options in a macro processor are available, like defining new macros, include other files, etc. For example, a template fragment like @@ -161,7 +161,7 @@ The rules for expression evaluation are very simple: * If an expression evaluates to `empty` the whole line vanishes. * If an expression produces only one value the snippet is replaced with this value. * If an expression produces multiple values the whole line is repeated multiple - times, whith the expression evaluated again each time. + times, with the expression evaluated again each time. #### Actions