C.1 Markup#
<i>
[1] rivt String#
rivt markup is a readable, plain text language that generates formatted text, PDF or HTML docs from the same rivt file. The markup is included in a rivt string - a utf-8 text string argument of a API function.
The API function and header start in the first column (standard Python syntax), with subsequent lines indented 4 spaces for improved readability and section folding in IDEs.
rv._("""Section Label | print;hide, private;public, section;merge
section text (utf-8 text)
...
...
""")
The rivt string begins with a section header that includes a “section label” and parameters that define the section behavior.
<i>
[2] Header#
A header starts with a section label followed by a vertical separator bar and section parameters that override the section default behavior. The section label is the section title.
Section parameters specify the following settings:
print: formats section text to doc
hide: evaluates the content but does not print the formatted content
public: copies section content to public rivt file
merge: merges formatted section content to previous section
history: writes section label and parameters to api-history file
The table below summarizes the section parameter settings, with the default setting shown first. A parameter only needs to be specified if different from the default.
API |
public |
merge |
|
|---|---|---|---|
rv.M |
hide; print |
private; public |
section; merge |
rv.R |
hide; print |
private; public |
section; merge |
rv.I |
print; hide |
private; public |
section; merge |
rv.V |
print; hide |
private; public |
section; merge |
rv.T |
hide; print |
private; public |
section; merge |
rv.D |
hide; print |
private; public |
section; merge |
rv.S |
hide; print |
private; public |
section; merge |
rv.Q |
hide; print |
private; public |
section; merge |
Examples of header settings are shown below.
rv._("""Section Label | hide;print, public;private;
section content (utf-8 text)
...
...
""")
<i>
[3] Section Text#
Section text is indented four spaces (for legibility and code folding) and includes tags for text formatting and commands for file operations.
rv._("""Section Label | write; nowrite, public; private
section text
...
""")
A section is processed line by line to a RestructuredText string, and then further processed to an HTML or PDF file. If a line does not contain a command or tag it is passed through as is. This allows for including restructured text directly, e.g. surrounding text with * for italics or ** for bold. Text docs are formatted separately.
<i>