This page describes requirements and preferences for a document markup format to be used for the canonical version of CABF documents.

Requirement Github Markdown Common Markdown AsciiDoc ReStructuredText
Vendor neutral
Text formatting[0]
Plain-text font[1]
Formatting for word or block[2]
Bulleted items
Multi-level bullets
Intersperse bullets and numbers
Numbered items
At least 1,2,3 and a,b,c options[3]
Nesting of lists[4]
Line-breaks in lists
Section Numbering
Automatic section number generation?
5+ levels of section numbers
Control indentation for sections[5]
Text sizes
Headings
Table of Contents
Automatic generation of ToC from headers
Three-level ToC (down to 1.2.3)
Separate page numbers for this section[6]
Page Numbers
Separate title page
CA/B Forum logo on first page
License attribution on first page
Metadata block on first page[7]
No page number on title page
Document title large and centered
Headers
Footers
Footnotes[8]
Hyperlinks
Tables
Header rows and/or columns
Table alignment on page[9]
Table cell alignment[9]
Tables can break across pages
With or without table borders[10]
Cross-references[11]

[1] E.g. different font for “code” representations, like BRs section 7.1.5

[2] E.g. Single word in monospace vs. code block

[3] We also use (1)(2)(3) and i,ii,iii

[4] 1 a/b/c, 2 a/b/c or 1 i/ii/iii, 2 i/ii/iii

[5] Having 1.2.3.4.5 halfway across the page looks odd

[6] Optional, but we have it today

[7] Version, org, date

[8] Right now we do these manually with asterisks where they appear

[9] E.g. Centered, Right or Left alignment

[10] Cf. Acronyms table vs. Versions table

[11] Nice to have, considering lots of references in the Guidelines