A.1 Introduction#

[1] Summary#

rivt is an open source software project that simplifies reuse of shared engineering documents. Collaboration reduces repetitive work and improves quality. Although a number of document software programs are available, reuse and sharing is generally not possible because of limitations in software terms of use and distribution:

documents come from many incompatible programs
document formats become obsolete and inaccessible
frequent software updates are needed
update costs are high
software is limited to specific platforms
version control is limited
report generation features are limited
collaboration features are limited

The table below summarizes these limitations and compares rivt with other software programs.

Table 1 - Limitations Comparison

Program	Rep [1]	Ver [2]	Txt [3]	Comp [4]	CP [5]	Collab [6]
Matlab	no	no	no	no	no	no
Mathcad	no	no	no	no	no	no
Mathematica	no	no	no	no	no	no
Cloud SaaS	limited	limited	no	no	yes	limited
Jupyter	no	no	no	yes	yes	yes
rivt	yes	yes	yes	yes	yes	yes

[2] rivt File#

A rivt file is a Python plain text file (.py) that imports the rivtlib library into the rv-namespace and defines an API:

import rivtlib.rvapi as rv

Each rivt file outputs a formatted rivt doc file as a text, PDF or HTML document. Reports are organized assemblies of docs.

The rivt API is designed to simplify document organization and publishing by implementing a flexible rivt markup language and standard folder structure. It is designed to combine text, tables, diagrams, models and calculations that are typically part of engineering documents.

[3] API#

rivtlib includes 8 API functions that may be run as a script or interactively as notebook cells in VSCode or other IDE.

The four content functions (R I V T) output formatted utf-8 text to the terminal and generate formatted doc content.

The Run API executes shell commands.

The Insert API adds static table, image, equation and text content.

The Value API evaluates equations and functions.

The Tool API imports HTML, LaTeX, and Python scripts.

The three processing functions (D S X) are related to processing and output. The Doc API specifies settings for publishing formatted docs. The Skip and Exit functions are used for interactive editing and debugging.

API Function	Name	Purpose
rv.R(rS)	Run	Run shell commands
rv.I(rS)	Insert	Insert static resources
rv.V(rS)	Value	Calculate values
rv.T(rS)	Tool	Import Python and Markup functions
rv.D(rS)	Doc	Publish docs
rv.S(rS)	Skip	Skip section
rv.X(rS)	Exit	Exit rivt

Each function takes a single rivt string (triple quoted string) argument.

[4] rivt String#

An API function starts in the first column and takes a single rivt string (rS) argument. The first line of a rivt string is a header that specifies section labeling and processing. The header is followed byvthe section text, indented four spaces for legibility and section folding.

rv._("""Header

    section text
    ...
    ...

    """)

Section text includes rivt markup - a plain text language that generates doc files formatted as text, HTML or PDF. rivt markup includes line tags, block tags and commands summarized here. See Markup for further details.

[5] Report Folders#

Reports are organized under a single root report folder with the prefix rivt-. rivt files are stored in the root folder and rivt markup file paths are relative to the root. Resource files are stored in four primary subfolders:

public: Includes rivt files written by rivtlib intended for upload to a public repository.
publish: Includes formatted docs and reports written by rivtlib.
src: Includes author provided content, style and generating files for docs and reports.
stored: Includes output files written by rivtlib including logs, values, hidden, and metadata.

Folder Key

Required names or prefixes are shown in brackets [ ].

Folders and subfolders that contain author generated files are marked with a single vertical bar ( | ).

Folders and subfolders that contain *rivtlib* generated files are marked with double vertical bars ( || ).

Top Level Folders

[rivt]-Report-Label/                Report Folder Name
    ├── [rv101-]filename1.py        | rivt file
    ├── [rv102-]filename2.py        | rivt file
    ├── [rv201-]filename3.py        | rivt file
    ├── [rv202-]filename4.py        | rivt file

    ...

    ├── [public]/                   || public rivt files
    ├── [publish]/                  || report and doc files
    ├── [src]/                      |  source files
    ├── [stored]/                   || stored rivt files
    └── README.txt                  || searchable text report

An example of a complete folder structure is here.

[5] Metadata#

Metadata is specified before any API functions are called and uses standard Python dictionaries, lists and strings. It is specified outside the rivtlib API functions and provides author information and global file path handling. See here for further details.

Variable	Description
rv_authD	specifies author information
rv_forknD	specifies author fork information - n is a number
rv_localB	true; false [default] - resource files are local

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 is always included.

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.