Re: [patch][gdb,etc] Add configure option to disable building internal documentation.

Brooks Moses
2007-11-07T19:22:24Z

Eli Zaretskii wrote:
>> Date: Tue, 06 Nov 2007 15:17:58 -0800
>> From: Brooks Moses <brooks@codesourcery.com>
>> This patch adds an --enable-internal-docs configure flag, which controls
>> whether or not this "internal" documentation is built and installed. It
>> is on by default, so that the current behavior is unchanged. Specifying
>> --disable-internal-docs (or --enable-internal-docs=no) will turn off
>> this "internal" documentation, so that the only documentation which is
>> built is that which is useful to an end-user.
>
> I have never heard neither about the problem nor this kind of
> solution. How can a few additional files in /usr/local/info add
> clutter and confuse?

Yes, I probably should have explained the context for this a bit better.

To begin with, this is something that we intend to use for our internal
packaging (at CodeSourcery), and we wanted to contribute it upstream
rather than maintaining it as a local patch, expecting that other people
who are distributing packaged toolchains would find it useful. This is
only a piece of that; we have similar patches for GCC and libiberty that
we expect to submit as soon as GCC enters stage 1, so the justification
for this should perhaps be viewed in context of the patches for the
whole toolchain.

Anyhow, consider the viewpoint of a new end-user who has just installed
a binary package. For them, it's unlikely that the GDB documentation is
in /usr/local/info; it's probably going to be in /opt/$gdb-package/doc
or someplace. If that was set up with "make install-pdf", there will be
four or five manuals in there -- three of which are irrelevant to their
needs, and which they don't want. And it's not entirely obvious which
one the user wants to look at first, if they are unfamiliar with GDB and
have a question they want to find an answer to. That seems confusing to
me, and is clutter in the sense that that's a considerable quantity of
bloat in the package size and its disk-space requirements that is
essentially pointless. Add up the sizes of the pdf, info, and html
files, and the space usage is considerable.

Meanwhile, if things _are_ installed into /usr/local/info, consider the
filenames involved. "Annotate" and "stabs" are not names that have any
obvious relation to GDB; it seems unlikely that an end-user will have
any idea what they are if they do come across them. So, again, files
that the end-user neither needs, nor wants, nor has any idea why they
are there; I think that's pretty much a definition of "clutter".

I agree that, for the particular special case of a user who is also a
developer and is installing the package for themselves from source, and
is responsible for assembling a coherent toolchain from disparate
pieces, the internal manuals may not be clutter. That's why this patch
leaves the default case unchanged.

However, at the level of someone who is making a package of the software
to distribute, these are definitely clutter, and I expect that many
people who produce packages of the GNU toolchain already have some
(fragile, manual) process for taking out the extraneous manuals before
packaging it. Automating and standardizing that -- and providing a
means by which the developers can easily identify new manuals as useful
for end-users or not -- seems a distinct benefit to the community.

> What other GNU packages have such configuration options?

As mentioned, I have patches for GCC and libiberty as well. I just
happened to start the submission process with GDB because of how the
release schedules worked out.

Thank you for your comments!

- Brooks