Dear committee members,
At the last meeting we decided I would explore a more git friendly format that we could use to edit future spec versions.
Specifically I proposed to explore using markdown format which is also mostly friendly to display on github where we are also testing the wiki.
Last week I spent some time experimenting with this, and copied enough of the current draft to give an idea of what we can achieve with markdown+pandoc to generate pdf and html outputs.
Attached find two example outputs (see also the note at the end of this post) and here find the source these are base on:
https://github.com/simo5/oasis-pkcs11/tree/draft-3.3/draft-3.3" style="font-family: Monospace; font-size: 14.666667px; font-style: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-indent: 0; text-transform: none; white-space: normal; word-spacing: 0; background-color: #FFFFFF" target="_blank" rel="noopener">https://github.com/simo5/oasis-pkcs11/tree/draft-3.3/draft-3.3
To give some context to people that were not on the meeting here is a personal list of pros/cons that motivates me to pursue this proposal:
Style and editing
There are five advantages of using markdown that I care for, and one
disadvantage that annoys me a little.
Advantages
- Split document in smaller manageable parts
- Can use any text tool you care, don't have to use a heavy program
like MS Office or Libreoffice.
- All changes are version controlled, therefore easy to read history
(when a change was made) and if commit messages are curated also easy
to find the reason why.
- Mostly you can focus on content rather then style when working on a
change, reducing time spent on the mechanics of the change
- Can easily use text tools that are rather powerful when large changes
are needed (git grep, sed, etc...);
Bonus
- we can enforce a style for test sections via an-auto formatter if we
care for that
Disadvantages
- Formatting is rigid and certainly not as flexible as MS Office
allows. Making changes to the style may be more complicated and
sometimes we might have to give up on some "nice" idea because the
tools do not easily allow what we might like.
I personally think the disadvantage is minor and all the advantages are
more important, this is a technical spec not a work of art so, some
limitation in the styling is also not a big deal to me, but I recognize my
bias here.
NOTE: I did not attempt at creating a new style for the document and kept it as close as possible to the current word based document structure.
If we allow ourselves to change a bit how the document is structured we can get better rendering result. However I already spent some time improving the result compared to the most basic pandoc conversion and I believe we can further improve many aspects of the current rendering even with the current structure.
------------------------------
Simo Sorce
Red Hat
------------------------------