Re: Feature request: generate documentation from C files

[Simon Josefsson]

address@hidden (Karl Berry) writes:

> Hi Simon,
>
>     <http://josefsson.org/gdoc/>.  
>
> This seems very nice, thanks.  I added a link on the Texinfo home page.
>
> Is it self-contained, in the one file (it looked that way ...)?

Yes.  The Makefile snippet is separate, but that isn't required, and
still experimental.

> Do you think it would be useful to include in the Texinfo
> distribution?  It could either be fully integrated, installed with
> make install, etc., or just be dropped in util/ along with all the
> other random stuff there.

I believe it would be too early to fully integrate it, the script has
some quirks (e.g., C parameters that look like 'const char foo[]' are
rendered as 'const char[] foo' because it wants to separate type and
parameter name).  I'm also unsure about legal status of it.  But
including it in util/ would be quite nice!  I have been using it for
over a year, so it is fairly stable.

>     The question of what markup language to use within comments still
>     remains, though.
>
> Of course you wouldn't expect any other answer on the Texinfo list :),
> but isn't (a subset of) Texinfo an obvious choice?  Not as free form as
> TeX, not as verbose as *ML, etc...

I haven't convinced myself it is the right solution yet.

* Texinfo commands uses @ which GTK-DOC uses for parameter markup,
  e.g. @foo means parameter variable foo.  Making texinfo commands
  look like @@strong would work though.

* 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.

* The comments has to be translated into doxygen and (possibly) SGML
  comments.  I think I would want doxygen support, but doesn't care
  much about SGML.  So one would have to consider which markup is
  easier to translate into others, without loss of information.

* Texinfo is rather, well ... texinfo-specific.  The script output
  DocBook, LaTeX, HTML, Texinfo, Man pages etc.  Introducing @@example
  would mean adding a texinfo parser and generator to the script, to
  make it generate the proper output for various formats.  I belive
  BEAST/BSE are looking at generating the other formats using
  'makeinfo' after texinfo, but I'm not yet sure it is flexible
  enough.  I really like the man (*) pages, for example.

As you can see, most of the arguments apply to any markup language.
Which is why I haven't decided...

Thanks,
Simon

(*) Mostly because I can M-x man RET on a function to immediately
access its documentation.  Nothing like that for info, as far as I
know..