D.1 Markup#

[1t] API functions#

rivt has seven API functions. The name rivt is an acronym taken from the four functions that process content. The remaining three functions are used for document generation and debugging.

Content APIs

[R]un executes shell commands.
[I]nsert adds static table, image, equation and text content.
[V]alues evaluates equations and functions.
[T]ools runs reStructuredText, HTML, LaTeX and Python scripts.

Publish APIs

[D]oc specifies the doc type and style.
[S]kip can be used for interactive debugging and comments.
e[X]it can be used for interactive debugging.

API Function	Name	Purpose
rv.R (rS)	Run	Run shell commands
rv.I (rS)	Insert	Insert static sources
rv.V (rS)	Values	Calculate values
rv.T (rS)	Tools	Python and markup scripts
rv.D (rS)	Doc	Publish docs
rv.S (rS)	Skip	Skip section (comments and debugging)
rv.X (rS)	Exit	Exit rivt (debugging)

API functions define doc sections. If interactive IDEs like VSCode or Spyder are used to edit and run rivt files, functions can be processed individually as cells by using the standard notebook hash notation:

# %% optional label
rv.API("""rivt string""")

[2t] rivt string#

Each API function takes a triple quoted rivt string argument composed of a line header substring line followed by a multiple-line content substring.

The header substring defines section processing parameters. The content substring includes rivt markup and is indented four spaces for improved readability and navigation (e.g. section folding).

Header substring

The header substring starts with a section label, used as the section title, followed by a vertical bar and three comma separated section parameters that override default behavior.

rv._("""Section Label | doc;stored, private;public, section;merge

     Content substring indented 4 spaces

    ...

    """)

The parameters include the following, in any order:

private/public: Determines whether the API section text is copied to the the Public folder rivt file for sharing.
doc/stored: Determines whether the rivt string is formatted and printed in the doc, or just annotated in the doc and written to a file in the Stored folder for optional inclusion as an appendix.
section/merge: Determines whether the API starts a new doc section or is merged into the previous section.

Default settings in the header substring do not need to be specified. The default setting for each API is listed first (in bold) in the table below. The default privacy settings for all sections in a rivt file may be reversed by including the public comment setting immeditely following the rivlib import statement. Individual sections may still be set as private in the header substring.

import rivtlib.rvapi as rv

# rv public=True

API	private; public	doc; stored	section; merge
rv.R	private; public	stored; doc	merge; section
rv.I	private; public	doc; stored	section; merge
rv.V	private; public	doc; stored	section; merge
rv.T	private; public	stored; doc	merge; section
rv.S	private; public	stored	merge
rv.D	public	stored	merge
rv.X

Examples of header substring settings are shown below.

An example with explicit defaults (they do not have to be declared).

# This

rv.I("""A New Section | private, doc, section

    Content text
    ...

    """)

# is equivalent to:

rv.I("""A New Section

    Content text

    ...

    """)

An example that merges a section into the previous section.

rv.I("""A Merged Section | merge

    Content text

    ...

    """)

Content substring

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 or tag it is passed through as is, which allows for the Insert function (rv.I) including some restructured text directly i.e. surrounding words with * or ** will format a word as italic or bold respectively.

In addition block tags in the Tools function (rv.T) directly supports processing HTML, LaTeX and reStructuredText scripts.

[3t] Tags and Commands#

Line Tags

A line tag formats a line of text and is denoted with a single _[LETTER], placed at or near the end of the line, depending on the tag.

Block Tags

A block tag formats a block of text and begins with _[[TAGNAME]] and terminates with _[[END]].

Commands

rivt commands read and write external files. They typically start in the first column with a vertical bar ( | ) followed by the command name, file path, and parameters.

The exceptions are the definition (==:), assignment (<=:), function (:=:) and compare (<>) commands that are used to define, assign and compare values.
| COMMAND | relative path | parameters
File paths are specified relative to the rivt root folder. The rivt report folder structure is described here.

If the path is ommitted the default path for each command is applied. If the singledoc parameter is set, the resource files and docs are stored in the rivt root folder.

Tag and Command syntax for each API type is defined and described using the following format:

Markup Key

_[TAG] or | COMMAND |

Description

    Syntax:
        _[TAG] or | COMMAND | syntax

    Example:
        This is a sentence. _[C]

[4t] Folders#

Folder Names

A rivt report folder can contain any set of files and folders but the following structure is required for doc processing. Files and folders are organized under a root folder with the prefix rivt- e.g. rivt-Report-Label.

The root folder includes at least the rivt files and five required subfolders. Required folders and prefixes are shown in brackets. Folders preceded by an underscore contain rivt outputs. Capitalized folder names contain files requiring author input.

The top level folder structure is shown below. A more detailed description of the folder structure is here.

Top Level Folders

[rivt-]Report-Label/                Report Folder
    ├── [conf.py]                   configuration file
    ├── [rv101-]filename1.py        rivt file
    ├── [rv102-]filename2.py        rivt file
    ├── [rv201-]filename3.py        rivt file
    ├── [rv202-]filename4.py        rivt file
    ...
    ├── .vscode/                    optional VSCode settings
    ├── [_publish]/                 published docs and reports
    ├── [_rstdocs]/                 restructured text files
    ├── [_shared]/                  public rivt files
    ├── [_stored]/                  stored files
    ├── [Src]/                      source files
    └── README.txt                  searchable text report