Fix doc index name on Windows

Fix doc index name on Windows

[Jonathan Larmour]

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

When cross building GDB 7.2 to Windows I have found that the GDB
documentation set generates HTML files named index.html and Index.html. On
Windows this unfortunately doesn't work as those names match each other.
The former is the front page and ToC, the latter is the genuine Index at
the end of the documentation.

The simplest solution is just to rename the Index at the end to have a
different node name. This is what other GNU documentation sets (GAS, BFD,
CPP, etc.) do. So that's what the attached patch (against current CVS) does.

I have a copyright assignment and check-in permissions. Okay to commit?

2010-11-25  Jonathan Larmour  <jifl@eCosCentric.com>

	* gdb.texinfo (Top): Rename Index to GDB Index to prevent clashes
	on Windows systems.
	(Help): Likewise.
	(Index): Likewise.
	* gdbint.texinfo (Top): Similar but with Index to GDB Internals Index.
	(GDB Internals Index): Likewise.

Jifl
-- 
eCosCentric Limited      http://www.eCosCentric.com/     The eCos experts
Barnwell House, Barnwell Drive, Cambridge, UK.       Tel: +44 1223 245571
Registered in England and Wales: Reg No 4422071.
------["Si fractum non sit, noli id reficere"]------       Opinions==mine

