Modify Documents#

API#

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

import rivtlib.rivtapi as rv

which provides four primary API functions and formatting commands and tags. The API functions take a triple quoted string as the argument.

When running in an IDE (e.g. VSCode) the file may be executed interactively. Interactive output is formatted as utf-8 text for speed and compatiblility. API functions may be grouped and executed step-wise using the standard cell decorator # %%. 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(str)

rivtinit

repository and report settings

rv.I(str)

insert

static text, images and tables

rv.V(str)

rivtinit

values

rv.T(str)

tools

Python functions and scripts

Each API function defines a document section. The first line of each function includes a section label that becomes a section title, followed by formatting parameters. New sections may be suppressed by prepending a double hyphen to the label.

The section body can contain any utf-8 text. Commands and tags applicable to each function are defined here and here.

The API function names start in column one. All other content is indented 4 spaces to facilitate section folding, bookmarking and legibility. API functions can be written in any order and frequency except for rivtinit, which occurs only once as the initial function in the file. A rivt file is a Python file that follows pep8 and ruff conventions.

rivt markup uses a syntax of commands for file operations and tags for text formatting. Any text not defined with commands or tags is passed through as output. Commands and tags are processed in part by the docutils library and restructuredText.

Commands#

Commands read and write external files and are marked by double bars (||) at the beginning of a line. Command parameters are separated by a single bar (|). In the summary below parameter options are separated with semi-colons, parameter list elements are separated with commas, and options are in parenthesis.

File locations are specified using shortene, relative paths that include the name of the file and the name of its containing folder. Folder organization is described here

command [applicable API]

|| text | relative path | rivt; plain [R I V]

The text command inserts and formats plain text files or files with rivt tags.

|| append | relative path | cover.pdf [R]

The append command attaches PDF files to the end of the doc.

|| image | relative path, (2nd path) | width, (width) [I]

The image command inserts and formats png or jpg files.

|| table | relative path | max col width, align [I]

The table command inserts and formats tabular data from csv or xls files.

|| declare | relative path | print; noprint [V]

The declare command imports values from a csv file written by rivt. Used for passing calculation results between documents.

Tags#

Line tags format a line of text and are denoted with _[tag], typically at the end of a line. The = and := tags used in the Value method are unique exceptions.

line tags

description

API

text _[b]

bold

R I V

text _[c]

center

R I V

text _[i]

italic

R I V

text _[bc]

bold-center

R I V

text _[bi]

bold-italic

R I V

text _[r]

right justify

R I V

text _[u]

underline

R I V

text _[l]

LaTeX math

I V

text _[s]

sympy math

I V

text _[bs]

bold-sympy math

I V

text _[e]

equation label, autonumber

I V

text _[f]

figure caption, autonumber

I V

text _[t]

table title, autonumber

I V

text _[#]

footnote, autonumber

I V

text _[d]

footnote description

I V

_[page]

new page

I V

_[address, label]

url or internal reference

I V

a = 1.2 | unit, alt | descrip

declare =

V

a := b + c | unit, alt | n,n

assign :=

V

Block tags start a text block with _[[tag]] and end with _[[q]].

block tags

description

API

_[[b]]

bold

R I V

_[[c]]

center

R I V

_[[i]]

italic

R I V

_[[p]]

plain

R I V

_[[q]]

quit block

R I V

_[[l]]

LaTeX

I V

profiles#

The rivt VSCode profile includes extensions, snippets and shortcuts for common editing functions.

## VSCode 
==============  ===========================================================
Keystroke                   Description
==============  ===========================================================


alt+q                rewrap paragraph with hard line feeds (80 default)
alt+p                open file under cursor
alt+.                select correct spelling under cursor
alt+8                insert date
alt+9                insert time

ctl+1                focus on first editor
ctl+2                focus on next editor
ctl+3                focus on previous editor
ctl+8                focus on explorer pane
ctl+9                focus on github pane    

ctl+alt+x            reload window
ctl+alt+u            unfold all code
ctl+alt+f            fold code level 2 (rivt sections visible)
ctl+alt+a            fold code - all levels
ctl+alt+t            toggle local fold
ctl+alt+e            toggle explorer sort order
ctl+alt+s            toggle spell check
ctl+alt+g            next editor group

ctl+shift+u          open URL under cursor in browser
ctl+shift+s          open GitHub rivt README search
ctl+shift+a          commit all 
ctl+shift+z          commit current editor
ctl+shift+x          post to remote

snippets#

snippet

ini

app

img

tbl

dec

txt

command snippets#

GitHub#

some text

Installation#

  • VSCode + extensions

  • LaTeX

  • Github account

rivt-doc is available for every OS platform and installs either into a single portable folder via a zip file, or as a collection of system programs. It also runs in the cloud at rivt-online and may be installed on GitHub CodeSpaces or other cloud service providers.