Re: Feature request: generate documentation from C files

[Alper Ersoy]

Hello Simon,

Simon Josefsson:
> I'm using doxygen, but I think I wasn't clear on the feature I think
> is the most important in the tool I want: generating a texinfo block
> for _one function only_.  Doxygen (and GTK-DOC-tools for that matter)
> appear to output entire sets of HTML files documenting the entire
> package, and this is not useful if you want to write a texinfo manual
> that look like:

I have both good and bad news for you.

Good news is, we already create texinfo docs from GTK-DOC style
C comments in BEAST/BSE project.

Bad news is, it's usually a monolithic file :\

You can see a few examples here:

  http://beast.gtk.org/documentation.html

See below ``API Reference'' on the left side.  You are interested in
``BSE Structs'' and ``SFI Functions.''  You can also take a look at
the files under ``Development.''

We also distribute man pages of these files, plus a special XML format
of these to be used in GtkTextView widget for online help purposes.
Everything is based on Texinfo, including the entire website except
of course the CGI parts.

The Perl script that does the extraction is included in the Beast
archive.  Since it's initially written by one of the Gtk+ maintainers
(Tim Janik), I believe it's fairly compatible with the original
GTK-DOC tools.

Anyways, back to the point.  We rely on makeinfo's xml output
capability.  Unfortunately makeinfo's xml output currently has
problems regarding @deffn type commands, so we had to develop our own
very simple macros to overcome the issue.  Which breaks the info
compatibility :\  However, since I'm working on makeinfo _right now_
to fix these problems, info compatilibity will eventually be
available.  Though it may take some time.  As soon as the xml output
is 100% fixed, I will start writing other XSL stylesheets to convert
to different formats as necessary.

These stylesheets are available from freedesktop.org CVS, module name
is texitheque.  In a couple of days, I mean as soon as I finish
writing the prelimary docs on authoring man pages with Texinfo and
Texitheque, we'll hopefully release the first public version.

Enough with these :)  Let me know if you are interested, and I will
write you a thorough rundown of how we get stuff working.  Since
I have a bunch of free time to spend nowadays, I am willing to hear any
feature/change requests.

Thanks,

-- 
Alper Ersoy