Re: Build warnings for documentation

[Mike Miller]

On Tue, Aug 28, 2012 at 9:37 AM, John W. Eaton wrote:
> On 28-Aug-2012, Mike Miller wrote:
> | 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.

Pushed; http://hg.savannah.gnu.org/hgweb/octave/rev/969952fcd30f

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

I've posed a question to the automake list, I'll let you know if that
goes anywhere.

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

Agreed. I ensured this still works with this change.

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

I started working on a fix for this, see attached. It works mostly,
but I am stuck at this sequence, open to suggestions:
  1. octave.html/*.html get created
  2. *.png are copied into octave.html, updating the timestamp of octave.html
  3. a second "make" copies *.png into octave.html again because
octave.html is newer than the first png file
  4. a third "make" says "nothing to be done"

Not sure how to get around this. Two options that occurred to me:
  1. add a "touch octave.html/*.png" to images.awk after every copy
  2. change "cp $< $@" to "cp *.png octave.html" so they all have the
same timestamp

-- 
mike

doc-html-fix.diff
Description: Binary data