Re: Feature request: generate documentation from C files

[Simon Josefsson]

address@hidden (Karl Berry) writes:

>     I'm also unsure about legal status of it.
>
> Hmm, we need to be clear on that before I can include it in Texinfo.
> (Actually, we should really be clear even for linking, but anyway ...)
> Is the original author(s) unknown?

It is Michael Zucchi (written for GNOME 1.x and part of gnome-libs
back then, I believe), but at least Nikos Mavroyanopoulos has worked
on it for GNUTLS as well.  I got my copy from GNUTLS, perhaps Nikos
knows more.  It is licensed under GPL though.

>     I haven't convinced myself it is the right solution yet.
>
> Sure, I know there are lots of considerations.  Autodectecting 
> lists, examples, headings seems possible, maybe but I can't see how to
> autodetect a simple variable name which should come out in tt and may
> not have been previously seen.

Right now it uses $foo for environment variables, %bar for constants,
and @foo for parameters (which for me coincide with the set of
variables since I don't have any global variables).  Using FOO for tt
might work, and would work well with the elisp docstring tradition.

> Maybe some subset of pod?  (perldoc perlpod)  It is the most
> minimal/simplest documentation format I know that is still reasonably
> expressive.
>
>     "B<text>" -- bold text
>     "C<code>" -- code text
>     "L<name>" -- a hyperlink
>     =head1 Heading Text
>     =head2 Heading Text
>     =head3 Heading Text
>     =head4 Heading Text
>     =over indentlevel
>
> There are pod2foo translators for a number of foo's.

Thanks for the pointer, I'll consider it.