Re: Building the .info files in build directory.

[Simon Josefsson]

Simon Richter <address@hidden> writes:

> Simon,
>
>> > [Info files being built in source dir]
>
>> > When the source dir is readonly, noone can change the texinfo files. If
>> > noone can change the texinfo files, there is no need to rebuild the info
>> > files, so it doesn't matter that they're in a readonly directory.
>
>> I don't think this is true in general, a texinfo file could @include a
>> file that is built during the build phase.
>
> True, however that's a bad thing IMO, as it requires the user to have a
> working texinfo installation.

For some it may be a small price to pay for the simplification of
maintaining the manual, to have the manual change automatically when
the source code changes.  I'm not sure a policy of forbidding the use
of auto-generated texinfo sources is realistic.  Is it impossible to
support both modes of operation?

> For stuff that depends on the local software configuration (for example,
> the locally installed ORB), it is usually better to generate
> documentation from the source rather than from the generated files.
> Stuff like the version information can easily be updated automatically
> when configure.ac is changed (make dist will update the header file and
> the documentation before bundling the archive), and machine-dependent
> stuff should be abstracted away by the API anyway.

I don't think it is realistic to require that the C documentation
generators can parse Bison files, Perl scripts etc instead of parsing
the generated C code.

Perhaps part of the problem is writing the dependency rule for this.
I think you'd want something like in doc/Makefile.am:

generated.texi: ../lib/generate-source-code.pl
        ./gdoc ../lib/generated-source-code.c > generated.texi

But people, including me, are lazy and simply write:

generated.texi: ../lib/generated-source-code.c
        ./gdoc $< > generated.texi