A.1 Introduction#
<i>
[1] Summary#
rivt is an open source software project that faciliates reuse and continual improvement of engineering documents. Writing engineering documents typically involves combining text, tables, diagrams, equations and calculations from a variety of sources. Although software combining these elements is available, shared document reuse is generally difficult because of limitations in the software:
documents are divided among many incompatible programs
documents are inaccessible without frequently updating software
update costs are high
software is limited to specific platforms
version controls are limited
report generation features are limited
collaboration features are limited
The table below compares rivt with other software and summarizes how it addresses these limitations:
Table 1 - Features
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 |
some |
some |
no |
no |
yes |
some |
Jupyter |
no |
no |
no |
yes |
yes |
yes |
rivt |
yes |
yes |
yes |
yes |
yes |
yes |
<i>
[2] import rivtlib#
A rivt file is a Python plain text file (.py) that imports the rivtlib library into the rv namespace:
import rivtlib.rvapi as rv
rivtlib includes 8 API functions that may be run as a script or interactively as notebook cells in VSCode or other IDE.
API |
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 |
Run Python functions |
rv.D(rs) |
Doc |
Write docs |
rv.M(rs) |
Meta |
Meta data |
rv.S(rs) |
Skip |
Skip section |
rv.Q(rs) |
Quit |
Exit rivt |
<i>
[3] rivt Strings and Docs#
The first four functions (R I V T) output formatted utf-8 text to the terminal and can generate doc content. The Run function executes shell commands. The Insert function adds static tables, images, equations and text. The Values function evaluates equations. The Tools function runs Python scripts.
The last four functions (D M S Q) are related to processing and output. The Doc function writes text, PDF or HTML doc files. The Meta function contains rivt file author and version information. The Skip and Quit functions are used for interactive editing and debugging.
An API function starts in the first column and takes a rivt string (rS) argument enclosed in triple quotes. The first line is a header that specifies overall section labeling and processing, followed by the section content. Content is indented four spaces for legibility and section folding.
rv._("""Header
section content
...
...
""")
Section content includes rivt markup - a plain text, light weight language that generates docs from the same rivt file in different formats. See Markup for further details. rivt files are compiled into docs that are formatted as text (.txt), HTML (.html) or PDF (.pdf) files.