[-- Attachment #2: gdbdocidx.patch.txt --]
[-- Type: text/plain, Size: 2522 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.776
diff -u -5 -p -r1.776 gdb.texinfo
--- gdb.texinfo	23 Nov 2010 14:39:16 -0000	1.776
+++ gdb.texinfo	25 Nov 2010 17:33:49 -0000
@@ -182,11 +182,11 @@ software in general.  We will miss him.
                                  the operating system
 * Trace File Format::		GDB trace file format
 * 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
 
 @contents
@@ -1714,11 +1714,11 @@ inspect
 In addition to @code{help}, you can use the @value{GDBN} commands @code{info}
 and @code{show} to inquire about the state of your program, or the state
 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
 @kindex info
 @kindex i @r{(@code{info})}
@@ -36355,12 +36355,12 @@ which @value{GDBN} currently ignores.
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include fdl.texi
 
-@node Index
-@unnumbered Index
+@node GDB Index
+@unnumbered GDB Index
 
 @printindex cp
 
 @tex
 % I think something like @colophon should be in texinfo.  In the
Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.327
diff -u -5 -p -r1.327 gdbint.texinfo
--- gdbint.texinfo	20 Oct 2010 22:53:36 -0000	1.327
+++ gdbint.texinfo	25 Nov 2010 17:33:50 -0000
@@ -92,11 +92,11 @@ as the mechanisms that adapt @value{GDBN
 * Testsuite::
 * Hints::
 
 * GDB Observers::  @value{GDBN} Currently available observers
 * GNU Free Documentation License::  The license for this documentation
-* Index::
+* GDB Internals Index::
 @end menu
 
 @node Summary
 @chapter Summary
 
@@ -8030,11 +8030,11 @@ in the directory the script was called f
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include fdl.texi
 
-@node Index
-@unnumbered Index
+@node GDB Internals Index
+@unnumbered GDB Internals Index
 
 @printindex cp
 
 @bye

Re: Fix doc index name on Windows

[Eli Zaretskii]

> Date: Thu, 25 Nov 2010 17:40:07 +0000
> From: Jonathan Larmour <jifl@eCosCentric.com>
> 
> When cross building GDB 7.2 to Windows I have found that the GDB
> documentation set generates HTML files named index.html and
> Index.html.

What version of Texinfo is that?

Re: Fix doc index name on Windows

[Jonathan Larmour]

On 25/11/10 18:23, Eli Zaretskii wrote:
>> Date: Thu, 25 Nov 2010 17:40:07 +0000
>> From: Jonathan Larmour <jifl@eCosCentric.com>
>>
>> When cross building GDB 7.2 to Windows I have found that the GDB
>> documentation set generates HTML files named index.html and
>> Index.html.
> 
> What version of Texinfo is that?

The tools I build are generated on a RHEL4 machine, which is therefore a
bit on the older side intentionally for wider binary compatibility
(although that doesn't affect docs, true). It's texinfo 4.7.

Jifl
-- 
eCosCentric Limited      http://www.eCosCentric.com/     The eCos experts
Barnwell House, Barnwell Drive, Cambridge, UK.       Tel: +44 1223 245571
Registered in England and Wales: Reg No 4422071.
------["Si fractum non sit, noli id reficere"]------       Opinions==mine

Re: Fix doc index name on Windows

[Eli Zaretskii]

> Date: Thu, 25 Nov 2010 18:47:18 +0000
> From: Jonathan Larmour <jifl@eCosCentric.com>
> CC: gdb-patches@sourceware.org
> 
> On 25/11/10 18:23, Eli Zaretskii wrote:
> >> Date: Thu, 25 Nov 2010 17:40:07 +0000
> >> From: Jonathan Larmour <jifl@eCosCentric.com>
> >>
> >> When cross building GDB 7.2 to Windows I have found that the GDB
> >> documentation set generates HTML files named index.html and
> >> Index.html.
> > 
> > What version of Texinfo is that?
> 
> The tools I build are generated on a RHEL4 machine, which is therefore a
> bit on the older side intentionally for wider binary compatibility
> (although that doesn't affect docs, true). It's texinfo 4.7.

Then it's a bug in the cross-build version of makeinfo.  There's code
in makeinfo/node.c:cm_node to handle the case when a file name
produced from a node name clashes with a name of an existing file
(produced from some other node name), due to limitations of the
underlying filesystem.  What makeinfo does in that case is put all the
nodes whose names map to the same file name on that single file.  I
see this behavior in action in the Windows port of makeinfo 4.8, and
the code which does this was written long before Texinfo 4.7 was
released, so you must have it as well.

I guess whoever produced the cross-build environment didn't make sure
this feature is turned on, even though the RHEL4 filesystem does not
need this.

I don't like the name you suggest, "GDB Index".  That chapter is not
an index of GDB, it's an index of a manual.  I can go with something
like "Concept and Command Index" instead (and will accept such a patch
if you insist on fixing this in GDB), but I really think you should
take care of this in your cross-build environment, because that's
where the bug is.

Thanks.

Re: Fix doc index name on Windows

[Pedro Alves]

On Friday 26 November 2010 11:57:47, Eli Zaretskii wrote:
> Then it's a bug in the cross-build version of makeinfo.  There's code
> in makeinfo/node.c:cm_node to handle the case when a file name
> produced from a node name clashes with a name of an existing file
> (produced from some other node name), due to limitations of the
> underlying filesystem.  What makeinfo does in that case is put all the
> nodes whose names map to the same file name on that single file.  I
> see this behavior in action in the Windows port of makeinfo 4.8, and
> the code which does this was written long before Texinfo 4.7 was
> released, so you must have it as well.

If such code is only triggerable on some hosts only, then IMO it
is broken, because the resulting files will not be movable between
hosts (e.g., generate on Unix, unpack on Windows/NTFS/FAT/Samba, whatnot).
Is there a way to force that behaviour with a makeinfo command line
switch or something of the sort?

-- 
Pedro Alves

Re: Fix doc index name on Windows

[Eli Zaretskii]

> From: Pedro Alves <pedro@codesourcery.com>
> Date: Fri, 26 Nov 2010 12:03:05 +0000
> Cc: Jonathan Larmour <jifl@ecoscentric.com>
> 
> On Friday 26 November 2010 11:57:47, Eli Zaretskii wrote:
> > Then it's a bug in the cross-build version of makeinfo.  There's code
> > in makeinfo/node.c:cm_node to handle the case when a file name
> > produced from a node name clashes with a name of an existing file
> > (produced from some other node name), due to limitations of the
> > underlying filesystem.  What makeinfo does in that case is put all the
> > nodes whose names map to the same file name on that single file.  I
> > see this behavior in action in the Windows port of makeinfo 4.8, and
> > the code which does this was written long before Texinfo 4.7 was
> > released, so you must have it as well.
> 
> If such code is only triggerable on some hosts only, then IMO it
> is broken, because the resulting files will not be movable between
> hosts (e.g., generate on Unix, unpack on Windows/NTFS/FAT/Samba, whatnot).

IMO, "broken" is an exaggeration.  How many tools did you see that
care about having their files produced on Unix be compatible with
NTFS?  How many maintainers of GNU packages do you know who would even
consider a possibility of inserting NTFS-related limitations into
their codebase?

Usually, such problems are at best fixed for the hosts that use the
affected filesystems.  And the cross-build environments should take
care of these issues, because they _do_ (or should) care.

> Is there a way to force that behaviour with a makeinfo command line
> switch or something of the sort?

Not that I know of.  No one has ever asked for that, AFAIK.  But it
should be trivial to add such a switch, now that I pointed to the code
which does that.

Re: Fix doc index name on Windows

[Pedro Alves]

On Friday 26 November 2010 12:54:40, Eli Zaretskii wrote:
> > If such code is only triggerable on some hosts only, then IMO it
> > is broken, because the resulting files will not be movable between
> > hosts (e.g., generate on Unix, unpack on Windows/NTFS/FAT/Samba, whatnot).
> 
> IMO, "broken" is an exaggeration.

Maybe.  The emphasis should have been on "triggerable".  I don't
think one should have to build makeinfo for the host -- the build
machine's makeinfo should be useable in canadian crosses to build
the host's documentation.  Like the build machine's coreutils,
findutils, etc. are.

> How many tools did you see that
> care about having their files produced on Unix be compatible with
> NTFS?  How many maintainers of GNU packages do you know who would even
> consider a possibility of inserting NTFS-related limitations into
> their codebase?

Many.  I didn't mean that the "limitation" should be be added by
default, but as an option.

> > Is there a way to force that behaviour with a makeinfo command line
> > switch or something of the sort?
> 
> Not that I know of.  No one has ever asked for that, AFAIK.  But it
> should be trivial to add such a switch, now that I pointed to the code
> which does that.

Thanks.

Note that FWIW, I'd be perfectly happy with a change to our manual
to work around the issue.  We carry a similar patch in our tree.

-- 
Pedro Alves

Re: Fix doc index name on Windows

[Jonathan Larmour]

Eli Zaretskii wrote:
>>From: Pedro Alves <pedro@codesourcery.com>
>>Date: Fri, 26 Nov 2010 12:03:05 +0000
>>Cc: Jonathan Larmour <jifl@ecoscentric.com>
>>
>>On Friday 26 November 2010 11:57:47, Eli Zaretskii wrote:
>>
>>>Then it's a bug in the cross-build version of makeinfo.  There's code
>>>in makeinfo/node.c:cm_node to handle the case when a file name
>>>produced from a node name clashes with a name of an existing file
>>>(produced from some other node name), due to limitations of the
>>>underlying filesystem.  What makeinfo does in that case is put all the
>>>nodes whose names map to the same file name on that single file.  I
>>>see this behavior in action in the Windows port of makeinfo 4.8, and
>>>the code which does this was written long before Texinfo 4.7 was
>>>released, so you must have it as well.
>>
>>If such code is only triggerable on some hosts only, then IMO it
>>is broken, because the resulting files will not be movable between
>>hosts (e.g., generate on Unix, unpack on Windows/NTFS/FAT/Samba, whatnot).
> 
> 
> IMO, "broken" is an exaggeration.  How many tools did you see that
> care about having their files produced on Unix be compatible with
> NTFS?  How many maintainers of GNU packages do you know who would even
> consider a possibility of inserting NTFS-related limitations into
> their codebase?

Evidently quite a few because my patch just brings GDB into line with what 
GAS, binutils, BFD, CPP, and LD's docs explicitly do. In this respect GDB 
is the odd one out.

> Usually, such problems are at best fixed for the hosts that use the
> affected filesystems.  And the cross-build environments should take
> care of these issues, because they _do_ (or should) care.

People don't use a special cross version of makeinfo. GDB doesn't try and 
invoke one, for example. Which is quite right. I don't think people would 
be keen if I submitted a patch requiring cross builders to have provided 
e.g. arm-eabi-makeinfo.

>>Is there a way to force that behaviour with a makeinfo command line
>>> switch or something of the sort?
> 
> 
> Not that I know of.  No one has ever asked for that, AFAIK.  But it
> should be trivial to add such a switch, now that I pointed to the code
> which does that.

I don't think it's good to make GDB dependent on a version of makeinfo 
which does not yet exist.

Jifl
-- 
eCosCentric Limited      http://www.eCosCentric.com/     The eCos experts
Barnwell House, Barnwell Drive, Cambridge, UK.       Tel: +44 1223 245571
Registered in England and Wales: Reg No 4422071.
------["Si fractum non sit, noli id reficere"]------       Opinions==mine

Re: Fix doc index name on Windows

[Jonathan Larmour]

Eli Zaretskii wrote:
> 
> I don't like the name you suggest, "GDB Index".  That chapter is not
> an index of GDB, it's an index of a manual.

I was just going along with how other GNU projects have dealt with the 
issue. I have no strong feelings on this.

>  I can go with something
> like "Concept and Command Index" instead (and will accept such a patch
> if you insist on fixing this in GDB),

I'm happy to go along with whatever you suggest as the alternative.

Jifl
-- 
eCosCentric Limited      http://www.eCosCentric.com/     The eCos experts
Barnwell House, Barnwell Drive, Cambridge, UK.       Tel: +44 1223 245571
Registered in England and Wales: Reg No 4422071.
------["Si fractum non sit, noli id reficere"]------       Opinions==mine

Re: Fix doc index name on Windows

[Eli Zaretskii]

> Date: Fri, 26 Nov 2010 15:12:10 +0000
> From: Jonathan Larmour <jifl@eCosCentric.com>
> CC:  gdb-patches@sourceware.org
> 
> >  I can go with something
> > like "Concept and Command Index" instead (and will accept such a patch
> > if you insist on fixing this in GDB),
> 
> I'm happy to go along with whatever you suggest as the alternative.

Well, I just did, didn't I? ;-)

Re: Fix doc index name on Windows

[Eli Zaretskii]

> Date: Fri, 26 Nov 2010 15:07:30 +0000
> From: Jonathan Larmour <jifl@eCosCentric.com>
> CC: Pedro Alves <pedro@codesourcery.com>,  gdb-patches@sourceware.org
> 
> > IMO, "broken" is an exaggeration.  How many tools did you see that
> > care about having their files produced on Unix be compatible with
> > NTFS?  How many maintainers of GNU packages do you know who would even
> > consider a possibility of inserting NTFS-related limitations into
> > their codebase?
> 
> Evidently quite a few because my patch just brings GDB into line with what 
> GAS, binutils, BFD, CPP, and LD's docs explicitly do. In this respect GDB 
> is the odd one out.

I didn't mean in the manual, I meant in the code.  Most packages
assume that any file name is valid, and that file names are just
case-sensitive strings.  Some packages (GDB is one) are nice enough to
admit that file-name comparison should be case-insensitive on
non-Posix platforms.  But I can count on fingers of one hand those
that have code fragments that cater to more serious limitations or
idiosyncrasies of non-Posix platforms.

> People don't use a special cross version of makeinfo. GDB doesn't try and 
> invoke one, for example. Which is quite right.

Well, evidently it is NOT right, because stock makeinfo doesn't care
about this issue, except if you actually run it on Windows.

If we are going to have a coding convention that the Index nodes
should not be called just "Index", this should be at least in the
Texinfo manual, if not in standards.texi.

Re: Fix doc index name on Windows

[Andreas Schwab]

Eli Zaretskii <eliz@gnu.org> writes:

> I didn't mean in the manual, I meant in the code.  Most packages
> assume that any file name is valid, and that file names are just
> case-sensitive strings.  Some packages (GDB is one) are nice enough to
> admit that file-name comparison should be case-insensitive on
> non-Posix platforms.  But I can count on fingers of one hand those
> that have code fragments that cater to more serious limitations or
> idiosyncrasies of non-Posix platforms.

You can count on the fingers of one hand those packages that actually
have to care about conflicting file names in the first place.  Most
programs either don't write files, or they use the file names supplied
by the user.  Generating file names from user input is rather uncommon.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."