Documents & Rich Text

DOC CREATE converts existing HTML or plain text into a finished PDF or DOCX file. RICH builds a genuine rich text document from scratch, element by element — headings, paragraphs, images, tables, charts, shapes, lists — with full positional and styling control.

DOC CREATE — Convert HTML to a Finished Document

Converts HTML content or a web page URL to a PDF or DOCX file. Output is saved to /root/files/ and the virtual path is returned. Input must be HTML — use AS "html" for HTML content, AS "text" for plain text, which wraps each line in a paragraph automatically.

Inline HTML

DOC CREATE FROM STRING "<h1>Report</h1><p>Q3 results exceeded targets.</p>" AS "html" OUTPUT "pdf" SET ?path
AFTER EMIT ?path

Plain Text — Each Line Becomes a Paragraph

DOC CREATE FROM STRING "Line one\nLine two\nLine three" AS "text" OUTPUT "pdf" SET ?path
AFTER EMIT ?path

From a Variable

STRING "<h1>Invoice</h1><p>Amount due: R500</p>" SET ?html
AFTER DOC CREATE FROM STRING ?html AS "html" OUTPUT "docx" SET ?path
AFTER EMIT ?path

From a Web Page URL

DOC CREATE FROM URL "https://example.com/report" AS "html" OUTPUT "pdf" SET ?path
AFTER EMIT ?path

Reading Namespace Content First

FILE READ "/root/templates/invoice.html" SET ?html
AFTER DOC CREATE FROM STRING ?html AS "html" OUTPUT "pdf" SET ?path
AFTER EMIT ?path

Sharing the Generated File

DOC CREATE FROM STRING ?html AS "html" OUTPUT "pdf" SET ?path
AFTER FILE SHARE ?path SET ?url
AFTER EMIT ?url

DOC CREATE Verb Reference

Verb	Description
`DOC CREATE FROM STRING "html" AS "html" OUTPUT "pdf" SET ?path`	Convert an HTML string to PDF
`DOC CREATE FROM STRING "text" AS "text" OUTPUT "pdf" SET ?path`	Convert plain text to PDF, lines become paragraphs
`DOC CREATE FROM STRING ?var AS "html"\|"text" OUTPUT "docx" SET ?path`	Convert to DOCX
`DOC CREATE FROM URL "url" AS "html" OUTPUT "pdf" SET ?path`	Fetch a URL and convert its rendered HTML to PDF

RICH — Building a Document from Scratch

Rich text document construction. Positions and sizes are in millimetres. Content flows naturally across pages as it overflows, exactly like a real word processor — AT LINE n places flowing content at a position in that continuous flow; AT x BY y places a freestanding element at an absolute position on the page.

Document Lifecycle

RICH OPEN reads back every format RICH EXPORT can write — rtf, pdf, docx and html — so a document written by one script is editable by the next. NEW RICH starts one from nothing; SAVE writes back to the file it was opened from, SAVE INTO writes a copy.

Open, Create, Read, Save

RICH OPEN "/root/report.rtf" SET ?rtf
AFTER RICH OPEN "/root/report.pdf" SET ?pdf
AFTER RICH OPEN "/root/report.docx" SET ?docx
AFTER RICH OPEN "/root/report.html" SET ?html
AFTER NEW RICH SET ?doc2
AFTER RICH READ ?doc SET ?content
AFTER RICH SAVE ?doc SET ?doc
AFTER RICH SAVE ?doc INTO "/root/report-copy.rtf" SET ?doc

Page Setup

Configuring the Page

RICH PAGE ?doc SIZE "A4" ORIENTATION "portrait" MARGIN TOP 20 BOTTOM 20 LEFT 25 RIGHT 25 SET ?doc
AFTER RICH PAGE ?doc SIZE "A4" ORIENTATION "landscape" SET ?doc2

Headers, Footers, and Page Numbers

Header, Footer, and Page Numbering

RICH HEADER ?doc WITH "Annual Report 2026" SET ?doc
AFTER RICH FOOTER ?doc WITH "Confidential" SET ?doc
AFTER RICH PAGE NUMBER ?doc POSITION "bottom-right" SET ?doc

