[Infrastructure] Doc Formatting Requirements

[Ben Wilson]

FYI - I’ve volunteered to help lead a discussion of this (and related issues) in a slot at the face-to-face.

 

From: Infrastructure <infrastructure-bounces at cabforum.org> On Behalf Of Jos Purvis (jopurvis)
Sent: Friday, November 30, 2018 1:35 PM
To: infrastructure at cabforum.org
Subject: [Infrastructure] Doc Formatting Requirements

 

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 <mailto: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/20190306/8e374f7c/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4934 bytes
Desc: not available
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20190306/8e374f7c/attachment.p7s>