C.1 Markup#

<i>

[1] Metadata#

If Metadata is provided it is specified before any API functions are called. It uses standard Python dictionaries, lists and strings and provides author information and global file path handling. It is specified outside the rivtlib API functions.

Variable [1]

Description

rv_authD

dictionary specifies author information

rv_fork1D

dictionary specifies author fork information

rv_localB

true; [false] default - set resource files to local folder

[1] variables use the rivtlib code convention of data type indicated by suffix

rv_authD specifies the author, version, email, repository and license information and lists the forks. rv_forknD specifies data for the forked file. The rv_authD dictionary always precedes rv_forknD.

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

# 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/",
        "forks": ["rv_fork1D", "", "", ""],
        }

rv_forknD specifies author information for a rivt file fork.

#example - fork dictionary
rv_fork1D = {
        "authors": "",
        "version": "0.1.0",
        "email": "",
        "repo": "",
        }

<i>

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 relatively simple, single docs. Formatting is more limited.

# default setting uses report folders
rv_localB = false

# resource files are in rivt file folder
rv_localB = true

<i>

[2] 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>

[3] 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.

  • show/hidedetermines 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.

  • 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

show/hide

section/merge

rv.M

private; public

hide; show

merge; section

rv.R

private; public

hide; show

merge; section

rv.I

private; public

show; hide

section; merge

rv.V

private; public

show; hide

section; merge

rv.T

private; public

hide; show

merge; section

rv.D

private; public

hide; show

merge; section

rv.S

private; public

hide; show

merge; section

rv.Q

private; public

hide; show

merge; section

Examples of header settings are shown below.

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

    section content (utf-8 text)

    ...

    """)

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

rv.I("""A New Section

    section text (utf-8)

    ...

    """)

<i>

[4] 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>

[5] Tags and Commands#

Tags

A line tag formats a line of text and is denoted with _[TAG], usually at the end of the line.

A block tag formats a block of text that begins with _[[TAG]] and terminates with _[[Q]].

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>

[6] Markup Key#

_[TAG] : description of line tag

outputs: types of output

_[[TAG]] : description of block tag

file types

COMMAND | description of command

file types

<i>