Re: What is the correct way of handling generated docs?

[Bruce Korb]

Eli Zaretskii wrote:

> Is it out of the question to discuss possible alternatives to your
> current setup, so that the sources will be maintained in Texinfo?

That is what I was trying to do.  :-)
BTW, Doxygen does not (yet) have a way to emit texinfo docs.
I am trying to fix that by making it possible to insert the
Doxygen-extracted data into texi docs.

> What exactly are the reasons that you need to produce Texinfo from
> some other source language, rather than maintaining them in Texinfo?

This comment is used to produce external declarations,
Guile initialization code and usage documentation.
It belongs with the source code and needs to be inserted
whereever the information is required.

> /*=gfunc dne
>  *
>  * what:  '"Do Not Edit" warning'
>  *
>  * exparg: prefix, string for starting each output line
>  * exparg: first_prefix, for the first output line, opt
>  *
>  * doc:  Generate a "DO NOT EDIT" or "EDIT WITH CARE" warning string.
>  *       Which depends on whether or not the @code{--writable} command line
>  *       option was set.  The first argument is a per-line string prefix.
>  *       The optional second argument is a prefix for the first-line and,
>  *       in read-only mode, activates the editor hints:
>  *       @*
>  *       @example
>  *       -*- buffer-read-only: t -*- vi: set ro:
>  *       @end example
> =*/
>     SCM
> ag_scm_dne( SCM prefix, SCM first )
> {
>   [...]
> }

Karl Berry:
> I don't know about doxygen, but javadoc has a well-developed mechanism
> for maintaining the documentation for functions/classes/etc. in the
> source file, and standard tools for extracting it.  I didn't know there
> was a way to turn that into Texinfo, but if there is, great, I think
> it's worth supporting.

Doxygen will extract Java doc information.  My variation on Doxygen
will, at some point soon, be the official version, too.  It emits
definitions that AutoGen can use.  AutoGen can take the data and
insert it into anything, including texi docs.

> As for the original problem, maybe automake could have a variable
> BUILT_DOCS which lists texinfo files which are created, analogous to
> BUILT_SOURCES.  Just an idea, not claiming it solves everything or is
> easy to do ...

That would be the "macros, if that makes life easier" thing I referred
to.  Part of the problem is that the texi tools won't generate the
proper stuff into Makefile.in unless a .texi file exists.

Eli:
> Can the Javadoc-derived parts be @include'd in a Texinfo source?
> Bruce could then list them as prerequisites of the Info files, not of
> the Texinfo files.  (I'm thinking about something similar to the
> `chew' program used by several Cygnus-born projects.)

Truth is, that is more-or-less what I am doing now.  I don't actually
use the make-a-phoney/delete-a-phoney stuff any more.  However, that
still leaves a .info file dependent upon dynamic source, causing a
rebuild at "make distcheck" time causing the makeinfo command to choke
when it cannot "rm" (sans "-f") the .info file.  That is the second
part of the issue I am trying to raise:  It needs to not be an error
for dynamic text to make the .info file appear to need rebuilding.
Some well-defined mechanism should be constructed that says, basically,
"Rebuild it if you can and if it is convenient, but don't sweat it
if that is inconvenient."

Alexandre:
> You you elaborate on why the docs get rebuilt during distcheck?
> Which dependencies cause that?

The fact that nearly every source file I have contributes to some
piece of the documentation.  Since my tool includes the extraction
mechanism, I do not distribute that intermediate file.  Consequently,
the distcheck constructs it, it has a time stamp more recent than
the .info file, the .info file is distributed and you are not supposed
to rebuild during distcheck.  I can solve it by increasing my distro
size by 50K or so, but I'm already over a meg....

> What do you think about this unanswered bug report:
> http://sources.redhat.com/ml/bug-automake/2001/msg00423.html
> (personally I'd vote for solution 5)
Personally, I think it came two or three years after I initially
raised the issue, but now I'll go have a look.
[...time passes...]
[...too much time passed.  PacBell has stopped their DNS services again...]

:-)

Cheers,
        Bruce