Skip to content

Commit

Permalink
Revised english
Browse files Browse the repository at this point in the history
  • Loading branch information
@fadado
fadado committed Sep 3, 2016
1 parent f5a02fb commit 464ff0d
Show file tree
Hide file tree
Showing 27 changed files with 181 additions and 173 deletions.
6 changes: 3 additions & 3 deletions docs/content/FLOW.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ Template +----------->|expand|-->|convert|-------------------------------+
|
HTML and CSS |
fragments v
MarkDown +------+ +------+ /-------->+-----+ JSON +------+
Document +----------->|expand|-->|markup|--+ |merge|-------->|render|--> HTML
+------+ +------+ \-------->+-----+ +------+ page
MarkDown +------+ +------+ /-------->+-----+ JSON +------+ HTML
Document +----------->|expand|-->|markup|--+ |merge|-------->|render|-------> Page
+------+ +------+ \-------->+-----+ +------+
YAML ^ ^
front-matter | |
metadata | |
Expand Down
45 changes: 23 additions & 22 deletions docs/content/content.md
View file
Original file line number Diff line number Diff line change
@@ -1,49 +1,48 @@
---
title: Document content
title: Authored content
updated: "2016-08-28T10:27:09Z"
---
<%include "macros.m">&
<%include "LINKS.txt">&
<%include macros.m>&
<%include LINKS.txt>&

## General operation

_jqt_ transforms [MarkDown][MARKDOWN] documents to HTML using Pandoc,
but before [GPP][GPP] is used to preprocess them. Pandoc's output
but before that [GPP][GPP] is used to preprocess them. Pandoc's output
is then merged with the [YAML][YAML] front matter metadata and other input data before be sended
to the render stage. This is described on the middle of this diagram:

<%include "FLOW.txt">
<%include FLOW.txt>

When invoking `jqt` you can use the following options to influence document
conversion:

<%include "opt/4.txt">
<%include "opt/D.txt">
<%include "opt/d.txt">
<%include "opt/I.txt">
<%include opt/4.txt>
<%include opt/D.txt>
<%include opt/d.txt>
<%include opt/I.txt>

## File structure

Document files contain MarkDown text preceded by an optional YAML front matter.

### Front matter

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 `.page`.
_jqt_ extracts the YAML front matter, located at the very beginning of the file,
and injcontent. ects it into the render stage under a global JSON object named `.page`.

### Body

Pandoc converts the document body to HTML,
and _jqt_ injects it into the render stage under the global JSON scalar
`.page._content`. If the document contains fenced code blocks specifying the language of
the code block, the highlight code will be in the scalar `.page._highlight`. Also, the
table of contents is available in the scalar `.page._toc`, and the path to the document
the code block, the related highlight CSS code will be in the scalar `.page._highlight`. Also, the
HTML table of contents is available in the scalar `.page._toc`, and the path to the document
file in the scalar `.page._path`.

## Document syntax

The document conversion has two stages. In the first text is preprocessed,
Document's conversion has two stages. In the first the text is preprocessed,
and the second does the proper conversion to HTML.

### Preprocessing
Expand All @@ -57,7 +56,7 @@ 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 document. The macro syntax used by _jqt_ in input documents precedes macro names with the characters `<%`
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:

Expand Down Expand Up @@ -88,7 +87,7 @@ Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2
Predefined macros and user define macros have the same call sequence:

```
<%include "LINKS.txt">
<%include LINKS.txt>
<%sc 'A title in small caps'>
```

Expand All @@ -101,7 +100,8 @@ continuation lines and arbitrary but delimited strings of characters:

```
<# Block comments, removed, must end in newline (also removed) #>
Continuation lines using an ampersand just before the newline character&
Continuation lines using an ampersand &
just before the newline character
```

_Strings_ are copied to the output, but evaluation of macros inside strings can
Expand Down Expand Up @@ -130,7 +130,7 @@ This table summarizes all the available document skips:
<code>\\n&#96;&#96;&#96;</code>[^4] No No No
`\n~~~`[^5] No No No

