Re: Feature request: generate documentation from C files

[Simon Josefsson]

Simon Josefsson <address@hidden> writes:

> * Arguable, ANY form of markup will make the comments heavier to
>   maintain.  The nice thing about the current situation is that you
>   just type whatever you want, and the perl script figure things out.
>   E.g., if you write 'Errors:' on a line, the script treat this as a
>   section heading and uses @strong for texinfo.  To continue along
>   that path would mean having the script auto-detect if you include a
>   C code snippet, and use @example for it.  It would also auto-detect
>   indented text, and indent it.  Same thing for lists, e.g.:
>   * foo
>   * bar
>     + baz
>     + foo
>   * bar
>   would be translated into a nested list.  Almost all kind of markup
>   that one might want to use appear to be possible to auto-detect from
>   a very minimal and natural markup.  But perhaps I'm being optimistic.

For future reference, if someone stumbles over this thread; I found
something that might be what I was looking for: AsciiDoc.  It is an
ASCII markup that can be translated into HTML and DocBook.  For
example, it translates:

http://www.methods.co.nz/asciidoc/asciidoc.asc

into

http://www.methods.co.nz/asciidoc/asciidoc.html

or (using stylesheets)

http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html

I'm experimenting with making it generate TexInfo output somehow.

Using the AsciiDoc syntax within C source comments, and converting
them into TexInfo for the manual, appear to be ideal.