5. Edit

A rivt file is a Python file (utf-8 ) that includes the import statement

import rivtlib.rivtapi as rv

providing four primary API functions (7 total).

API

The API functions take a triple quoted string as the single argument. When running in an IDE (e.g. VSCode) API functions may be grouped and executed interactively using the standard cell decorator # %%. Interactive output is formatted as utf-8 text. Document and report files are generated by the functions rv.write_public() and rv.write_private() which output files in GitHub Flavored Markdown (GFM) and PDF.

API	Name	Purpose
rv.R	Run	Run external programs
rv.I	Insert	Insert static resources
rv.V	Value	Calculate values
rv.T	Tool	Python functions
rv.X	Exclude	Skip rivt function (editing)
rv.W	Write	Write docs or reports and exit
rv.Q	Quit	Exit rivt

Each API function defines a document section which may be arranged in any order or frequency.

Syntax

The first line of each function includes a section label (that also may be a section title) followed by formatting parameters. New sections may be labeled as separate or integrated with preceding sections. The section body can contain any utf-8 text. Commands and tags applicable to each function are defined [here](#commands) and [here](#tags).

rivt syntax includes COMMANDS for file operations and TAGS for text formatting. Any text not defined by commands or tags is passed through as restructuredText. COMMANDS and

Commands

Commands read and write external files. They start in the first column with one or two vertical bars. A double bar is used for write commands (||) and a single bar (|) for read commands. The command bar is followed by the command name, relative file path and parameters, all separated by a single bar:

| A READ COMMAND | relative file path | params

|| A WRITE COMMAND | relative file path | params

In the syntax description below parameter options are separated with semi-colons and list elements by commas. Optional parameters are in parenthesis. File locations are specified using paths relative to the rivt file location and the folder structure. File alias are also implemented. Folder organization is described here.

READ

Scope	Command	File Types
rv.V	| VALREAD | rel. pth | [rows]	.csv
rv.I	| TABLE | rel. pth | col width, l;c;r, [rows]	.csv, .txt, .xlsx
rv.I	| IMG | rel. pth | caption, scale, - ;**[_F]**	.png, .jpg
rv.I	| IMG2 | rel. pth | c1, c2, s1, s2, -;**[_F]**	.png, .jpg
rv.I	| TEXT | rel. pth | plain; rivt; literal; latex	.txt, .tex
rv.I	| APPEND | rel. pth | num; nonum	.pdf

WRITE

Scope	Command	Notes
rv.V	a = 1+1 | reference | units | decimals	= is command tag
rv.W	|| DOC | docs | (pdf, txt, html, pdf2)	pdf2 uses rst2pdf
rv.W	|| REPORT | docs | (pdf, txt, html, pdf2)	pdf uses latex pdf

Tags

Line tags format a line of text,are added at the end of the line and are denoted with _[TAG]. Block tags are denoted with _[[TAG]] on the first line. They evaluate a multi-line text block and end with _[[Q]] on the last line of the block (note: some tags only format pdf and html output).

Scope	Line Tags	Description
rv.I rv.V	_[G]	new page
rv.I rv.V	text _[C]	center text
rv.I rv.V	caption _[F]	autonumber, format image [1]
rv.I rv.V	title _[T]	autonumber, format table
rv.I rv.V	label _[E]	autonumber, format equation
rv.I	equation _[N]	autonumber, format Python math
rv.I	equation _[S]	format Python math
rv.I	text _[#]	autonumber footnote
rv.I	descrip _[D]	footnote description
rv.I	——–_[H]	horizontal line
rv.I	url, label _[K]	link
rv.I	text _[B]	center bold text (lpdf, html)

[1] Figure tag may be included IMG command

Scope	Block Tags	Description
rv.V	_[[V]]	start value-format block
rv.I rv.V	_[[Q]]	end block
rv.I	_[[N]]	start indent block
rv.I	_[[O]]	start literal (code) block
rv.I	__[[L]]	start latex block (lpdf, html)
rv.I	__[[I]]	start italic block (lpdf, html)
rv.I	__[[B]]	start bold block (lpdf, html)
rv.I	__[[T]]	start indent italic block (lpdf, html)