Simon Richter <[EMAIL PROTECTED]> 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
