Skip to content

Commit

Permalink
Unified documentation for JSON and CSS macros
Browse files Browse the repository at this point in the history
  • Loading branch information
@fadado
fadado committed Mar 29, 2017
1 parent 89a0674 commit 582625d
Show file tree
Hide file tree
Showing 4 changed files with 48 additions and 105 deletions.
7 changes: 4 additions & 3 deletions docs/content/content.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -105,9 +105,10 @@ 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
the input MarkDown document. The macro syntax used by _jqt_ in templates and 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 character `>`.
Here are some of the predefined macros:

```HTML
<%defeval x y>
Expand Down Expand Up @@ -168,7 +169,7 @@ Fenced code blocks with tildes (~~~) or backticks (```)
```
~~~

This table summarizes all the available document skips:
This table summarizes all the available skips:

Delimiters Macro expansion Delimiters removed Content removed
------------- --------------- ------------------ ---------------
Expand Down
46 changes: 38 additions & 8 deletions docs/content/data.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,17 +62,17 @@ are provided:
Additional JSON files can be provided and are merged with front matter metadata
to be the `jq` input in the render stage.

### JSON preprocessing
### Preprocessing

JSON files are preprocessed using [GPP][GPP], and all the expected options in a
preprocessor are available, like defining new macros, include other files, etc.
CSS files are also preprocessed with the same macros syntax used in JSON files.

#### Macro calls

The macro syntax used by _jqt_ in JSON files is very similar to the syntax used by the traditional
TeX language macro processor, but changing the prefix character `\\` by
`&`.
The more common predefined macros have this syntax:
The macro syntax used by _jqt_ in JSON and CSS files is very similar to the syntax used by the traditional
TeX language macro processor, but changing the prefix character `\\` by `&`.
Here are some of the predefined macros:

```
&defeval{x}{y}
Expand All @@ -95,17 +95,26 @@ but named arguments are also possible.
The more used features are the inclusion on external files and the definition of simple constants:

```JSON
// JSON example
&define{eur}{\u20AC}
&define{price}{$1 &euro}

{ "price": "&price{100}" }
```

```CSS
// CSS example
&include{theme.css}
&define{Blue}{#0000FF}

{ color: &Blue; }
```

Warning: you must see 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:
One use of the preprocessor is to remove comments in the C and C++ languages style:

```CPP
/* Block comments */
Expand All @@ -114,7 +123,7 @@ The main use of the preprocessor is to remove comments in the CPP style:

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:
This table summarizes all the available skips:

Delimiters Macro expansion Delimiters removed Content removed
------------- --------------- ------------------ ---------------
Expand All @@ -123,12 +132,33 @@ This table summarizes all the available skips in JSON files:
`//` `\n`[^2] No Yes Yes
`` ` `` `` ` `` No Yes No
`"` `"` Yes No No
`'` `'`[^3] Yes No No

Table: **Semantics for all JSON and CSS skips**

Table: **Semantics for all JSON skips**
Observe that single quote strings are defined only for CSS files.

[^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.
[^3]: Only for CSS files.

#### CSS preprocessor

_jqt_ offers an standalone CSS preprocessor. Macros can be defined, files included, etc.

<details>

<summary>
To enable CSS preprocessing the `-P` option must be used with the `css` or `css-min` options:
</summary>

<%include content/opt/P.txt>

</details>

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

## Tools

Expand Down
94 changes: 3 additions & 91 deletions docs/content/engine.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,14 +111,10 @@ all kinds of input files.
Also, _jqt_ can be used as a standalone
preprocessor thanks to the `-P` option.

### Files preprocessed

The pages about templates, documents and data cover in
detail the usage of the preprocessor for
[_jqt_ templates](./structure.html#preprocessing),
_jqt_ uses two different syntaxes for macros, one for
[_jqt_ templates](./structure.html#preprocessing) and
[MarkDown documents](./content.html#preprocessing)
and [JSON data files](./data.html#json). _jqt_ can also expand CSS style sheets; this is documented
in the following section because it is outside the normal _jqt_ processing work flow.
and another for [JSON and CSS](./data.html#preprocessing) files.

<details>

Expand All @@ -132,90 +128,6 @@ of YAML files for collections of MarkDown snippets:

</details>

### CSS preprocessing

_jqt_ offers an standalone CSS preprocessor. Macros can be defined, files included, etc.

<details>

<summary>
To enable CSS preprocessing the `-P` option must be used with the `css` or `css-min` options:
</summary>

<%include content/opt/P.txt>

</details>

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

#### Macro calls

The macro syntax used by _jqt_ in CSS files is very similar to the syntax used by the traditional
TeX language macro processor, but changing the prefix character `\\` by
`&`.
The more common predefined macros have this syntax:

```
&defeval{x}{y}
&define{x}{y}
&elif{expr}
&else
&endif
&eval{expr}
&if{expr}
&ifdef{x}
&ifeq{x}{y}
&ifndef{x}
&ifneq{x}{y}
&include{file}
&undef{x}
```

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

```CSS
&include{theme.css}
&define{Blue}{#0000FF}

{ color: &Blue; }
```

Warning: you must see the [GPP manual][GPPMAN] if you want to know all the gory details.

#### Skips

Some fragments of text are skipped during macro expansion, like comments and
other delimited strings of characters. One use of the preprocessor is to
remove in CSS files comments in the style of C and C++ languages:

```CPP
/* Block comments */
// Line comments
```

Quoted strings are also defined as skips, and backticks can be used to
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
------------- --------------- ------------------ ---------------
`&\n`[^1] No Yes There is no content
`/*` `*/`[^2] Yes/No No/Yes No/Yes
`//` `\n`[^3] No Yes Yes
`` ` `` `` ` `` No Yes No
`"` `"` Yes No No
`'` `'` Yes No No

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]: Multiline comments are expanded and preserved when not minifying CSS.
[^3]: This represents a newline character.

<#
vim:ts=4:sw=4:ai:et:fileencoding=utf8:syntax=markdown
#>
6 changes: 3 additions & 3 deletions docs/content/structure.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,9 @@ as you can see in the internal code of this page.

#### Macro calls

The macro syntax used by _jqt_ precedes macro names with the characters `<%`
The macro syntax used by _jqt_ in templates and MarkDown documents precedes macro names with the characters `<%`
and finishes the macro calls with the character `>`.
The more common predefined macros have this syntax:
Here are some of the predefined macros:

```HTML
<%defeval x y>
Expand Down Expand Up @@ -149,7 +149,7 @@ be enabled or disabled. String delimiters can be copied, or not, to the output:
All jqt template delimited regions: {#...#}, {%...%}, {{...}}
~~~

This table summarizes all the available template skips:
This table summarizes all the available skips:

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

0 comments on commit 582625d

Please sign in to comment.