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

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

[Brooks Moses]

[-- Attachment #1: Type: text/plain, Size: 2139 bytes --]

Currently, GDB's documentation targets build (and install) a number of
documents that are only relevant to people who are developing and/or
building the compiler, and which are not relevant to the end user on
whose system they have been installed.  These add clutter to the system
(thereby potentially confusing users), and are an inconvenience to
people who are packaging distributions.

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.

Specifically, the documents disabled with --disable-internal-docs are
standards and configure from etc/, and gdbint, stabs, and annotate from
gdb/doc/.  This affects pdf, html, ps, and info documentation.

(I also have a corresponding patch for libiberty; my understanding is
that this should go to GCC first, and then it will get merged to
src/libiberty, yes?)

Tested by building gdb with various iterations of this flag, and
confirming that it works as expected and doesn't break the build.  Ok to
commit?

- Brooks

gdb/ChangeLog -------------------------------------------------------
2007-11-06  Brooks Moses  <brooks@codesourcery.com>

	* doc/configure.ac (enable-internal-docs): New option.
	(enable_internal_docs): New AC_SUBST variable.
	* Makefile.in: Condition internal documentation on
	enable_internal_docs.
	* configure: Regenerated.

etc/ChangeLog -------------------------------------------------------
2007-11-06  Brooks Moses  <brooks@codesourcery.com>

	* doc/configure.ac (enable-internal-docs): New option.
	(enable_internal_docs): New AC_SUBST variable.
	* Makefile.in: Condition internal documentation on
	enable_internal_docs.
	(install-info, install-html, install-pdf): Loop over
	filenames rather than hardcoding them.
	* configure: Regenerated.

---------------------------------------------------------------------

[-- Attachment #2: 2007-11-06_internal-docs2a.diff --]
[-- Type: text/plain, Size: 11134 bytes --]

Index: gdb/doc/configure.ac
===================================================================
RCS file: /cvs/src/src/gdb/doc/configure.ac,v
retrieving revision 1.1
diff -U3 -r1.1 configure.ac
--- gdb/doc/configure.ac	7 Jan 2005 21:53:22 -0000	1.1
+++ gdb/doc/configure.ac	6 Nov 2007 22:46:57 -0000
@@ -2,4 +2,13 @@
 AC_INIT(refcard.tex)
 AC_PROG_INSTALL
 AC_PROG_LN_S
+
+AC_ARG_ENABLE(internal-docs,
+  [  --enable-internal-docs   build and install internal documentation],
+  [if test "x$enable_internal_docs" = x; then
+    enable_internal_docs=yes
+  fi],
+  [enable_internal_docs=yes])
+AC_SUBST(enable_internal_docs)
+
 AC_OUTPUT(Makefile)
Index: gdb/doc/Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.39
diff -U3 -r1.39 Makefile.in
--- gdb/doc/Makefile.in	26 Jul 2007 10:34:00 -0000	1.39
+++ gdb/doc/Makefile.in	6 Nov 2007 22:46:55 -0000
@@ -27,6 +27,8 @@
 pdfdir = $(prefix)/share/doc/gdb
 htmldir = $(prefix)/html
 
+enable_internal_docs = @enable_internal_docs@
+
 SHELL = @SHELL@
 
 LN_S = @LN_S@
@@ -71,11 +73,20 @@
 SET_TEXINPUTS = \
    TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$(GDBMI_DIR):$$TEXINPUTS
 
-# Files which should be generated via 'info' and installed by 'install-info'
-INFO_DEPS = gdb.info gdbint.info stabs.info annotate.info
-
-# Files which should be generated via 'pdf' and installed by 'install-pdf'
-PDFFILES = gdb.pdf gdbint.pdf stabs.pdf refcard.pdf annotate.pdf
+# Documentation files of various sorts.
+INFO_DEPS = gdb.info
+HTMLFILES = gdb_toc.html
+DVIFILES = gdb.dvi refcard.dvi
+PSFILES = gdb.ps refcard.ps
+PDFFILES = gdb.pdf refcard.pdf
+
+ifeq ($(enable_internal_docs),yes)
+  INFO_DEPS += gdbint.info stabs.info annotate.info
+  HTMLFILES += gdbint_toc.html stabs_toc.html annotate_toc.html
+  DVIFILES += gdbint.dvi stabs.dvi annotate.dvi
+  PSFILES += gdbint.ps stabs.ps annotate.ps
+  PDFFILES += gdbint.pdf stabs.pdf annotate.pdf
+endif
 
 # There may be alternate predefined collections of switches to configure
 # the GDB manual.  Normally this is not done in synch with the software
@@ -157,9 +168,9 @@
 all:
 
 info: $(INFO_DEPS)
-dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi annotate.dvi
-ps: gdb.ps gdbint.ps stabs.ps refcard.ps annotate.ps
-html: gdb_toc.html gdbint_toc.html stabs_toc.html annotate_toc.html
+dvi: $(DVIFILES)
+ps: $(PSFILES)
+html: $(HTMLFILES)
 pdf: $(PDFFILES)
 all-doc: info dvi ps # pdf
 diststuff: info
Index: etc/configure.in
===================================================================
RCS file: /cvs/src/src/etc/configure.in,v
retrieving revision 1.2
diff -U3 -r1.2 configure.in
--- etc/configure.in	6 Apr 2006 21:49:30 -0000	1.2
+++ etc/configure.in	6 Nov 2007 22:46:35 -0000
@@ -8,5 +8,12 @@
 AC_SUBST(docdir)
 AC_SUBST(htmldir)
 
+AC_ARG_ENABLE(internal-docs,
+  [  --enable-internal-docs   build and install internal documentation],
+  [if test "x$enable_internal_docs" = x; then
+    enable_internal_docs=yes
+  fi],
+  [enable_internal_docs=yes])
+AC_SUBST(enable_internal_docs)
 
 AC_OUTPUT(Makefile)
Index: etc/Makefile.in
===================================================================
RCS file: /cvs/src/src/etc/Makefile.in,v
retrieving revision 1.7
diff -U3 -r1.7 Makefile.in
--- etc/Makefile.in	27 Mar 2007 18:09:32 -0000	1.7
+++ etc/Makefile.in	6 Nov 2007 22:46:33 -0000
@@ -30,6 +30,7 @@
 infodir = @infodir@
 pdfdir = @docdir@
 htmldir = @htmldir@
+enable_internal_docs = @enable_internal_docs@
 
 SHELL = /bin/sh
 
@@ -58,10 +59,12 @@
 #### Host, target, and site specific Makefile fragments come in here.
 ###
 
-INFOFILES = standards.info configure.info
-DVIFILES = standards.dvi configure.dvi
-PDFFILES = standards.pdf configure.pdf
-HTMLFILES = standards.html configure.html
+ifeq ($(enable_internal_docs),yes)
+  INFOFILES = standards.info configure.info
+  DVIFILES = standards.dvi configure.dvi
+  HTMLFILES = standards.html configure.html
+  PDFFILES = standards.pdf configure.pdf
+endif
 
 all: info
 install: install-info
@@ -80,19 +83,15 @@
 	done
 
 install-info: info
-	$(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(infodir)
-	if test ! -f standards.info; then cd $(srcdir); fi; \
-	if test -f standards.info; then \
-	  for i in standards.info*; do \
-	    $(INSTALL_DATA) $$i $(DESTDIR)$(infodir)/$$i; \
-	  done; \
-	fi
-	if test ! -f configure.info; then cd $(srcdir); fi; \
-	if test -f configure.info; then \
-	  for i in configure.info*; do \
-	    $(INSTALL_DATA) $$i $(DESTDIR)$(infodir)/$$i; \
-	  done; \
+	if test "x$(INFOFILES)" != x; then \
+	  $(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(infodir); \
 	fi
+	for f in $(INFOFILES); do \
+	  if test ! -f $$f; then cd $(srcdir); fi; \
+	  if test -f $$f; then \
+	    $(INSTALL_DATA) $$f $(DESTDIR)$(infodir)/$$f; \
+	  fi; \
+	done
 
 html:
 	for f in $(HTMLFILES); do \
@@ -106,19 +105,15 @@
 	done
 
 install-html: html
-	$(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(htmldir)
-	if test ! -f standards.html; then cd $(srcdir); fi; \
-	if test -f standards.html; then \
-	  for i in standards.html*; do \
-	    $(INSTALL_DATA) $$i $(DESTDIR)$(htmldir)/$$i; \
-	  done; \
-	fi
-	if test ! -f configure.html; then cd $(srcdir); fi; \
-	if test -f configure.html; then \
-	  for i in configure.html*; do \
-	    $(INSTALL_DATA) $$i $(DESTDIR)$(htmldir)/$$i; \
-	  done; \
+	if test "x$(HTMLFILES)" != x; then \
+	  $(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(htmldir); \
 	fi
+	for f in $(HTMLFILES); do \
+	  if test ! -f $$f; then cd $(srcdir); fi; \
+	  if test -f $$f; then \
+	    $(INSTALL_DATA) $$f $(DESTDIR)$(htmldir)/$$f; \
+	  fi; \
+	done
 
 dvi:
 	for f in $(DVIFILES); do \
@@ -143,19 +138,15 @@
 	done
 
 install-pdf: pdf
-	$(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(pdfdir)/etc
-	if test ! -f standards.pdf; then cd $(srcdir); fi; \
-	if test -f standards.pdf; then \
-	  for i in standards.pdf*; do \
-	    $(INSTALL_DATA) $$i $(DESTDIR)$(pdfdir)/etc/$$i; \
-	  done; \
-	fi
-	if test ! -f configure.pdf; then cd $(srcdir); fi; \
-	if test -f configure.pdf; then \
-	  for i in configure.pdf*; do \
-	    $(INSTALL_DATA) $$i $(DESTDIR)$(pdfdir)/etc/$$i; \
-	  done; \
+	if test "x$(PDFFILES)" != x; then \
+	  $(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(pdfdir)/etc; \
 	fi
+	for f in $(PDFFILES); do \
+	  if test ! -f $$f; then cd $(srcdir); fi; \
+	  if test -f $$f; then \
+	    $(INSTALL_DATA) $$f $(DESTDIR)$(pdfdir)/etc/$$f; \
+	  fi; \
+	done
 
 standards.info: $(srcdir)/standards.texi $(srcdir)/make-stds.texi
 	$(MAKEINFO) --no-split -I$(srcdir) -o standards.info $(srcdir)/standards.texi
Index: gdb/doc/configure
===================================================================
RCS file: /cvs/src/src/gdb/doc/configure,v
retrieving revision 1.3
diff -U3 -r1.3 configure
--- gdb/doc/configure	7 Jan 2005 21:53:22 -0000	1.3
+++ gdb/doc/configure	6 Nov 2007 22:46:57 -0000
@@ -272,7 +272,7 @@
 PACKAGE_BUGREPORT=
 
 ac_unique_file="refcard.tex"
-ac_subst_vars='SHELL PATH_SEPARATOR PACKAGE_NAME PACKAGE_TARNAME PACKAGE_VERSION PACKAGE_STRING PACKAGE_BUGREPORT exec_prefix prefix program_transform_name bindir sbindir libexecdir datadir sysconfdir sharedstatedir localstatedir libdir includedir oldincludedir infodir mandir build_alias host_alias target_alias DEFS ECHO_C ECHO_N ECHO_T LIBS INSTALL_PROGRAM INSTALL_SCRIPT INSTALL_DATA LN_S LIBOBJS LTLIBOBJS'
+ac_subst_vars='SHELL PATH_SEPARATOR PACKAGE_NAME PACKAGE_TARNAME PACKAGE_VERSION PACKAGE_STRING PACKAGE_BUGREPORT exec_prefix prefix program_transform_name bindir sbindir libexecdir datadir sysconfdir sharedstatedir localstatedir libdir includedir oldincludedir infodir mandir build_alias host_alias target_alias DEFS ECHO_C ECHO_N ECHO_T LIBS INSTALL_PROGRAM INSTALL_SCRIPT INSTALL_DATA LN_S enable_internal_docs LIBOBJS LTLIBOBJS'
 ac_subst_files=''
 
 # Initialize some variables set by options.
@@ -780,6 +780,11 @@
 
   cat <<\_ACEOF
 
+Optional Features:
+  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
+  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
+  --enable-internal-docs   build and install internal documentation
+
 _ACEOF
 fi
 
@@ -1330,6 +1335,18 @@
 echo "${ECHO_T}no, using $LN_S" >&6
 fi
 
+
+# Check whether --enable-internal-docs or --disable-internal-docs was given.
+if test "${enable_internal_docs+set}" = set; then
+  enableval="$enable_internal_docs"
+  if test "x$enable_internal_docs" = x; then
+    enable_internal_docs=yes
+  fi
+else
+  enable_internal_docs=yes
+fi;
+
+
           ac_config_files="$ac_config_files Makefile"
 cat >confcache <<\_ACEOF
 # This file is a shell script that caches the results of configure
@@ -1970,6 +1987,7 @@
 s,@INSTALL_SCRIPT@,$INSTALL_SCRIPT,;t t
 s,@INSTALL_DATA@,$INSTALL_DATA,;t t
 s,@LN_S@,$LN_S,;t t
+s,@enable_internal_docs@,$enable_internal_docs,;t t
 s,@LIBOBJS@,$LIBOBJS,;t t
 s,@LTLIBOBJS@,$LTLIBOBJS,;t t
 CEOF
Index: etc/configure
===================================================================
RCS file: /cvs/src/src/etc/configure,v
retrieving revision 1.2
diff -U3 -r1.2 configure
--- etc/configure	6 Apr 2006 21:49:30 -0000	1.2
+++ etc/configure	6 Nov 2007 22:46:35 -0000
@@ -272,7 +272,7 @@
 PACKAGE_BUGREPORT=
 
 ac_unique_file="Makefile.in"
-ac_subst_vars='SHELL PATH_SEPARATOR PACKAGE_NAME PACKAGE_TARNAME PACKAGE_VERSION PACKAGE_STRING PACKAGE_BUGREPORT exec_prefix prefix program_transform_name bindir sbindir libexecdir datadir sysconfdir sharedstatedir localstatedir libdir includedir oldincludedir infodir mandir build_alias host_alias target_alias DEFS ECHO_C ECHO_N ECHO_T LIBS INSTALL_PROGRAM INSTALL_SCRIPT INSTALL_DATA datarootdir docdir htmldir LIBOBJS LTLIBOBJS'
+ac_subst_vars='SHELL PATH_SEPARATOR PACKAGE_NAME PACKAGE_TARNAME PACKAGE_VERSION PACKAGE_STRING PACKAGE_BUGREPORT exec_prefix prefix program_transform_name bindir sbindir libexecdir datadir sysconfdir sharedstatedir localstatedir libdir includedir oldincludedir infodir mandir build_alias host_alias target_alias DEFS ECHO_C ECHO_N ECHO_T LIBS INSTALL_PROGRAM INSTALL_SCRIPT INSTALL_DATA datarootdir docdir htmldir enable_internal_docs LIBOBJS LTLIBOBJS'
 ac_subst_files=''
 
 # Initialize some variables set by options.
@@ -780,6 +780,11 @@
 
   cat <<\_ACEOF
 
+Optional Features:
+  --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
+  --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
+  --enable-internal-docs   build and install internal documentation
+
 _ACEOF
 fi
 
@@ -1325,6 +1330,16 @@
 
 
 
+# Check whether --enable-internal-docs or --disable-internal-docs was given.
+if test "${enable_internal_docs+set}" = set; then
+  enableval="$enable_internal_docs"
+  if test "x$enable_internal_docs" = x; then
+    enable_internal_docs=yes
+  fi
+else
+  enable_internal_docs=yes
+fi;
+
 
           ac_config_files="$ac_config_files Makefile"
 cat >confcache <<\_ACEOF
@@ -1968,6 +1983,7 @@
 s,@datarootdir@,$datarootdir,;t t
 s,@docdir@,$docdir,;t t
 s,@htmldir@,$htmldir,;t t
+s,@enable_internal_docs@,$enable_internal_docs,;t t
 s,@LIBOBJS@,$LIBOBJS,;t t
 s,@LTLIBOBJS@,$LTLIBOBJS,;t t
 CEOF

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

[Daniel Jacobowitz]

On Tue, Nov 06, 2007 at 03:17:58PM -0800, Brooks Moses wrote:
> (I also have a corresponding patch for libiberty; my understanding is
> that this should go to GCC first, and then it will get merged to
> src/libiberty, yes?)

Yes.

> Tested by building gdb with various iterations of this flag, and
> confirming that it works as expected and doesn't break the build.  Ok to
> commit?

No, sorry - as came up after you posted this, the GNU make requirement
is not OK for GDB or binutils.  Could you revise?

-- 
Daniel Jacobowitz
CodeSourcery

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

[Eli Zaretskii]

> Date: Tue, 06 Nov 2007 15:17:58 -0800
> From: Brooks Moses <brooks@codesourcery.com>
> 
> Currently, GDB's documentation targets build (and install) a number of
> documents that are only relevant to people who are developing and/or
> building the compiler, and which are not relevant to the end user on
> whose system they have been installed.  These add clutter to the system
> (thereby potentially confusing users), and are an inconvenience to
> people who are packaging distributions.
> 
> 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?

What other GNU packages have such configuration options?

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

[Brooks Moses]

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

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

[Joel Brobecker]

> 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.

I agree that such an option would be very useful. I would even consider
changing the default to not installing these docs unless an option is
specified, since I think that most people who do gdb installs only
care about building/installing/using. Even as a GDB developer who
uses this documentation from time to time, I actually never look at
the installed documentation, because I never do "make install"! Most
of the time, I just go on the GDB webpage and browse the documentation
from there.

Anyway, I like the new option. Having the default one way or the other
doesn't matter much to me, so don't let this prevent this idea from
being implemented. We can always change the default later if we want to. 
That's the easy part.

-- 
Joel

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

[Eli Zaretskii]

> Date: Wed, 07 Nov 2007 11:22:12 -0800
> From: Brooks Moses <brooks@codesourcery.com>
> CC:  gdb-patches@sourceware.org
> 
> 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.

I really don't feel we are entitled to second-guess the user's needs.
The manuals that come with GDB are all useful one way or the other;
it's up to the user to remove those she knows she will never need.

> Add up the sizes of the pdf, info, and html files, and the space
> usage is considerable.

Actually, I doubt it's considerable by modern standards, but even if
it is, why would someone want to install all 3 formats by default?
You only need one (any one).

> 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.

You are reading too much into the names.  You assume that the user
looks at the file names and somehow decides what she needs to read or
search judging by the names.  But at least with Info manuals, that's
not the case: the user looks at the short descriptions in the DIR's
master menu, or invokes some global search command, like info-apropos.
So I really don't think the file names are too important.  Moreover,
if we look at other packages, we will see even more cryptic file
names: for example, what is `eintr' in Emacs? would you know that it's
the Introduction to Emacs Lisp? does this mean this manual is
``clutter''?

> 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.

People who produce packages are experienced users; they know what they
do.  I'm not sure we should propagate their system- and
package-system-specific choices upstream.

In sum, I cannot say I like this feature; it almost sounds to me like
something we should at least ask RMS about, as it goes against
long-standing policy of the GNU project.

Anyway, if we are going to have such a feature, I'd prefer a special
Makefile target for this, not a configure option.  This way, one can
install either the whole set of manuals or its subset, without the
need to reconfigure.

And the default ("make info" and "make install-info") must stay to
install everything, of course.

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

[Mark Kettenis]

> Date: Thu, 08 Nov 2007 00:22:39 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > Date: Wed, 07 Nov 2007 11:22:12 -0800
> > From: Brooks Moses <brooks@codesourcery.com>
> > CC:  gdb-patches@sourceware.org
> > 
> > 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.
> 
> I really don't feel we are entitled to second-guess the user's needs.
> The manuals that come with GDB are all useful one way or the other;
> it's up to the user to remove those she knows she will never need.
> 
> > Add up the sizes of the pdf, info, and html files, and the space
> > usage is considerable.
> 
> Actually, I doubt it's considerable by modern standards, but even if
> it is, why would someone want to install all 3 formats by default?
> You only need one (any one).

Seconded.  My biggest gripe about Linux these days is the insane
subdivision in subpackages just to save a few megabytes of disk space.