OCP Specification Tools

This repo contains tooling for rendering OCP specifications from Markdown.

TCG Pandoc

The scripts in this repository rely on TCG's Pandoc tooling. See the Guide (in PDF form on the TCG Pandoc Releases page).

How to Run Locally

Due to the complexity of the various Pandoc and LaTeX dependencies at work, it's easiest to use TCG's published Docker containers.

./docker-pull.sh

# Must run from the directory containing the input file
./docker-run.sh --pdf sample-spec.pdf sample-spec.ocp

HTML support is experimental.

./docker-run.sh --html sample-spec.html sample-spec.ocp

How to Build Locally

See the TCG Pandoc README for how to build locally.

Tips and tricks

Diagrams

Specification diagrams may be generated using draw.io. These can be edited with the Draw.io Integration Visual Studio Code extension.

When creating new diagrams, be sure to enable a white background. Otherwise, the diagram will not be legible to viewers with dark mode enabled.

Tables

This tooling supports multiple table syntaxes. See here for more details on each supported syntax.

Grid tables offer the most fine-grained control of column widths. With this syntax, a table's column widths in the rendered PDF are proportional to the column widths in the source file.

It is recommended to use a plugin to aid in formatting grid tables. The Table Formatter extension is suitable.

Note: do not use the extension's "Table: Format All" command, as the extension misinterprets the YAML frontmatter as a table, and attempts to format it.

Note: ensure that the extension settings match what appear here:

Note: while grid tables support rowspan or colspan cells, this extension cannot format them. One workaround is to format the table with all edges present, and then as a last step, remove the edges needed to produce the desired rowspan or colspan cells.