[Infrastructure] Doc Formatting Requirements

[Dimitris Zacharopoulos]

On 30/11/2018 10:34 μ.μ., Jos Purvis (jopurvis) wrote:
>
> 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
>       o Bold/italic/both/plain-text
>       o Format per word or per block
>   * Bulleted and Numbered lists
>       o Support for 1,2,3/a,b,c/i,ii,iii number formats
>       o Intersperse lists and paragraphs (i.e. include line-breaks
>         without restarting the list)
>       o Intersperse bullets and numbers
>   * Tables
>       o Header rows and/or columns
>       o Line breaks inside table cells
>   * Hyperlinks
>   * Can be diffed to show changes in Github
>
> Thoughts? Anything else that we couldn’t live without?
>

There was also a recommendation on github related to the formatting of 
listed items (https://github.com/cabforum/documents/issues/122).

I believe we also use subscripts and superscripts in the BRs. We also 
have footnotes (3.2.2.6) that currently doesn't render correctly (it is 
shown as "[^pubsuffix]").


Dimitris.



> -- 
> Jos Purvis (jopurvis at cisco.com)
> .:|:.:|:. cisco systems  | Cryptographic Services
> PGP: 0xFD802FEE07D19105  | +1 919.991.9114 (desk)
>
>
> _______________________________________________
> Infrastructure mailing list
> Infrastructure at cabforum.org
> http://cabforum.org/mailman/listinfo/infrastructure

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cabforum.org/pipermail/infrastructure/attachments/20190107/60ed887d/attachment-0001.html>