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.

Oftentimes, fine-grained control of table column widths is needed to prevent text overflow in the rendered PDF. The column widths are based on the relative widths of the separator row after the column headers.

| Col 1 | Col 2 | Col 3 | Col 4 |
|----|---|-------|----|                     <-- The widths of the separators on this line determine column widths.
| Some | text | of | varying length |
| 123 | 123 | 123 | 123 |


| Col 1 | Col 2 | Col 3 | Col 4          |
| ----- | ----- | ----- | -------------- |  <-- Auto-formatting a table will make these lengths match the column text.
| Some  | text  | of    | varying length |
| 123   | 123   | 123   | 123            |


+-------+-------+-------+---------+
| Col 1 | Col 2 | Col 3 | Col 4   |
+=======+=======+=======+=========+         <-- Grid tables let you wrap text within the cell to control the column width.
| Some  | text  | of    | varying |
|       |       |       | length  |
+-------+-------+-------+---------+
| 123   | 123   | 123   | 123     |
+-------+-------+-------+---------+

It is recommended to use a plugin to aid in formatting grid tables. This Table Formatter extension is suitable. When using this extension, ensure that its settings match what appear here:

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: 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.