[Cryptech Core] [Cryptech Tech] Doc, Markdown, and Wiki

[Rob Austein]

At Mon, 27 Oct 2014 21:16:26 +0100, Joachim Strömbergson wrote:
> 
> BTW: We could use the Wiki as the primary documentation source. The only
> thing I really have against it is that I would rather having each core
> to be self contained. If I for example clone the ChaCha core, the clone
> should contain the core documentation too (in doc/ for example). I
> should not also have to go to the wiki and print a PDF of the wiki to
> get a local copy of the core documentation.

Moving text and simple diagrams between Wiki, HTML, PDF, and (where
practical) flat text is not all that hard.  See, eg, the stuff we use
on rpki.net: primary doc is in the Wiki, but we have tools (none of
which you would want to bring home to meet your family) which produce
PDF and flat text from them.  Samples:

  http://trac.rpki.net/wiki/doc/RPKI			(Wiki)

  http://subvert-rpki.hactrn.net/trunk/doc/manual.pdf	(PDF)

  http://subvert-rpki.hactrn.net/trunk/doc/		(flat text)

Neither the PDF nor the flat text is perfect, but in practice they
seem to be good enough for most purposes.

That's not currently organized to make it easy to pick out particular
bunches of pages and associate them with particular repositories
(rpki.net still uses one big Subversion repository), but it would be a
relatively trivial feature to add if that turns out to be the only
issue.

Given that this is an online project I would prefer to avoid getting
into lengthy discussions about which dead-tree-oriented document tools
we should use.  Word and all of its various clones give me hives; if I
were picking something it would be PDFLaTeX, or maybe DocBook.  No
doubt others have other preferences.  Large hole, many hungry rats.