# 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.
```{list-table}
:header-rows: 1
* - 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](#commands) and [here](#tags).
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](https://docutils.sourceforge.io/docs/user/rst/quickref.html).
## 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](/organize.md#folders)
```{list-table}
:header-rows: 1
* - 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.
```{list-table}
:header-rows: 1
* - 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]]*.
```{list-table}
:header-rows: 1
* - 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.