Doc fixes for makeinfo --html

Doc fixes for makeinfo --html

[Joseph S. Myers]

This patch fixes various problems arising using the GDB manuals with
makeinfo --html.

* In general makeinfo --html expects the node structure similar to
  that for info output (and may be stricter about this than
  texi2html).  So @ifnottex should be used in most places in place of
  @ifinfo.

* @copying and @insertcopying need to be used for copyright and
  license notices so they get correctly included in all output files.
  See the notice in the Texinfo NEWS file regarding version 4.2.  (src
  toplevel configure requires makeinfo version 4.6 or later.)

* One index entry in gdb.texinfo used :: conditional on @iftex; this
  could be @ifnotinfo, as used in another such index entry.

* To work on case-insensitive filesystems with makeinfo splitting by
  node, the index should not be called "Index" as this clashes with
  the automatically generated index.html.  Fixed in the same way as
  <http://sourceware.org/ml/binutils/2006-05/msg00215.html>.

* Texinfo has allowed @contents at the start since version 4.0, so
  comments about it not working with 3.12 are out of date and
  irrelevant.

Tested building info/HTML/PDF (HTML with both makeinfo --html and
texi2html).  OK to commit?

2009-01-14  Joseph Myers  <joseph@codesourcery.com>
            Carlos O'Donell  <carlos@codesourcery.com>

	* annotate.texinfo: Use @copying and @insertcopying.  Use
	@ifnottex in place of @ifinfo.
	* gdb.texinfo: Use @copying and @insertcopying.  Use @ifnottex in
	place of @ifinfo.  Use @ifnotinfo for one index entry.
	(Index): Rename to GDB Index.
	* gdbint.texinfo: Use @copying and @insertcopying.  Use @ifnottex
	in place of @ifinfo.
	(Index): Rename to GDB Internals Index.
	* stabs.texinfo: Use @copying and @insertcopying.  Use @ifnottex
	in place of @ifinfo.  Include contents at start unconditionally.

Index: annotate.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/annotate.texinfo,v
retrieving revision 1.10
diff -u -r1.10 annotate.texinfo
--- annotate.texinfo	6 Jun 2008 00:35:16 -0000	1.10
+++ annotate.texinfo	14 Jan 2009 02:31:29 -0000
@@ -26,10 +26,9 @@
 @c more expensive, form factor and would drive up the manuals publication
 @c cost.  Having a smaller cheaper manual helps the GNU Press with its sales.
 
-@ifinfo
-This file documents @value{GDBN}'s obsolete annotations.
-
-Copyright (C) 1994, 1995, 2000, 2001, 2003 Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1994, 1995, 2000, 2001, 2003, 2004, 2005, 2007,
+2008, 2009 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -37,8 +36,13 @@
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled ``GNU
 Free Documentation License''.
+@end copying
+
+@ifnottex
+This file documents @value{GDBN}'s obsolete annotations.
 
-@end ifinfo
+@insertcopying
+@end ifnottex
 
 @titlepage
 @title @value{GDBN}'s Obsolete Annotations
@@ -47,18 +51,10 @@
 @author Free Software Foundation
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software
-Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts.  A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+@insertcopying
 @end titlepage
 
-@ifinfo
+@ifnottex
 @node Top
 @top GDB Annotations
 
@@ -68,7 +64,7 @@
 @ignore
 This is Edition @value{EDITION}, @value{DATE}.
 @end ignore
-@end ifinfo
+@end ifnottex
 
 @menu
 * Annotations Overview::  What annotations are; the general syntax.
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.544
diff -u -r1.544 gdb.texinfo
--- gdb.texinfo	13 Jan 2009 19:05:53 -0000	1.544
+++ gdb.texinfo	14 Jan 2009 02:31:35 -0000
@@ -1,6 +1,6 @@
 \input texinfo      @c -*-texinfo-*-
 @c Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,
-@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
+@c 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
 @c Free Software Foundation, Inc.
 @c
 @c %**start of header
@@ -43,20 +43,10 @@
 * Gdb: (gdb).                     The GNU debugger.
 @end direntry
 
