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