Source Code Conventions

The following describes the conventions for the various types of source files.

There is great advantage to be had by obeying certain source code conventions.
Among the benefits of these source conventions is are ease of reading and of editing, the ability to determine the source of current content in the standard, and the enhanced ease with which multiple editors can work on the same documents.

Editors are requested to abide by these conventions and to correct deviation from these conventions that they find.

All Source Files

XML Source Files

Graphics Files

Vector graphic files should be in SVG format, other graphic files should use the PNG format.

XSL Source Files

DTD Source Files

Makefile

Documentation Source Files

All documentation shall be written in Markdown format (*.md files)..

Do not use `<tag>` where "tag" is code, hostcode, schemacode, mono or URI as this confuses the line length checker. instead use the form &lt;tag>.

See Markdown for help on Markdown syntax.

The documentation generation pipeline supports the generation of mermaid diagrams.

Mermaid is a popular markup syntax for specifying various kinds of diagrams, flowcharts, and the like. To add another diagram, create a mermaid file with extensions .mmd in doc/ and update the Makefile accordingly. This will make sure that the doc build renders your diagram to SVG. Generated mermaid diagrams may be included in the documentation using the regular markdown syntax for embedding images.

See Mermaid for help on Mermaid syntax.

This file: Copyright © 2021 Editors of ISO/IEC JTC 1/SC 32/WG 3: Jim Melton, Stephen Cannan, Jörn Bartels, Stefan Plantikow