[Infrastructure] Doc Formatting Requirements

[Jos Purvis (jopurvis)]

I took our list of document formatting requirements and plugged them into a table in the wiki, here:

            https://cabforum.org/wiki/FIWG-DocMgtFormats

 

It occurs to me, looking over the list, that some of these are differences crucial only to the “print” version (PDF, Doc, etc.)—for example, the ability to modify bits on the title page only matters if you’re producing a PDF from the markup, which we’ve said wouldn’t be the canonical version. Markdown doesn’t have the ability to modify bits on the title page, but this may not be significant to us if we can do that with a wrapper when producing a PDF (as we do now).

 

Some features, on the other hand, are vital to the actual content of the document. If we couldn’t use nested lists, for example, or have tables with header rows, the resulting documentation would be much less manageable and could potentially be more difficult to read or interpret in any form. With that in mind, I’d propose a shorter list of actual canonical markup format requirements:

 
Vendor neutral
Basically human-readable in source form (this eliminates, e.g., TeX or XML)
Text formatting
Bold/italic/both/plain-text
Format per word or per block
Bulleted and Numbered lists
Support for 1,2,3/a,b,c/i,ii,iii number formats
Intersperse lists and paragraphs (i.e. include line-breaks without restarting the list)
Intersperse bullets and numbers
Tables
Header rows and/or columns
Line breaks inside table cells
Hyperlinks
Can be diffed to show changes in Github
 

Thoughts? Anything else that we couldn’t live without?

 

 

-- 
Jos Purvis (jopurvis at cisco.com)
.:|:.:|:. cisco systems  | Cryptographic Services
PGP: 0xFD802FEE07D19105  | +1 919.991.9114 (desk)

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20181130/1c85cb88/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 2095 bytes
Desc: not available
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20181130/1c85cb88/attachment.p7s>