D.1 | rivt Markup#
[1] API methods#
rivt has seven API methods. The name rivt is an acronym taken from four functions that process content. The remaining functions are used for document generation and debugging.
Content APIs- [R]un Runs Python scripts and markup.
- [I]nsert Adds static tables, images and equations.
- [V]alues Evaluates equations and functions.
- [T]ools Executes shell scripts and external programs.
Publish APIs
- [D]oc specifies the doc type and style.
- [S]kip, e[X]it can be used for interactive debugging and comments.
API Function |
Name |
Purpose |
|---|---|---|
rv.R (rS) |
Run |
Run external binary programs |
rv.I (rS) |
Insert |
Insert static sources |
rv.V (rS) |
Values |
Calculate values |
rv.T (rS) |
Tools |
Process text scripts |
rv.D (rS) |
Doc |
Publish docs |
rv.S,X (rS) |
Skip, Exit |
Skip section, exit (comments, debugging) |
There are several settings that a apply to the entire rivt file. These are specified in the comment settings immediately following the import statement. Default settings do not need to be specified - only variants.
import rivtlib.rvapi as rv
# rv private = false ; default section parameter changed to public (true)
# rv no_tag = true ; API type is added to section number (true)
# rv set_width = true character width of text output (80
If interactive IDEs are used rv.S and rv.X can be used for debugging and cell notation can be used for navigation. Note that Ctrl+Alt+C inserts the navigation cell label (# %%) if the cursor is on the first line of the cell and the rivt Profile is installed in VSCode.
# %% My Section Label
rv._("""My Section Label
Content text and rivt markup - indented four spaces.
...
""")
[2] rivt string Header#
Individual API methods define sections. Each API function takes a raw, triple quoted rivt string composed of a header substring on the first line followed by a multi-line content substring. The header line defines section processing parameters. The content substring includes rivt markup and is indented four spaces for improved readability and navigation (e.g. section folding). rivt markup commands and tags will vary depending on the API function.
The header substring starts with a section label, also used as the section title, followed by section parameters that override default behavior. All parameters are optional and may be omitted if defaults are acceptable. If any parameters are specified the vertical bars bracketing the file name are required.
The header substring specifies the section title and other processing parameters. The first set of parameters modify section processing. The second parameter provides the option for a template file or script that is processed in addition to the content substring if provided.
The API method header has two general forms: Default and Modified. The default form is used when the header substring accepts default parameters. It only requires a section label. The modified form is used when default parameters need to be modified.
Header Defaults
rv._("""Section Label
Content text and rivt markup - indented four spaces.
...
""")
Header Modifications
rv._("""Section Label | shmpn | type | template or script file
Content text and rivt markup - indented four spaces.
Content may be ommitted if a template file or script
is specified.
...
""")
The first set of parameters in the header substring specify handling of the content substring. The second and third parameters specify a type and file or script that is processed by the API method before processing any content.
Parameters
Section parameters may be specified in any order or ommitted if defaults are acceptable. The default parameters are shown in the
s stores the section content in _rvstored/sect as a .rvt file.
h processes the section but suppresses the doc output.
m merges the section with the previous section.
p toggles the public/private status of the section. The rivt file default is private unless overridden by a comment settings
n Starts a new pdf page.
File and Type Settings
The second parameter specifies a template file or script that is processed by the API method before processing any content. The file is read from the rvsrc/data folder unless a relative path is specified. The file type is determined by the API method. The type setting for all API methods, except rv.T, is rvt. A rvt file type is a section content string stored as a file. It is written by the s parameter.
For the rv.T method the type settings are:
PYTHON - run Python script
python - insert Python script
text - literal text
rst - reStructuredText
html - HTML markup
mermaid - Mermaid diagram (requires mermaid installation)
latex - LaTeX (requires LaTeX installation)
[3] rivt String Content#
The content substring is indented four spaces for legibility and code folding. It includes line tags, block tags and commands along with text.
rv._("""Section Label
Content text indented 4 spaces.
...
""")
Content is converted line by line into formatted text and RestructuredText, and then further processed into HTML or PDF. If a line does not contain a command, tag or assignment it is passed through as is. This allows the Insert function (rv.I) to include some restructured text directly i.e. surrounding words with * or ** will format a word as italic or bold.
In addition block tags in the Tools function (rv.R) directly supports processing HTML, LaTeX and reStructuredText scripts.