Re: Build warnings for documentation

[Mike Miller]

On Sat, Aug 25, 2012 at 11:30 AM, 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.

Whether my change is applied or not, octave.info *is* being built in
the source tree, nothing we can do about that, short of getting a
change made in Automake, so that could be brought up on their mailing
list.

> Hmm, I looked at a few projects to try to find an example of a .info
> file depending on something other than included .texi files and I
> couldn't find one where the dependency is expressed in the Makefile.am
> file (I admit it was not an exhaustive search).  The guile reference
> manual includes an image but doesn't state the dependency in the
> manual.  The GSL manual does the same.
>
> So maybe this is something that automake is not really handling very
> well?

I think that about sums it up. I suspect automake is most interested
in separating the source and build from the perspective of the end
user, whatever goes into generating the source tarball is open to
interpretation. For example, I'm pretty sure "make distcheck" marks
the source tree read-only to ensure that nothing is created there. But
some people choose to keep autotools-generated files under version
control, Octave doesn't, I also don't follow that practice for my
projects.

> It doesn't seem to be documented in the automake manual.  It
> does say:
>
>      Sometimes an info file actually depends on more than one `.texi'
>   file.  For instance, in GNU Hello, `hello.texi' includes the file
>   `fdl.texi'.  You can tell Automake about these dependencies using the
>   `TEXI_TEXINFOS' variable.  Here is how GNU Hello does it:
>
>        info_TEXINFOS = hello.texi
>        hello_TEXINFOS = fdl.texi
>
> (aside:  that's not very clear:  what is TEXI_TEXINFOS?) so it might
> work to add figure files here as well, but that's not really accurate
> as each output format type requires a different type of figure and
> the extra included files that we are concerned with are not Texinfo
> files, so the variable name wouldn't really match the usage we have in
> mind.

Only detailed documentation I've seen is this long comment in the
automake source about the pros and cons of .texi and .info files in
source vs. build directories:

http://git.savannah.gnu.org/cgit/automake.git/tree/automake.in#n3172

and it references Texinfo itself as an example of building info files
in the build path.

> Maybe we should bring it up on the automake list?

Sounds good.

-- 
mike