Inserting Elements

Heading

RICH INSERT ?doc WITH "Annual Report 2026" AS "heading-1"
AT LINE 1
FONT "Inter" SIZE 32 WEIGHT 700 COLOR "#0d1117"
SET ?doc

All Six Heading Levels

NEW RICH SET ?doc
AFTER RICH INSERT ?doc WITH "Chapter" AS "heading-1" AT LINE 1 SET ?doc
AFTER RICH INSERT ?doc WITH "Section" AS "heading-2" AT LINE 2 SET ?doc
AFTER RICH INSERT ?doc WITH "Subsection" AS "heading-3" AT LINE 3 SET ?doc
AFTER RICH INSERT ?doc WITH "Topic" AS "heading-4" AT LINE 4 SET ?doc
AFTER RICH INSERT ?doc WITH "Detail" AS "heading-5" AT LINE 5 SET ?doc
AFTER RICH INSERT ?doc WITH "Fine print" AS "heading-6" AT LINE 6 SET ?doc
AFTER RICH EXPORT ?doc AS "html" SET ?html
AFTER EMIT ?html

Paragraph — with Alignment and Text Style

RICH INSERT ?doc WITH "This quarter we exceeded targets across every region." AS "paragraph"
AT LINE 2
FONT "Inter" SIZE 11 WEIGHT 400 WIDTH 160 LINE HEIGHT 1.6
ALIGN "justify"
ITALIC false UNDERLINE false STRIKETHROUGH false
SET ?doc

Every Colour Format

NEW RICH SET ?doc
AFTER RICH INSERT ?doc WITH "Named colour" AS "paragraph" AT LINE 1 COLOR "crimson" SET ?doc
AFTER RICH INSERT ?doc WITH "RGB" AS "paragraph" AT LINE 2 COLOR "rgb(0,87,255)" SET ?doc
AFTER RICH INSERT ?doc WITH "RGBA" AS "paragraph" AT LINE 3 COLOR "rgba(255,0,0,0.5)" SET ?doc
AFTER RICH INSERT ?doc WITH "3-hex" AS "paragraph" AT LINE 4 COLOR "#0af" SET ?doc
AFTER RICH INSERT ?doc WITH "Bare 6-hex" AS "paragraph" AT LINE 5 COLOR "0057FF" SET ?doc
AFTER RICH EXPORT ?doc AS "html" SET ?html
AFTER EMIT ?html

Image — Absolute Position

RICH INSERT ?doc WITH "/root/logo.png" AS "image"
AT 10 BY 10
WIDTH 50 HEIGHT 20
SET ?doc

Table — Built from Real Data

NEW ARRAY SET ?sales_data
AFTER NEW OBJECT SET ?row1
AFTER SET ?row1("region") AS "West"
AFTER SET ?row1("revenue") AS 42000
AFTER APPEND ?row1 TO ?sales_data
AFTER NEW OBJECT SET ?row2
AFTER SET ?row2("region") AS "East"
AFTER SET ?row2("revenue") AS 38000
AFTER APPEND ?row2 TO ?sales_data
AFTER RICH INSERT ?doc WITH ?sales_data AS "table"
AT LINE 4
WIDTH 160
SET ?doc

Chart — Reusing GRAPH's Chart Type Catalog

NEW OBJECT SET ?chart_data
AFTER SET ?chart_data("labels") AS ["West" AND "East" AND "North"]
AFTER SET ?chart_data("values") AS [42000 AND 38000 AND 51000]
AFTER RICH INSERT ?doc WITH ?chart_data AS "chart" TYPE "bar"
AT LINE 8
WIDTH 160 HEIGHT 80
SET ?doc
(* TYPE accepts any chart type documented on Graphs - SVG Charts *)

Shapes

