[Cryptech Tech] Doc, Markdown, and Wiki

[Joachim Strömbergson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Aloha!

Rob Austein wrote:
> So I've noticed that all of the existing git.cryptech.is
> repositories have README.md files, in the style of github.  That's
> harmless, and certainly better than no doc at all.  Questions are:
> 
> 1) Is this all we want for doc of these repositories, or do we need 
> something more?

No, we want and SHOULD provide much more. I'm used to open projects
having a README file that gives an intro. But it does not replace all
documentation needed. The cores for example needs documentation that
describes functionality, architecure, ABI (register map and what the
registers do including side effects), implementation aspects etc.

I think Markdoen is good format for the README-file, but the other docs
should be in a suitable source format (ODT for example) and a PDF or
similar as a generated result for easy reading.


> 2) If this is the real doc, or at least part of the real doc, do we 
> want a hack which will extract content from the README.md files and 
> drop it into the Wiki?

It is part of the real doc. But extracting to the Wiki is a good idea.

> If this is of interest, I can hack together the necessary script and 
> set it running under cron (or maybe hanging off of a git hook, but
> I'm reluctant to get too clever with git hooks with tasks that could
> be handled well enough by a cron job).

Not sure we need to go as far as doing it with a cron job, but instead
run it whenwever we have had lots of updates. But otherwise I'm very in
favour of doing this, great idea.

- -- 
Med vänlig hälsning, Yours

Joachim Strömbergson - Alltid i harmonisk svängning.
========================================================================
 Joachim Strömbergson          Secworks AB          joachim at secworks.se
========================================================================
-----BEGIN PGP SIGNATURE-----
Version: GnuPG/MacGPG2 v2.0.22 (Darwin)
Comment: GPGTools - http://gpgtools.org
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQIcBAEBCAAGBQJUTqb9AAoJEF3cfFQkIuyN51QP/AxVV5i8mXYnDJ1DSACxC9Mh
3WDonlAyeWHPsHkMMPtScSa0wPvx/Wfln040NjOA9gBSiXcn5D8mHNITfdfPMbaP
REI0OM4PpiGX82doefW01vJ1PttalwU0M3tRTISJvtrbeDipc63+lS8icDwM1nVT
2uJ7PAL1HEowsztXQsq2cySx8n1pV5DXNMtkn84uZDW+Z6+GDPrFIEAbML51hxQE
xp2r+A6JxEIfSpzSwVRgJBsOd+QB+n+V/pLvllt4y4TqnaeU4Mo/buQR+4E9mFCk
97LOAkq2YdwrkDcwAk/6V6mWvZZLQx0AhiUPrueQWLq7fPoSxAcgbWxuEpNj72vS
SHWFZIt8eBlUQwe96hkjM9shzKamMVtcamAYsgPk70yz8EyBETH75xraJYplEk8c
MoTPlAXJkLUS8qDusozjoL7BkplalRxD3kbHk5+RKkeobEk3jTbWnX7mx6kbrAzS
vlanJ+d9tYUqqyOyq1CVRIwmWgChadNMjKwZ3n2tO7jLwb1pNXm4XolOfHdsBZeo
GFAtb2ZT14nF9dQ61vA2IrLhpw0xM1MGH8tiD771uPOWLBogcdr8tPZwCDxRsmSh
GqEzImwxVzJndPHRaWkjXDYP6fnxcY0QcEkbiNlqotBRuBKm1MfnkXoeNZP/rVm3
jtuo/xPOrSTv4JtKPMQJ
=pQGh
-----END PGP SIGNATURE-----