Re: Build warnings for documentation

[John W. Eaton]

On 28-Aug-2012, Mike Miller wrote:

| John, I reread your concerns and looked at this in some more depth. The
| octave_TEXINFOS variable exists purely for adding dependencies, any file
| listed there is turned into a make dependency. The attached patch
| reworks the dependencies in our Makefile.am using that approach (also
| removes an unnecessary dependency in doc/liboctave, version.texi is
| handled by Automake automatically). Including this patch, I see three
| options:
| 
| 1. Apply the attached patch. Fixes the bug that IMAGES_TXT are not being
| generated for octave.info. Octave.info will still be built in srcdir,
| but at least the Makefile.am does not express knowledge of that. This
| approach loses the fine-grained association of which images are required
| for which doc format, now they are all required for all formats. I don't
| think that's a huge loss.

I'd prefer to have more accurate dependencies, but I agree that this
solution is probably OK.

| 2. Get Automake changed to allow octave.info to be made in the build
| directory. I already have a draft to the Automake list that I am
| planning on sending anyway to pursue that path if I can.

I think this would be best, but it's not urgent.

| 3. Do not distribute octave.info, octave.pdf, octave.html, etc, with the
| source, add those to DISTCLEANFILES, and octave.info will be built in
| the build directory. This is the only option in current versions of
| Automake to force octave.info to be built in the build directory. I
| think we do want to continue distributing documentation, so this is not
| viable.

I think we should be distributing formatted documentation and the
Makefile rules should be set up so that documentation building tools
are not needed unless some changes are made in the source tree.  This
is also what the GNU coding standards state.

| BTW, while testing this I uncovered a second bug, HTML documentation is
| not built now, with or without this patch. I think this is due to your
| change http://hg.savannah.gnu.org/hgweb/octave/rev/017f0b2e6933. Do you
| agree? Automake uses an implicit rule ".texi.html" and the new
| "octave.html" target is overriding that. There is no rule to build
| octave.html/index.html.

OK.  I didn't intend to break the rules for building octave.html.  But
I think the previous dependency of

  octave.html: $(OCTAVE_PNG)

was also wrong since makeinfo wants to put all the output files in a
subdirectory called octave.html.  I thought it was failing to create
the subdirectory itself.  Maybe I misunderstood the failure I saw.

jwe