[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

What is the correct way of handling generated docs?

From: Bruce Korb
Subject: What is the correct way of handling generated docs?
Date: Sat, 29 Dec 2001 02:25:35 -0800


For years I have been maintaining this tool that extracts its own
documentation.  Projects that use Doxygen and Java doc tools have
basically the same issue.  The problem is that the "makeinfo" stuff
makes the erroneous assumption that mumble.texi is a source document.
>From that bad assumption stems many problems that have been hacked and
kludged around in various ways.  I'm tired of it.  I would like to see
a fix.

With a derived .texi file, that file will almost always get rebuilt
in a distribution and, as a consequence, it will always seem that the
.info file will need rebuilding.  There are two issues with that:

1.  A package builder may not have "makeinfo"
2.  "make distcheck" assumes that it should never need to
    rebuild the .info, even if it reconstructs the .texi.
    (So it errors-out by failing to ``rm'' the .info file.)

The solution is non-obvious to me, but necessary.  (Removing the .texi
predecessor dependencies works, but is rather tacky and doesn't really

Methinks the way this should work is that if the .texi is a derived
file, then "distcheck" should be okay with rebuilding the .info, even
though the .info is distributed.  Furthermore, if makeinfo is not
available, then the "missing --run makeinfo" script should print
"oops, sorry", `touch' the output, and exit with status 0.  Derivability
can be determined by looking for .texi build rules, or by an extra
magic macro name if that makes life easier.

Comments?  - Bruce

reply via email to

[Prev in Thread] Current Thread [Next in Thread]