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

[Brooks Moses <brooks@codesourcery.com>]

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