A.1 | Start

[1] Overview

rivt is an open source project for writing, sharing and reusing engineering calculation documents [1]. It runs on the desktop and in the cloud. The project components include:

• rivtlib - a Python package that formats and compiles rivt files into rivt docs

• rivt files - text documents written using rivt markup

• rivt docs - formatted text, HTML and PDF docs output from rivt files

• rivtStudio - an integrated desktop editor that manages and publishes

• rivtRemote - a cloud version of rivtStudio that runs on a server in a browser

A rivt file (.py) uses rivt markup to organize text, calculations, images, code and external programs to publish rivt doc. A doc is a formatted text, HTML and PDF document. The rivt folder structure provides a replicable format for organizing a wide variety of file types. Groups of docs can be assembled into a structured rivt report.

This tutorial provides examples of a rivt file and its text, PDF, and HTML docs. To get started running examples see install. For rivt with AI see here.

rivt projects, reports and handbooks may be shared and distributed as zip files through any cloud storage service. Examples are available on Google Drive and searchable at openmodels.info. A convenient interface for searching public rivt READMEs on GitHub is here.

[1]

rivt includes provisions for selectively exporting rivt file sections to a public rivt folder intended for open-source distribution.

---

[2] Motivation

Freely sharing live engineering documents has been a challenge because commercial software does not align with this objective, and because the documents are complex. They may include text, images, tables, calculations, active models and computer code. They are also dynamic, and frequently updated and recalculated as project designs evolve and change.

The need for reuse of engineering documents is a matter of reducing writing time and increasing time for independent creative thought and checking. Most engineering calculations are not fundamentally unique. The basic equations and methods are shared across many projects. However they are organized in unique ways for specific project requirements. The commercial market response to this has been to develop a number of siloed programs with barriers to sharing and reuse including:

• incompatible documents across different programs

• costly software updates that are backward incompatible

• software limited to specific platforms

• limited version control

• limited report generation

• limited collaboration

The table below summarizes and compares limitations between specific programs that rivt is designed to complement or replace.

Software Comparison (commercial programs in italics)

Program	Reprt [2]	Ver [3]	Txt [4]	Priv [5]	Unts [6]	Comp [7]	C-P [8]	Coll [9]	Pub [10]
Matlab	no	no	no	no	no	no	no	no	yes
Mathcad	no	no	no	no	no	no	no	no	no
Mathematica	no	no	no	no	no	no	no	no	yes
Cloud SaaS	limited	no	no	no	no	no	yes	limited	limited
Excel	limited	no	no	no	no	yes	no	yes	yes
Jupyter	no	no	no	no	no	yes	yes	yes	yes
Quarto	yes	yes	no	no	no	no	yes	yes	yes
rivt	yes	yes	yes	yes	yes	yes	yes	yes	yes

[2]

Report generation.

[3]

Native Git version control.

[4]

Plain text input and output files.

[5]

Integrated syntax control of private/public files.

[6]

Calculation with dual units.

[7]

Forward and backward compatibility.

[8]

Cross-platform support.

[9]

Collaboration support.

[10]

Text, PDF, and HTML documents from the same input file.

rivt produces organized, formatted engineering documents from active calculation files that can be shared anywhere. The primary use cases for rivt include:

1. producing reusable engineering documents that are easier to write, edit and maintain compared to LaTeX, Excel, or Word

2. producing documents that need to be separated into public and private parts prior to sharing

3. using Python and AI tools to write engineering documents

4. functioning as a front and back end for external software

Engineering document types include:

1. internal communications

2. research documentation

3. government permits

4. technical reports

5. funding applications

6. teaching and presentation materials

7. homework

rivt may not be the best fit for all use cases. Quarto is likely a better fit for static documents with highly specific format requirements including journal articles and books. For interactive calculation documents that do not need organized report output or separation of private and public sections Jupyter Notebooks is likely a better tool.