Re: Build warnings for documentation

[Mike Miller]

On Sat, Aug 25, 2012 at 11:30:35AM -0400, John W. Eaton wrote:
> On 25-Aug-2012, Mike Miller wrote:
> 
> | On Sat, Aug 25, 2012 at 12:16 AM, Daniel J Sebald wrote:
> | > On 08/24/2012 06:55 PM, Daniel J Sebald wrote:
> | >
> | >> The only thing that I can think of (and which the others don't
> | >> have) is this dependency definition:
> | >>
> | >> INFO_DEPS = $(srcdir)/octave.info
> | >>
> | >> If one builds in a separate directory, then the destination for
> | >> octave.info is no longer in the source tree. I thought the answer was to
> | >> change "srcdir" to "DESTDIR", but that doesn't compile.
> | >
> | >
> | > The octave.info files are built, but placed in the wrong directory. Here's
> | > the contents in stages of build for the $(source)/doc/interpreter 
> directory
> | > (notice I said "source"):
> | 
> | It's not the wrong directory, it's how Automake defines info files to
> | be built. Automake considers info docs to be things that only
> | maintainers will build, are distributed with source, and hence end
> | users don't need to regenerate them. Remember there is the
> | version-controlled source tree, which is what we work with, and then
> | there's the source that is distributed in the octave-x.y.z.tar.gz,
> | which has some of the build steps already done so end users don't need
> | certain tools.
> | 
> | I looked through automake's logic and it does have a way to force info
> | files to be built in the build directory, but only if they are deleted
> | by a "clean" or "distclean" target, which is not what we want for
> | Octave.
> | 
> | Instead here's a changeset that fixes the dependencies by specifying
> | the correct path in $(srcdir) to octave.info so the *.txt files will
> | be generated when needed. Let me know if you all agree this captures
> | the situation correctly and it fixes the warnings you're seeing.
> 
> I suppose your workaround expresses the dependency, but I don't really
> like generating files in the source tree, or specifying targets that
> are explicitly in the source tree.

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.

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.

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.

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.

-- 
mike

info-fix-deps.diff
Description: Text Data