Publish a document, not a screenshot of a website
GraphArch generates a typeset PDF and editable Typst source from the selected content in the documentation KG. No separate typesetting installation is required. A PDF can share a specification's content or use an independently planned reading order for review.
Document structure and presentation
The specification presentation follows the publisher's accent colour and includes publication metadata. The reader presentation uses the companion site's slate and teal palette. Documents support a cover, linked contents, running headings, page numbers, tables with repeated headers, code, retained images and diagrams, Markdown alerts, references, and appendices.
Legal notices can occupy their own styled front-matter pages. A publisher preface is distinct from the legal preamble and ordinary numbered chapters. Quality findings are grouped by warning type in a separate numbered appendix. Supplied content and release metadata remain source-owned; a layout is not proof of standards approval.
Tagged, accessible PDF
Every PDF, including each bookshelf book, is a tagged PDF: it carries a logical structure tree for headings, paragraphs, lists, tables, figures and links, a document language, and bookmarks that repeat the heading numbers. Images and diagrams carry alternative text from their retained titles.
Document metadata comes from the pinned target definition, never from the build
machine. The title is the document or book title. The authors are the target's
ga:author people, or else the publishing authority. Repeat ga:keyword on the
target for keywords; each value is one xsd:string. The creation date is the
target's ga:publicationDate; an undated target embeds no date. The same pinned
plan therefore produces byte-identical PDFs.
To require PDF/UA-1, add
ga:pdfStandard ga:PdfUa1 to the PDF profile:
@prefix ga: <https://ekgf.org/ontology/grapharch#> .
<urn:example:pdf-profile> a ga:Profile ;
ga:pdfStandard ga:PdfUa1 .
Typst checks the requirement while exporting each PDF. It requires a title, alternative text for images, and consecutive heading levels, and makes viewers display the document title. A violation fails the publication; it does not produce a non-conforming PDF. Typst's automated checks cannot establish everything PDF/UA asks of authors, such as a meaningful reading order or useful alternative text, so review the result with an accessibility checker.
Choose or define a theme
A profile selects its house style with ga:theme. Themes are RDF resources
identified by IRIs. GraphArch ships ga:ReaderTheme (the default for PDF and
websites), ga:SpecificationTheme (the default for specifications; it follows
the publisher's accent colour), ga:OverviewTheme, ga:EkgfTheme and
ga:EkgfProjectTheme in its theme catalogue.
The EKGF themes select the EKGF website identity; for PDF they use the reader
tokens.
A consumer theme refines a catalogue theme with ga:baseTheme and declares
only the tokens it changes:
@prefix ga: <https://ekgf.org/ontology/grapharch#> .
<urn:example:house> a ga:Theme ;
ga:baseTheme ga:SpecificationTheme ;
ga:paper "us-letter" ; ga:marginLeft "0.79in" ;
ga:bodyFont "Liberation Serif" ; ga:justify false ; ga:hyphenate false ;
ga:headingNumberGap "0.5in" ;
ga:tableHeaderFill "#4e80bc" ; ga:tableHeaderText "#ffffff" ; ga:tableGrid true ;
ga:footerShowsText true ; ga:outerPageNumber true ; ga:pageOfTotal false ;
ga:frontNumbering "i" ; ga:bodyNumbering "1" ;
ga:tocTitle "Table of Contents" ; ga:tocTitleAlign "center" ; ga:contentsDepth 2 ;
ga:annexLabel "Annex {letter}: {title}" ; ga:annexNormativity true ;
ga:annexRectoStart true ; ga:blankPageText "This page intentionally left blank." .
<urn:example:pdf-profile> a ga:Profile ; ga:theme <urn:example:house> .
Tokens cover page size and margins; colours; body, heading, code, caption,
footer, contents and notice fonts and sizes; justification and hyphenation;
heading numbering, a fixed number column and chapter page breaks; table header
fill, text and grid, caption position, and numbering within each top-level
chapter (ga:tableNumberByChapter, as in Table 8.3); link colour and
underlining; the footer text
(ga:footerText on the target, else the title) and a page number on the outer
edge; front and body page numbering; the contents title, alignment and depth;
and annex labels, a normativity line from the placement's ga:normativity, and
recto starts (the body then also starts on an odd page); and ga:normativeKeywordStyle, the small-caps or bold-italic
style of BCP 14 keywords in a target that declares ga:conformanceLanguage. The vocabulary defines each
token and its value syntax. GraphArch validates every value and maps it to a
Typst value; no supplied text is evaluated. An invalid value, an unknown token,
a missing token or a theme that does not refine a catalogue theme fails the
publication.
The cover is an ordered list of ga:coverBlock entries. Each places one
element: space, the publisher, its logo (ga:logo, PNG or SVG), the
publication date in a chosen format, the title, the subtitle, a version line,
a rule, a bar, the target's ordered metadata rows with their definition labels,
the specification summary, or fixed text. The values come from the target, so
a theme supplies no document number, status or legal wording.
Generated class diagrams take their PDF text font (ga:diagramFont) and the
fill of each box from the theme, by the box's role: the documented term, local
and imported classes, class expressions, object, datatype and other
properties, datatypes and literal values (ga:diagramFocusFill …
ga:diagramLiteralFill). A theme can so reproduce a notation's palette, such
as the ODM colours of OMG specifications. The layout engine measures Arial;
the metric-compatible Liberation Sans keeps the measured text widths. A profile
with ga:classDiagrams false omits the per-term diagrams from its PDF.
The bundled fonts are Liberation Sans, Serif and Mono, metric-compatible substitutes for Arial, Times New Roman and Courier New, plus Typst's embedded fonts. They are openly licensed; they are not the proprietary originals.
Add authored figures
A family chapter shows authored figures after its introduction. Each is a
ga:Figure with an image asset, a caption and an order, attached to its
ontology. Definitions collect the images from files beside them:
ex:project ga:collector ex:overview-image .
ex:overview-image a ga:CollectorUse ; ga:collectorType ga:ImageCollector ;
ga:source "figures/overview.png" ; ga:sourcePath "figures/overview.png" ;
ga:asset ex:overview-asset .
<https://example.org/ontology/> ga:figure ex:overview .
ex:overview a ga:Figure ; ga:asset ex:overview-asset ; ga:order 1 ;
dct:title "Overview of the Example Ontology" .
PDF figures are numbered through the document ("Figure 1: …"); the caption
uses the caption font, below the image, aligned by ga:figureCaptionAlign.
HTML shows the same caption in a figcaption. Authored Markdown can request
the same presentation with the image title grapharch:figure; the alternative
text is the caption.
A paragraph Table: <caption> directly before a Markdown table captions that
table, as in Pandoc. The PDF numbers it as a table ("Table 1: …") and places
the caption above or below it by ga:tableCaptionAbove; HTML wraps the table
in a figure with that figcaption. A paragraph that is not directly followed
by a table stays ordinary text.
The OMG Commons edition
The Commons showcase
declares OMG's house style as a consumer theme, OMG's notices, preface and
copyright holders, the OMG logo, and the Commons 1.3 release metadata. Its
profile sets ga:w3cFrontMatter false, omits the family overview, coverage,
quality, diagram-note and per-term class diagram material from the PDF, shows
OMG's 24 overview figures with their captions, authors clauses 1 to 7 and
Annex B as Markdown, and nests the ontology chapters under clause 8. Its ga:termTable presents each ontology as OMG's
clause 8 does: a numbered metadata table of the ontology header and a numbered
details table of its classes, datatypes, individuals and properties, with
labels, annotations and axioms in description-logic notation (see
Ontology families). Its cover states that it is a GraphArch rendering of
Commons 1.3. The design references the
Commons 1.3 PDF,
OMG core templates at revision 7e9dbce,
and OMG specification template at revision 9801480.
Publish an audience overview
Select ga:theme ga:OverviewTheme on a PDF profile for an editorial introduction:
a prominent cover, indigo accent, orange cover marker, larger chapter openings,
and a more relaxed reading measure. Choose a separate scope and placements for
purpose, concepts, adoption, and selected examples. The same sources can supply
a website and a guide without putting the full technical reference in both.
An overview is a community explanation, not an approval or release declaration.
Its provenance section still records the source revision and generator.
An independently scoped guide can set ga:qualityScope "selected" on its profile
to report findings for the resources it selects. The default, "all", retains
project-wide findings. Original diagnostics stay in the documentation KG.
Match the publication to its size
A small reference can have one PDF. A large ontology family can use bookshelf publication to create module books with separate PDFs and chapter navigation. Unchanged book PDFs can be reused after their input fingerprints and checksums are verified.
PDF compilation can be substantially slower than HTML generation for large or complex documents. Book boundaries and contents depth help keep the result usable; they do not make a very large ontology small.
Dedicated taxonomist-oriented print layouts are not currently supplied. SKOS content can appear in the existing resource-reference documents; a specialist hierarchical or alphabetical taxonomy edition requires further renderer work.
See publication families to separate a specification, companion site, and review PDF.