C.1 Markup#

<i>

[1] rivt String#

A rivt string is a utf-8 text triple quoted string argument to an API function. It may include rivt markup, a readable, plain text language that generates formatted text, PDF or HTML docs. The different doc types are generated from the same rivt file.

The first line of a rivt string is a header, followed by text indented 4 spaces for improved readability and section folding.

rv._("""Section Label | show;hide, private;public, section;merge

    section text (utf-8 text)

    ...

    """)

The rivt string begins with an API header that includes a “section label” and section formatting parameters.

<i>

[2] API Header#

An API header starts with a section label followed by comma separated section parameters that may override default behavior. The section label is the section title and is separated from the section header paramaters by a vertical bar. Parameters include the following:

  • private/publicdetermines whether the API section text is copied to the

    the /public folder rivt file for sharing.

  • print/storedetermines whether the rivt string is formatted and printed

    in the doc or just annotated and written to a file for optional inclusion as an appendix. eps

  • section/mergedetermines whether the API starts a new doc section

    or is merged into the previous section.

Default settings do not need to be specified in the header. In the table below, the default setting for each API is listed first (in bold).

API

private;public

print;store

section;merge

rv.R

private;public

store;print

merge;section

rv.I

private;public

print;store

section;merge

rv.V

private;public

print;store

section;merge

rv.T

private;public

store;print

merge;section

rv.D

private;public

store;print

merge;section

rv.S

private;public

store;print

merge;section

rv.X

private;public

store;print

merge;section

Examples of header settings are shown below.

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

    Section text (utf-8 text)

    ...

    """)

For the Insert API - rv.I(), the following syntax is equivalent:

rv.I("""A New Section

    Section text (utf-8)

    ...

    """)

<i>

[3] Section Text#

Section text is indented four spaces for legibility and code folding. It includes rivt tags that format lines of text and rivt commands that operate on files.

rv._("""Section Label | write; nowrite, public; private

    Section text
    ...

    """)

A section is processed line by line into formatted text and RestructuredText, 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, which allows for including some restructured text directly. For example surrounding words with * for italics or ** for bold.

In addition the Tools API function (rv.T) supports inserting raw Python, HTML and LaTex. Since it can be hid from the primary textual content of the file rv.T() improves readability.

<i>

[4] Tags and Commands#

Tags

A line tag formats a line of text and is denoted with _[LETTER], generally placed at the end of the line for readability.

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 file path, name and parameters. The exceptions to this pattern are the assignment (<= ) and definition (:=) commands, which are used to assign values to equation results and define variables.

| COMMAND | relative path | parameters

File paths are specified relative to the report folder or rivt file folder. The typical rivt report folder structure is described here.

<i>

[5] Markup Key#

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

_[TAG] : description of line tag

outputs: types of output

_[[TAG]] : description of block tag

file types

COMMAND | description of command

file types

<i>

[6] Metadata#

Metadata is stored in the file rivtmeta.py. If used, it is imported prior to rivtlib and provides author information and specifies whether the rivt file is a single doc or part of report. Metadata is specified using standard Python data types. See here for further details.

Variable

Description

rv_authD

specifies author information

rv_localB

True; False [default] if True resource files are local

rv_authD is a dictionary that pecifies the author, version, email, repository and license information and forks.

# default - author dictionary
rv_authD = {
        "authors": "",
        "version": "0.0.0",
        "email": "",
        "repo": "",
        "license": "https://opensource.org/license/mit/",
        "fork1": ["author", "version", "email", "repo"],
        "fork2": ["author", "version", "email", "repo"],
        }

# example - author dicitionary
rv_authD = {
        "authors": "rholland",
        "version": "0.6.1",
        "email": "rod.h.holland@gmail.com",
        "repo": "https://github.com/rivt-info/rivt-simple-doc",
        "license": "https://opensource.org/license/mit/",
        }

rv_localB overrides the default report structure and specifies that all resource files are read from and written to the rivt file folder instead of rivt folders. It is intended for simple, single docs with more limited formatting options.

# default setting uses report folders
rv_localB = false

# resource files are read from and written to the rivt file folder
rv_localB = true