-@ifinfo
-This file documents the @sc{gnu} debugger @value{GDBN}.
-
-
-This is the @value{EDITION} Edition, of @cite{Debugging with
-@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
-@ifset VERSION_PACKAGE
-@value{VERSION_PACKAGE}
-@end ifset
-Version @value{GDBVN}.
-
-Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998,@*
-              1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006@*
-              Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
+1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -68,7 +58,20 @@
 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
 this GNU Manual.  Buying copies from GNU Press supports the FSF in
 developing GNU and promoting software freedom.''
-@end ifinfo
+@end copying
+
+@ifnottex
+This file documents the @sc{gnu} debugger @value{GDBN}.
+
+This is the @value{EDITION} Edition, of @cite{Debugging with
+@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN}
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+Version @value{GDBVN}.
+
+@insertcopying
+@end ifnottex
 
 @titlepage
 @title Debugging with @value{GDBN}
@@ -90,25 +93,12 @@
 @end tex
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
-1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2006 
-Free Software Foundation, Inc.
-@sp 2
 Published by the Free Software Foundation @*
 51 Franklin Street, Fifth Floor,
 Boston, MA 02110-1301, USA@*
 ISBN 1-882114-77-9 @*
 
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Free Software'' and ``Free Software Needs
-Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
-and with the Back-Cover Texts as in (a) below.
-
-(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
-this GNU Manual.  Buying copies from GNU Press supports the FSF in
-developing GNU and promoting software freedom.''
+@insertcopying
 @page
 This edition of the GDB manual is dedicated to the memory of Fred
 Fish.  Fred was a long-standing contributor to GDB and to Free
@@ -129,7 +119,7 @@
 @end ifset
 Version @value{GDBVN}.
 
-Copyright (C) 1988-2006 Free Software Foundation, Inc.
+Copyright (C) 1988-2009 Free Software Foundation, Inc.
 
 This edition of the GDB manual is dedicated to the memory of Fred
 Fish.  Fred was a long-standing contributor to GDB and to Free
@@ -183,7 +173,7 @@
 * Copying::			GNU General Public License says
                                 how you can copy and share GDB
 * GNU Free Documentation License::  The license for this documentation
-* Index::                       Index
+* GDB Index::                   Index
 @end menu
 
 @end ifnottex
@@ -1694,7 +1684,7 @@
 of @value{GDBN} itself.  Each command supports many topics of inquiry; this
 manual introduces each of them in the appropriate context.  The listings
 under @code{info} and under @code{show} in the Index point to
-all the sub-commands.  @xref{Index}.
+all the sub-commands.  @xref{GDB Index}.
 
 @c @group
 @table @code
@@ -11117,9 +11107,9 @@
 @vindex colon-colon@r{, in Modula-2}
 @c Info cannot handle :: but TeX can.
 @end ifinfo
-@iftex
+@ifnotinfo
 @vindex ::@r{, in Modula-2}
-@end iftex
+@end ifnotinfo
 
 There are a few subtle differences between the Modula-2 scope operator
 (@code{.}) and the @value{GDBN} scope operator (@code{::}).  The two have
@@ -29201,8 +29191,8 @@
 @include fdl.texi
 @lowersections
 
-@node Index
-@unnumbered Index
+@node GDB Index
+@unnumbered GDB Index
 
 @printindex cp
 
Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.296
diff -u -r1.296 gdbint.texinfo
--- gdbint.texinfo	7 Jan 2009 21:42:50 -0000	1.296
+++ gdbint.texinfo	14 Jan 2009 02:31:37 -0000
@@ -6,11 +6,10 @@
 * Gdb-Internals: (gdbint).	The GNU debugger's internals.
 @end direntry
 
-@ifinfo
-This file documents the internals of the GNU debugger @value{GDBN}.
-Copyright (C) 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001,
-   2002, 2003, 2004, 2005, 2006, 2008
-   Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1996, 1998, 1999,
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009
+Free Software Foundation, Inc.
 Contributed by Cygnus Solutions.  Written by John Gilmore.
 Second Edition by Stan Shebs.
 
@@ -20,7 +19,13 @@
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled ``GNU
 Free Documentation License''.
-@end ifinfo
+@end copying
+
+@ifnottex
+This file documents the internals of the GNU debugger @value{GDBN}.
+
+@insertcopying
+@end ifnottex
 
 @setchapternewpage off
 @settitle @value{GDBN} Internals
@@ -48,15 +53,7 @@
 @end tex
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1990,1991,1992,1993,1994,1996,1998,1999,2000,2001,
-   2002, 2003, 2004, 2005, 2006  Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts.  A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+@insertcopying
 @end titlepage
 
 @contents
@@ -95,7 +92,7 @@
 
 * GDB Observers::  @value{GDBN} Currently available observers
 * GNU Free Documentation License::  The license for this documentation
-* Index::
+* GDB Internals Index::
 @end menu
 
 @node Requirements
@@ -6949,8 +6946,8 @@
 @include fdl.texi
 @lowersections
 
-@node Index
-@unnumbered Index
+@node GDB Internals Index
+@unnumbered GDB Internals Index
 
 @printindex cp
 
Index: stabs.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/stabs.texinfo,v
retrieving revision 1.20
diff -u -r1.20 stabs.texinfo
--- stabs.texinfo	20 Jan 2007 16:51:56 -0000	1.20
+++ stabs.texinfo	14 Jan 2009 02:31:37 -0000
@@ -10,11 +10,9 @@
 * Stabs: (stabs).                 The "stabs" debugging information format.   
 @end direntry
 
-@ifinfo
-This document describes the stabs debugging symbol tables.
-
-Copyright (C) 1992,1993,1994,1995,1997,1998,2000,2001
-   Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1997, 1998, 2000, 2001,
+2002, 2003, 2004, 2005, 2006, 2007, 2009 Free Software Foundation, Inc.
 Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
 and David MacKenzie.
 
@@ -24,7 +22,13 @@
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled ``GNU
 Free Documentation License''.
-@end ifinfo
+@end copying
+
+@ifnottex
+This document describes the stabs debugging symbol tables.
+
+@insertcopying
+@end ifnottex
 
 @setchapternewpage odd
 @settitle STABS
@@ -44,18 +48,10 @@
 @end tex
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1992,1993,1994,1995,1997,1998,2000,2001 Free Software Foundation, Inc.
-Contributed by Cygnus Support.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts.  A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+@insertcopying
 @end titlepage
 
-@ifinfo
+@ifnottex
 @node Top
 @top The "stabs" representation of debugging information
 
@@ -80,12 +76,9 @@
 * Symbol Types Index::          Index of symbolic stab symbol type names.
 * GNU Free Documentation License::  The license for this documentation
 @end menu
-@end ifinfo
+@end ifnottex
 
-@c TeX can handle the contents at the start but makeinfo 3.12 can not
-@iftex
 @contents
-@end iftex
 
 @node Overview
 @chapter Overview of Stabs
@@ -4130,12 +4123,4 @@
 
 @printindex fn
 
-@c TeX can handle the contents at the start but makeinfo 3.12 can not
-@ifinfo
-@contents
-@end ifinfo
-@ifhtml
-@contents
-@end ifhtml
-
 @bye

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Doc fixes for makeinfo --html

[Eli Zaretskii]

> Date: Wed, 14 Jan 2009 02:51:01 +0000 (UTC)
> From: "Joseph S. Myers" <joseph@codesourcery.com>
> 
> This patch fixes various problems arising using the GDB manuals with
> makeinfo --html.

Thanks.

> * To work on case-insensitive filesystems with makeinfo splitting by
>   node, the index should not be called "Index" as this clashes with
>   the automatically generated index.html.

In what version of makeinfo did you see this problem, and on what OS
and which port?  Because it was solved long ago: when some <node>.html
clashes with another <node>.html, makeinfo should resolve the clash
automatically.

> Fixed in the same way as
> <http://sourceware.org/ml/binutils/2006-05/msg00215.html>.

Sorry, but I don't like this fix.  Index nodes follow certain
guidelines in GNU packages, and I don't want to change that just like
that.  If there's a bug in makeinfo, I prefer to solve it there.

> Tested building info/HTML/PDF (HTML with both makeinfo --html and
> texi2html).  OK to commit?

Yes, but without the Index node renaming.

Thanks.

> 2009-01-14  Joseph Myers  <joseph@codesourcery.com>
>             Carlos O'Donell  <carlos@codesourcery.com>
> 
> 	* annotate.texinfo: Use @copying and @insertcopying.  Use
> 	@ifnottex in place of @ifinfo.
> 	* gdb.texinfo: Use @copying and @insertcopying.  Use @ifnottex in
> 	place of @ifinfo.  Use @ifnotinfo for one index entry.
> 	(Index): Rename to GDB Index.
> 	* gdbint.texinfo: Use @copying and @insertcopying.  Use @ifnottex
> 	in place of @ifinfo.
> 	(Index): Rename to GDB Internals Index.
> 	* stabs.texinfo: Use @copying and @insertcopying.  Use @ifnottex
> 	in place of @ifinfo.  Include contents at start unconditionally.

Please add a line before the actual logs that explains the purpose of
these changes.

Re: Doc fixes for makeinfo --html

[Joseph S. Myers]

On Wed, 14 Jan 2009, Eli Zaretskii wrote:

> > * To work on case-insensitive filesystems with makeinfo splitting by
> >   node, the index should not be called "Index" as this clashes with
> >   the automatically generated index.html.
> 
> In what version of makeinfo did you see this problem, and on what OS
> and which port?  Because it was solved long ago: when some <node>.html
> clashes with another <node>.html, makeinfo should resolve the clash
> automatically.

Various versions of makeinfo up to 4.12.  The problem is building GDB on 
i686-pc-linux-gnu (build system) with --host=i686-mingw32; I have not 
tried any version of makeinfo running directly on the case-insensitive 
systems (we build all tools for all hosts on GNU/Linux build systems).  
There is no way to pass the expected host to makeinfo, and since 
documentation goes in a "share" directory the files generated should not 
depend at all on the host in any case; it would be a bug for the files in 
the share directory to differ for different --host configurations.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Doc fixes for makeinfo --html

[Joseph S. Myers]

On Wed, 14 Jan 2009, Joseph S. Myers wrote:

> Various versions of makeinfo up to 4.12.  The problem is building GDB on 
> i686-pc-linux-gnu (build system) with --host=i686-mingw32; I have not 

I should add: we have a patch to make GDB use makeinfo --html instead of 
texi2html (as is generally done by GNU software, including anything using 
automake), as noted in 
<http://sourceware.org/ml/gdb-patches/2007-08/msg00133.html>; I'm trying 
to get in the fixes for makeinfo --html to work properly before proposing 
that patch.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: Doc fixes for makeinfo --html

[Eli Zaretskii]

> Date: Wed, 14 Jan 2009 11:30:50 +0000 (UTC)
> From: "Joseph S. Myers" <joseph@codesourcery.com>
> cc: gdb-patches@sourceware.org
> 
> On Wed, 14 Jan 2009, Eli Zaretskii wrote:
> 
> > > * To work on case-insensitive filesystems with makeinfo splitting by
> > >   node, the index should not be called "Index" as this clashes with
> > >   the automatically generated index.html.
> > 
> > In what version of makeinfo did you see this problem, and on what OS
> > and which port?  Because it was solved long ago: when some <node>.html
> > clashes with another <node>.html, makeinfo should resolve the clash
> > automatically.
> 
> Various versions of makeinfo up to 4.12.  The problem is building GDB on 
> i686-pc-linux-gnu (build system) with --host=i686-mingw32; I have not 
> tried any version of makeinfo running directly on the case-insensitive 
> systems

That might explain it: I think the feature I was talking about only
works on DOS and Windows, where the problem happens.

> There is no way to pass the expected host to makeinfo, and since 
> documentation goes in a "share" directory the files generated should not 
> depend at all on the host in any case; it would be a bug for the files in 
> the share directory to differ for different --host configurations.

That's quite an unusual setup for producing Info files; I'm not sure
GDB should make changes in the manual to cater to it.

My suggestion would be to add an option to makeinfo to enable the
feature on any platform, or maybe run makeinfo on Windows to produce
these files.