Re: [dev] suckless document generator for C code

From: Galos, David <galosd83_AT_students.rowan.edu>
Date: Fri, 11 May 2012 13:29:11 -0500

> I guess I like the idea of keeping all the information in the C header
> file. This makes it clean.

Less clean than troff files for the docs, I think. And retrieval is
definitely uglier than "man headername"

> The problem right now is the APIs are kept in a MS Word Office 2010
> .docx file, which doesn't work right with LibreOffice.

Ye gads!

> So I would prefer anything else over using MS Word to update the API
> docs.

Manpages are written in troff. Look up a manpage-writing
tutorial. Source documentation should concisely hint
at the algorithms, and _meanings_ of unclear things.

Manpages document the api, usage, and gotchas etc..
And, with troff, you can still do cool things like render
the pages to html, or pdf.
Received on Fri May 11 2012 - 20:29:11 CEST