RICH INSERT ?doc AS "rect" AT 0 BY 0 WIDTH 210 HEIGHT 2 COLOR "#0057FF" SET ?doc
AFTER RICH INSERT ?doc AS "circle" AT 50 BY 50 WIDTH 30 HEIGHT 30 COLOR "blue" SET ?doc
AFTER RICH INSERT ?doc AS "ellipse" AT 80 BY 50 WIDTH 40 HEIGHT 20 COLOR "#f00" SET ?doc
AFTER RICH INSERT ?doc AS "line" FROM 0 BY 0 TO 100 BY 100 COLOR "rgb(0,87,255)" SET ?doc
AFTER RICH INSERT ?doc AS "triangle" AT 20 BY 20 WIDTH 30 HEIGHT 30 COLOR "green" SET ?doc
AFTER RICH INSERT ?doc AS "arrow" FROM 10 BY 10 TO 90 BY 10 COLOR "black" SET ?doc
AFTER RICH INSERT ?doc AS "polygon" WITH [[10 AND 10] AND [50 AND 10] AND [30 AND 40]] COLOR "purple" SET ?doc

Divider

RICH INSERT ?doc AS "divider" AT LINE 6 COLOR "#e0e0e0" SET ?doc

Lists — Bulleted and Numbered

NEW ARRAY SET ?items
AFTER APPEND "First point" TO ?items
AFTER APPEND "Second point" TO ?items
AFTER APPEND "Third point" TO ?items
AFTER RICH INSERT ?doc WITH ?items AS "list-bulleted" AT LINE 10 SET ?doc
AFTER RICH INSERT ?doc WITH ?items AS "list-numbered" AT LINE 14 SET ?doc

Hyperlink

RICH INSERT ?doc WITH "Visit our site" AS "link" LINK "https://ocalt.com" AT LINE 18 SET ?doc

Page Break

RICH INSERT ?doc AS "page-break" AT LINE 20 SET ?doc

Formatting, Repositioning, and Deleting

Format a Text Range

RICH FORMAT ?doc FROM LINE 2 COL 1 TO LINE 2 COL 20
WEIGHT 700 COLOR "#0057FF"
SET ?doc

Move and Resize by Element ID

RICH MOVE ?doc ELEMENT ?el("id") AT 100 BY 200 SET ?doc
AFTER RICH RESIZE ?doc ELEMENT ?el("id") WIDTH 80 HEIGHT 40 SET ?doc

Delete an Element

RICH DELETE ?doc ELEMENT ?el("id") SET ?doc

Export

Exporting to Other Formats

RICH EXPORT ?doc AS "pdf" INTO "/root/report.pdf" SET ?path
AFTER RICH EXPORT ?doc AS "docx" INTO "/root/report.docx" SET ?path
AFTER RICH EXPORT ?doc AS "html" SET ?html

Reading the Document Object

NEW RICH SET ?doc
AFTER RICH PAGE ?doc SIZE "A4" ORIENTATION "landscape" SET ?doc
AFTER RICH INSERT ?doc WITH "One paragraph" AS "paragraph" AT LINE 1 SET ?doc
AFTER EMIT ?doc("page_size")
AFTER EMIT " "
AFTER EMIT ?doc("orientation")
AFTER EMIT " "
AFTER COUNT ?doc("pages") SET ?n
AFTER EMIT ?n

Color Formats

Every COLOR modifier throughout RICH accepts a named colour, RGB, RGBA (alpha as a 0–1 decimal), 6-character hex with or without #, or 3-character hex with or without # — the same universal set used everywhere else in OcaltQL.

Document Object Fields

Field	Type	Description
`page_size`	string	e.g. `"A4"`
`orientation`	string	`"portrait"` or `"landscape"`
`pages`	array	Array of page objects, each with an `elements` array
`path`	string	Source file path, present when opened from a file

Element Types Reference

Type	Description
`heading-1` through `heading-6`	Heading levels
`paragraph`	Body paragraph
`image`	Embedded image — `WITH "/root/path.png"`
`table`	Table built from an array of objects
`chart`	Chart — `TYPE` accepts any type from the Graphs - SVG Charts catalog
`rect`, `circle`, `ellipse`, `line`, `triangle`, `arrow`, `polygon`	Shapes
`divider`	Horizontal rule
`list-bulleted`	Bulleted list, built from an array
`list-numbered`	Numbered list, built from an array
`link`	Hyperlink — `LINK "url"`
`page-break`	Forces content after it onto a new page