Table: **Semantics for all document skips**
Table: **Semantics for all MarkDown document 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).
Expand All @@ -142,9 +142,10 @@ is, the ampersand and the newline are removed and effectively ignored).
### Pandoc’s Markdown

_jqt_ accept as input format the [Pandoc's MarkDown](http://pandoc.org/MANUAL.html#pandocs-markdown)
variant, with the title block extension disabled, and produces transitional
HTML. When running `jqt` the following Pandoc long options can be specified in
the command line and will be forwarded to `pandoc`:
variant, with the <a href="http://pandoc.org/MANUAL.html#extension-pandoc_title_block">title block extension</a>
disabled, and produces transitional HTML. When running `jqt` the following
Pandoc long options can be specified in
the command line and will be forwarded untouched to `pandoc`:

```
--base-header-level=NUMBER --latexmathml[=URL]
Expand Down
21 changes: 11 additions & 10 deletions docs/content/data.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
title: Data model
updated: "2016-08-28T10:27:09Z"
---
<%include "macros.m">&
<%include "LINKS.txt">&
<%include macros.m>&
<%include LINKS.txt>&

## General operation

Expand Down Expand Up @@ -32,7 +32,8 @@ data and influence JSON preprocessing:
### YAML

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 and merged to be the `jq` input in the render stage. No preprocessing is
applied to YAML data.

The front matter content is available in the global object `.page`. The object
member names prefixed with the underline character (`_`) are reserved, and the following
Expand All @@ -57,10 +58,10 @@ 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 with arguments are preceded with the
character `&`, then followed by the character `(`, accept arguments separated by
* The user defined macro names are preceded with
the character `&` and for calls without arguments the macro calls finishes with the character `;`.
* For calls with arguments the user defined macro names are
followed by the character `(`, arguments separated by
commas (`,`), and the macro calls finishes with the character `)`.

The more common predefined macros have this syntax:
Expand Down Expand Up @@ -101,7 +102,7 @@ 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
Double quoted strings are defined as skips, and backticks can be used to
disable macro expansion (inside double quoted strings backticks are ignored).
This table summarizes all the available skips in JSON files:

Expand Down Expand Up @@ -146,7 +147,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:
These utilities imitate the `jq` command line interface:

```
$ yq '.store.book[2]' tests/data/store.yaml
Expand All @@ -159,7 +160,7 @@ title: Moby Dick
...
```

You can also ask for JSON output:
You can also preserve `jq` JSON output:

```
$ yq --json -c '.store.book[2]' tests/data/store.yaml
Expand Down
77 changes: 38 additions & 39 deletions docs/content/engine.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,18 @@
title: Operating the engine
updated: "2016-08-28T10:27:09Z"
---
<%include "macros.m">&
<%include "LINKS.txt">&
<%include macros.m>&
<%include LINKS.txt>&

## General operation

_jqt_ orchestrates several shell utilities to transform [MarkDown][MARKDOWN] text and
[YAML][YAML] or [JSON][JSON] data into a final HTML document. The transformation is driven by a template,
[YAML][YAML] or [JSON][JSON] data into a final HTML page. The transformation is driven by a template,
where HTML is mixed with [_jq_][JQ] snippets to implement the transformation logic.
This diagram shows how document, template and data inputs (on the left) are combined by
_jqt_ to produce the final HTML output:

<%include "FLOW.txt">
<%include FLOW.txt>

The command `jqt` is a shell script executed by `bash`.
The external shell commands called by `jqt` are `cat`, `gpp`, `jq`, `mkdir`,
Expand Down Expand Up @@ -55,13 +55,13 @@ $ sudo make install prefix=/your/installation/path
```

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.
you must still edit by hand the parameter `DATADIR` definition in the `bin/jqt` file.

## Invoking _jqt_

### Synopsis

`jqt` accepts several options and can be called with zero, one or two file
`jqt` accepts several options and can be called with zero, one or two filename
arguments. The usage possibilities are:

| **jqt** [**-h** | **--help** | **-p** | **-V** | **--version**]
Expand All @@ -71,32 +71,32 @@ arguments. The usage possibilities are:

### Options

<%include "opt/4.txt">
<%include "opt/C.txt">
<%include "opt/D.txt">
<%include "opt/d.txt">
<%include "opt/e.txt">
<%include "opt/H.txt">
<%include "opt/h.txt">
<%include "opt/I.txt">
<%include "opt/i.txt">
<%include "opt/j.txt">
<%include "opt/L.txt">
<%include "opt/M.txt">
<%include "opt/m.txt">
<%include "opt/n.txt">
<%include "opt/P.txt">
<%include "opt/p.txt">
<%include "opt/r.txt">
<%include "opt/S.txt">
<%include "opt/T.txt">
<%include "opt/t.txt">
<%include "opt/V.txt">
<%include opt/4.txt>
<%include opt/C.txt>
<%include opt/D.txt>
<%include opt/d.txt>
<%include opt/e.txt>
<%include opt/H.txt>
<%include opt/h.txt>
<%include opt/I.txt>
<%include opt/i.txt>
<%include opt/j.txt>
<%include opt/L.txt>
<%include opt/M.txt>
<%include opt/m.txt>
<%include opt/n.txt>
<%include opt/P.txt>
<%include opt/p.txt>
<%include opt/r.txt>
<%include opt/S.txt>
<%include opt/T.txt>
<%include opt/t.txt>
<%include opt/V.txt>

## Preprocessing

One distinctive feature of _jqt_ is the text expansion applied to almost
all kind of input files.
all kinds of input files.
Also, _jqt_ can be used as a standalone
preprocessor thanks to the `-P` option.

Expand All @@ -107,27 +107,27 @@ The sections about
[documents](./content.html#preprocessing) and [data](./data.html#json) cover in
detail their usage of the preprocessor.

A different transformation can also be be considered a kind of preprocessing. The option
_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:

<%include "opt/T.txt">
<%include opt/T.txt>

### CSS preprocessing

As a bonus, _jqt_ can also expand CSS style sheets. This is documented in this
section because it is outside the _jqt_ normal processing work flow.
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:

<%include "opt/P.txt">
<%include opt/P.txt>

You can minify the CSS style sheet choosing the `css-min` option.
The CSS minimization is not extremely aggressive, but is safe and sufficient.

#### Macro calls

The macro syntax used by _jqt_ in CSS files is very similar to used by the traditional
`cpp` preprocessing of C and C++ languages, but changing the prefix character `#` by
The macro syntax used by _jqt_ in CSS files is very similar to the syntax used by the traditional
preprocessing of C and C++ languages, but changing the prefix character `#` by
`&`.
The more common predefined macros have this syntax:

Expand All @@ -148,11 +148,10 @@ The more common predefined macros have this syntax:
```

Inside macro definitions argument references are prefixed by a dollar (`$1`, `$2`, etc.).
The more common used features are the inclusion on external files and definition of simple constants:
The more used features are the inclusion on external files and the definition of simple constants:

```
&include "theme.css"
&include theme.css
&define Blue #0000FF
{ color: &Blue; }
Expand All @@ -170,8 +169,8 @@ The main use of the preprocessor is to remove comments in the CPP style:
```

Quoted strings are also defined as skips, and backticks can be used to
disable macro expansion (inside double quoted strings backticks are ignored).
This table summarizes all the available skips in JSON files:
disable macro expansion (inside quoted strings backticks are ignored).
This table summarizes all the available skips in CSS files:

Delimiters Macro expansion Delimiters removed Content removed
------------- --------------- ------------------ ---------------
Expand Down
Loading

0 comments on commit 464ff0d

Please sign in to comment.