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|AsciiDoc]]** | **[[:ReStructuredText|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]| | | | |[0] Bold, underline, inclined 

[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