[PATCH, doc]: Rename Index node to prevent file collision

[PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

Hi there.  This patch renames the 'Index' node in the GDB end user documentation to 'GDB Index'
to prevent generating HTML filenames that differ only in case.

makeinfo generates a HTML file per node and uses the node name as the filename.  It also generates
a top level 'index.html'.  This causes problems in Windows as 'index.html' and 'Index.html' differ
only in case.

'GDB Index' matches the binutils style of using 'AS Index' and similar for the different tools.
makeinfo displays the node name to the end user in the window title so you can't use names like
'Index_'.

OK for trunk?

-- Michael

2012-06-14  Michael Hope  <michael.hope@linaro.org>

        * gdb.texinfo (GDB Index): Rename 'Index' to 'GDB Index'.

--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -182,7 +182,7 @@ software in general.  We will miss him.
  * 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::                   GDB Index
  @end menu

  @end ifnottex
@@ -1779,7 +1779,7 @@ 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
@@ -40390,8 +40390,8 @@ A string in the constant pool is zero-terminated.
  @appendix GNU Free Documentation License
  @include fdl.texi

-@node Index
-@unnumbered Index
+@node GDB Index
+@unnumbered GDB Index

  @printindex cp

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Joseph S. Myers]

On Thu, 14 Jun 2012, Michael Hope wrote:

> Hi there.  This patch renames the 'Index' node in the GDB end user
> documentation to 'GDB Index'
> to prevent generating HTML filenames that differ only in case.

This was rejected when I submitted it 
<http://sourceware.org/ml/gdb-patches/2009-01/msg00298.html>.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> Date: Thu, 14 Jun 2012 15:06:30 +0000 (UTC)
> From: "Joseph S. Myers" <joseph@codesourcery.com>
> cc: gdb-patches@sourceware.org
> 
> On Thu, 14 Jun 2012, Michael Hope wrote:
> 
> > Hi there.  This patch renames the 'Index' node in the GDB end user
> > documentation to 'GDB Index'
> > to prevent generating HTML filenames that differ only in case.
> 
> This was rejected when I submitted it 
> <http://sourceware.org/ml/gdb-patches/2009-01/msg00298.html>.

Right, and I still would like very much to follow GNU practice in this
matter.

Michael, is your setup also that you produce the HTML files on a Posix
host, but then deploy them on Windows?  If not, can you describe how
you bump into this problem?

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

On 15 June 2012 04:42, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Thu, 14 Jun 2012 15:06:30 +0000 (UTC)
>> From: "Joseph S. Myers" <joseph@codesourcery.com>
>> cc: gdb-patches@sourceware.org
>>
>> On Thu, 14 Jun 2012, Michael Hope wrote:
>>
>> > Hi there.  This patch renames the 'Index' node in the GDB end user
>> > documentation to 'GDB Index'
>> > to prevent generating HTML filenames that differ only in case.
>>
>> This was rejected when I submitted it
>> <http://sourceware.org/ml/gdb-patches/2009-01/msg00298.html>.
>
> Right, and I still would like very much to follow GNU practice in this
> matter.
>
> Michael, is your setup also that you produce the HTML files on a Posix
> host, but then deploy them on Windows?

Yip.  We supply pre-built toolchains for Linux and Windows[1].  The
build is crtosstool-NG based, runs on Ubuntu Lucid, and uses the LSB
compilers for Linux and the mingw cross compilers for Windows.  We
cross-make the manuals the same as we cross-build the compiler.

The makeinfo manual says: """If makeinfo is run on a system which does
not distinguish case in filenames, nodes which are the same except for
case will also be folded into the same output file.""".  I don't think
that's valid here as the index is a special case: we shouldn't merge
the top level index.html with the output of a node called Index.

-- Michael

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Joel Brobecker]

> Yip.  We supply pre-built toolchains for Linux and Windows[1].  The
> build is crtosstool-NG based, runs on Ubuntu Lucid, and uses the LSB
> compilers for Linux and the mingw cross compilers for Windows.  We
> cross-make the manuals the same as we cross-build the compiler.

I think we do something similar as well. I do not think that this is
an uncommon situation when someone works with GNU software on multiple
platforms.

> The makeinfo manual says: """If makeinfo is run on a system which does
> not distinguish case in filenames, nodes which are the same except for
> case will also be folded into the same output file.""".  I don't think
> that's valid here as the index is a special case: we shouldn't merge
> the top level index.html with the output of a node called Index.

I haven't checked, but is there a command-line option to force
that behavior? And I am also wondering why they wouldn't just
always make sure that the names are always different, irrespective
of casing...

-- 
Joel

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

On 15 June 2012 10:00, Joel Brobecker <brobecker@adacore.com> wrote:
>> Yip.  We supply pre-built toolchains for Linux and Windows[1].  The
>> build is crtosstool-NG based, runs on Ubuntu Lucid, and uses the LSB
>> compilers for Linux and the mingw cross compilers for Windows.  We
>> cross-make the manuals the same as we cross-build the compiler.
>
> I think we do something similar as well. I do not think that this is
> an uncommon situation when someone works with GNU software on multiple
> platforms.
>
>> The makeinfo manual says: """If makeinfo is run on a system which does
>> not distinguish case in filenames, nodes which are the same except for
>> case will also be folded into the same output file.""".  I don't think
>> that's valid here as the index is a special case: we shouldn't merge
>> the top level index.html with the output of a node called Index.
>
> I haven't checked, but is there a command-line option to force
> that behavior?

Not in makeinfo 4.13b.  There's been discussion upstream before about
this with no conclusion:
 http://lists.gnu.org/archive/html/bug-texinfo/2008-12/msg00012.html
 http://lists.gnu.org/archive/html/bug-texinfo/2010-11/msg00033.html

and on this list:
 http://sourceware.org/ml/gdb-patches/2010-11/msg00431.html
 http://sourceware.org/ml/gdb-patches/2009-01/msg00298.html

nodename_to_filename_1() special cases the node 'Top' and rewrites it
to 'index.html'.  Perhaps it should special case if the node is called
'Index'?

Eli, if that sounds OK to you then I'll propose a patch to bug-texinfo
and get it into Ubuntu.  texinfo seems to be dormant so it may be some
time before the patch appears in a release.

> And I am also wondering why they wouldn't just
> always make sure that the names are always different, irrespective
> of casing...

Agreed.  Host independent files like a manual shouldn't change based
on build or host.

-- Michael

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> From: Michael Hope <michael.hope@linaro.org>
> Date: Fri, 15 Jun 2012 10:27:05 +1200
> Cc: Eli Zaretskii <eliz@gnu.org>, "Joseph S. Myers" <joseph@codesourcery.com>, gdb-patches@sourceware.org
> 
> > I haven't checked, but is there a command-line option to force
> > that behavior?
> 
> Not in makeinfo 4.13b.  There's been discussion upstream before about
> this with no conclusion:
>  http://lists.gnu.org/archive/html/bug-texinfo/2008-12/msg00012.html
>  http://lists.gnu.org/archive/html/bug-texinfo/2010-11/msg00033.html

Patrice Dumas is the developer of the replacement for makeinfo, so I
guess you can expect the solution he liked in that thread when the
next version of Texinfo is out.

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> Date: Thu, 14 Jun 2012 15:00:37 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>,
> 	"Joseph S. Myers" <joseph@codesourcery.com>,
> 	gdb-patches@sourceware.org
> 
> > The makeinfo manual says: """If makeinfo is run on a system which does
> > not distinguish case in filenames, nodes which are the same except for
> > case will also be folded into the same output file.""".  I don't think
> > that's valid here as the index is a special case: we shouldn't merge
> > the top level index.html with the output of a node called Index.
> 
> I haven't checked, but is there a command-line option to force
> that behavior? And I am also wondering why they wouldn't just
> always make sure that the names are always different, irrespective
> of casing...

makeinfo is no longer maintained.  It will be replaced in the next
Texinfo release with a Perl-based reimplementation from scratch, which
is said to give us all kinds of wonders, and where you should ask for
this feature.

I have no idea when the next release will happen.  Until then, I would
suggest that the interested parties simply hack their own copies of
makeinfo to do what you need.  The code that puts several nodes on the
same HTML file and adjusts the links to DTRT is there, it just isn't
enabled on Posix platforms.  Enable it, and you are home free.  If you
need my help, just ask (I'm the one who adapted makeinfo to
case-insensitive filesystems years ago, and the text quoted above is
my fault).

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Joel Brobecker]

> I have no idea when the next release will happen.

I wrote the development mailing list, and they said hopefully this
summer.

-- 
Joel

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

On 15 June 2012 19:35, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Thu, 14 Jun 2012 15:00:37 -0700
>> From: Joel Brobecker <brobecker@adacore.com>
>> Cc: Eli Zaretskii <eliz@gnu.org>,
>>       "Joseph S. Myers" <joseph@codesourcery.com>,
>>       gdb-patches@sourceware.org
>>
>> > The makeinfo manual says: """If makeinfo is run on a system which does
>> > not distinguish case in filenames, nodes which are the same except for
>> > case will also be folded into the same output file.""".  I don't think
>> > that's valid here as the index is a special case: we shouldn't merge
>> > the top level index.html with the output of a node called Index.
>>
>> I haven't checked, but is there a command-line option to force
>> that behavior? And I am also wondering why they wouldn't just
>> always make sure that the names are always different, irrespective
>> of casing...
>
> makeinfo is no longer maintained.  It will be replaced in the next
> Texinfo release with a Perl-based reimplementation from scratch, which
> is said to give us all kinds of wonders, and where you should ask for
> this feature.
>
> I have no idea when the next release will happen.  Until then, I would
> suggest that the interested parties simply hack their own copies of
> makeinfo to do what you need.

This isn't ideal.  The problem has been discussed multiple times over
four years, affects at least four groups, and might be fixed by a
rewrite that might come out in the future.

Changing the node name works around a tools problem and makes the
output the same for all hosts.  I agree that 'Index' is more natural
than 'GDB Index'.  How about matching GCC, and call it the 'Concept
Index' instead?

-- Michael

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> From: Michael Hope <michael.hope@linaro.org>
> Date: Mon, 18 Jun 2012 11:26:04 +1200
> Cc: Joel Brobecker <brobecker@adacore.com>, joseph@codesourcery.com, 
> 	gdb-patches@sourceware.org
> 
> Changing the node name works around a tools problem and makes the
> output the same for all hosts.

I fail to understand why working around by changes in one file
(gdb.texinfo) is acceptable, but working around in another file
(makeinfo's source) is not.  I guess I'm missing something.

> I agree that 'Index' is more natural than 'GDB Index'.  How about
> matching GCC, and call it the 'Concept Index' instead?

(I wouldn't take example from GCC in any documentation-related area,
if you catch my drift.  I can never find anything there.  I hope the
GDB manual is better.)

The problem with your suggestion is that the GDB index is not a
concept index, it is all the indices lumped into one.  But I would be
OK if we separate the concept index from the rest, and then we could
have "Concept Index" and "Command and Variable Index".

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

On 18 June 2012 14:53, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Michael Hope <michael.hope@linaro.org>
>> Date: Mon, 18 Jun 2012 11:26:04 +1200
>> Cc: Joel Brobecker <brobecker@adacore.com>, joseph@codesourcery.com,
>>       gdb-patches@sourceware.org
>>
>> Changing the node name works around a tools problem and makes the
>> output the same for all hosts.
>
> I fail to understand why working around by changes in one file
> (gdb.texinfo) is acceptable, but working around in another file
> (makeinfo's source) is not.  I guess I'm missing something.

GDB is an active project.  Even if makeinfo was alive, it's nice to be
able to use the tools already shipped with long term releases like
Ubuntu 10.04.

I'd argue that if there's a tool problem we fix it in the tool and, if
the workaround is tidy and has no ongoing cost, work around it in GDB
as well.

>> I agree that 'Index' is more natural than 'GDB Index'.  How about
>> matching GCC, and call it the 'Concept Index' instead?
>
> (I wouldn't take example from GCC in any documentation-related area,
> if you catch my drift.  I can never find anything there.  I hope the
> GDB manual is better.)

Renaming the node doesn't affect the content or findability of the
documentation.

> The problem with your suggestion is that the GDB index is not a
> concept index, it is all the indices lumped into one.  But I would be
> OK if we separate the concept index from the rest, and then we could
> have "Concept Index" and "Command and Variable Index".

I'd rather not go there as it's a big change for little gain.

There's a few options so far:
 1. Leave it and have many groups with many hack arounds (ergh)
 2. Match bintuils and rename to 'GDB Index' (not natural)
 3. Match GCC and rename to 'Concept Index' (strictly true but confusing)
 4. Wait for makeinfo to be re-written and released
 5. Rewrite the filenames after generation

The last is what we currently do:  build on a case sensitive
filesystem, rename Index.html to Index_.html, and use sed to rewrite
the links in all other files.  This keeps the text the same and
doesn't require a change to makeinfo, but is a hack.

Shall I send a patch?

-- Michael

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> From: Michael Hope <michael.hope@linaro.org>
> Date: Thu, 21 Jun 2012 16:19:48 +1200
> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
> 
> > I fail to understand why working around by changes in one file
> > (gdb.texinfo) is acceptable, but working around in another file
> > (makeinfo's source) is not.  I guess I'm missing something.
> 
> GDB is an active project.  Even if makeinfo was alive, it's nice to be
> able to use the tools already shipped with long term releases like
> Ubuntu 10.04.

Texinfo is actively maintained as well.  It is also nice to be able to
generate a manual without having to jump through hoops.

It simply sounds unfair that you are asking a project to fix problems
of another.

> > The problem with your suggestion is that the GDB index is not a
> > concept index, it is all the indices lumped into one.  But I would be
> > OK if we separate the concept index from the rest, and then we could
> > have "Concept Index" and "Command and Variable Index".
> 
> I'd rather not go there as it's a big change for little gain.

??? It's as simple as modifying the "@syncodeindex" directives at the
beginning of gdb.texinfo, and then adding 2 @node lines for the two
indices, instead of the current one.  All the rest will be done by
makeinfo.  Am I missing something?

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

On 22 June 2012 04:22, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Michael Hope <michael.hope@linaro.org>
>> Date: Thu, 21 Jun 2012 16:19:48 +1200
>> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
>>
>> > I fail to understand why working around by changes in one file
>> > (gdb.texinfo) is acceptable, but working around in another file
>> > (makeinfo's source) is not.  I guess I'm missing something.
>>
>> GDB is an active project.  Even if makeinfo was alive, it's nice to be
>> able to use the tools already shipped with long term releases like
>> Ubuntu 10.04.
>
> Texinfo is actively maintained as well.

The last release was four years ago.  The list has around five threads
a month.  The ChangeLog shows recent development by Karl.

I'm happy to post a patch to makeinfo similar to
http://sourceware.org/ml/gdb-patches/2012-06/msg00496.html.  I'll do
that next as another avenue.

>  It is also nice to be able to
> generate a manual without having to jump through hoops.

I agree, including being able to cross build the manual for case
insensitive systems.

> It simply sounds unfair that you are asking a project to fix problems
> of another.

Yes if there's a need in the community, the problem won't be fixed in
a reasonable time in the tool, the work around is benign, and it
doesn't cost us down the road.

>> > The problem with your suggestion is that the GDB index is not a
>> > concept index, it is all the indices lumped into one.  But I would be
>> > OK if we separate the concept index from the rest, and then we could
>> > have "Concept Index" and "Command and Variable Index".
>>
>> I'd rather not go there as it's a big change for little gain.
>
> ??? It's as simple as modifying the "@syncodeindex" directives at the
> beginning of gdb.texinfo, and then adding 2 @node lines for the two
> indices, instead of the current one.  All the rest will be done by
> makeinfo.  Am I missing something?

Sorry, I assumed that we'd have to check and perhaps update each index
entry to see that it's in the right category.  Your texinfo foo is
better than mine - could you post a patch?

-- Michael

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> From: Michael Hope <michael.hope@linaro.org>
> Date: Fri, 22 Jun 2012 10:36:02 +1200
> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
> 
> >> > I fail to understand why working around by changes in one file
> >> > (gdb.texinfo) is acceptable, but working around in another file
> >> > (makeinfo's source) is not.  I guess I'm missing something.
> >>
> >> GDB is an active project.  Even if makeinfo was alive, it's nice to be
> >> able to use the tools already shipped with long term releases like
> >> Ubuntu 10.04.
> >
> > Texinfo is actively maintained as well.
> 
> The last release was four years ago.  The list has around five threads
> a month.  The ChangeLog shows recent development by Karl.

I don't see how this matters, when you have a publicly accessible CVS
repository.  What's important is that there are 3 active developers
who are responsive to questions and bug reports.

> I'm happy to post a patch to makeinfo similar to
> http://sourceware.org/ml/gdb-patches/2012-06/msg00496.html.  I'll do
> that next as another avenue.

Thank you.

> >> > The problem with your suggestion is that the GDB index is not a
> >> > concept index, it is all the indices lumped into one.  But I would be
> >> > OK if we separate the concept index from the rest, and then we could
> >> > have "Concept Index" and "Command and Variable Index".
> >>
> >> I'd rather not go there as it's a big change for little gain.
> >
> > ??? It's as simple as modifying the "@syncodeindex" directives at the
> > beginning of gdb.texinfo, and then adding 2 @node lines for the two
> > indices, instead of the current one.  All the rest will be done by
> > makeinfo.  Am I missing something?
> 
> Sorry, I assumed that we'd have to check and perhaps update each index
> entry to see that it's in the right category.

No.  We already have separate index categories: see the @kindex,
@findex, @vindex, etc. directives, in addition to @cindex, that we
have all over the manual.  It's just that these 4 directives at the
beginning of gdb.texinfo:

  @syncodeindex ky cp
  @syncodeindex tp cp

  @c readline appendices use @vindex, @findex and @ftable,
  @c annotate.texi and gdbmi use @findex.
  @syncodeindex vr cp
  @syncodeindex fn cp

arrange for all of them to be lumped into a single index "cp" (which
stands for "Concept Index"), and so this directive in the single
"Index" node we have:

  @printindex cp

prints all of the index entries together.

> Your texinfo foo is better than mine - could you post a patch?

OK.

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> Date: Fri, 22 Jun 2012 08:58:19 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
> 
> > >> > The problem with your suggestion is that the GDB index is not a
> > >> > concept index, it is all the indices lumped into one.  But I would be
> > >> > OK if we separate the concept index from the rest, and then we could
> > >> > have "Concept Index" and "Command and Variable Index".
> > >>
> > >> I'd rather not go there as it's a big change for little gain.
> > >
> > > ??? It's as simple as modifying the "@syncodeindex" directives at the
> > > beginning of gdb.texinfo, and then adding 2 @node lines for the two
> > > indices, instead of the current one.  All the rest will be done by
> > > makeinfo.  Am I missing something?
> > 
> > Sorry, I assumed that we'd have to check and perhaps update each index
> > entry to see that it's in the right category.
> 
> No.  We already have separate index categories: see the @kindex,
> @findex, @vindex, etc. directives, in addition to @cindex, that we
> have all over the manual.  It's just that these 4 directives at the
> beginning of gdb.texinfo:
> 
>   @syncodeindex ky cp
>   @syncodeindex tp cp
> 
>   @c readline appendices use @vindex, @findex and @ftable,
>   @c annotate.texi and gdbmi use @findex.
>   @syncodeindex vr cp
>   @syncodeindex fn cp
> 
> arrange for all of them to be lumped into a single index "cp" (which
> stands for "Concept Index"), and so this directive in the single
> "Index" node we have:
> 
>   @printindex cp
> 
> prints all of the index entries together.
> 
> > Your texinfo foo is better than mine - could you post a patch?
> 
> OK.

Here it is.  Does this solve your problem?


Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.978
diff -u -p -r1.978 gdb.texinfo
--- gdb.texinfo	22 Jun 2012 08:37:49 -0000	1.978
+++ gdb.texinfo	22 Jun 2012 10:01:35 -0000
@@ -18,13 +18,17 @@
 @end iftex
 
 @finalout
-@syncodeindex ky cp
-@syncodeindex tp cp
+@c To avoid file-name clashes between index.html and Index.html, when
+@c the manual is produced on a Posix host and then moved to a
+@c case-insensitive filesystem (e.g., MS-Windows), we separate the
+@c indices into two: Concept Index and all the rest.
+@syncodeindex ky fn
+@syncodeindex tp fn
 
 @c readline appendices use @vindex, @findex and @ftable,
 @c annotate.texi and gdbmi use @findex.
-@syncodeindex vr cp
-@syncodeindex fn cp
+@syncodeindex vr fn
+@syncodeindex fn fn
 
 @c !!set GDB manual's edition---not the same as GDB version!
 @c This is updated by GNU Press.
@@ -182,7 +186,9 @@ software in general.  We will miss him.
 * Copying::			GNU General Public License says
                                 how you can copy and share GDB
 * GNU Free Documentation License::  The license for this documentation
-* Index::                       Index
+* Concept Index::               Index of @value{GDBN} concepts
+* Command and Variable Index::  Index of @value{GDBN} commands, variables,
+                                  functions, and Python data types
 @end menu
 
 @end ifnottex
@@ -1780,8 +1786,9 @@ In addition to @code{help}, you can use 
 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}.
+under @code{info} and under @code{show} in the Command, Variable, and
+Function Index point to all the sub-commands.  @xref{Command and Variable
+Index}.
 
 @c @group
 @table @code
@@ -40415,11 +40422,16 @@ A string in the constant pool is zero-te
 @appendix GNU Free Documentation License
 @include fdl.texi
 
-@node Index
-@unnumbered Index
+@node Concept Index
+@unnumbered Concept Index
 
 @printindex cp
 
+@node Command and Variable Index
+@unnumbered Command, Variable, and Function Index
+
+@printindex fn
+
 @tex
 % I think something like @@colophon should be in texinfo.  In the
 % meantime:

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

Ping!  Should I commit this?

> Date: Fri, 22 Jun 2012 13:02:46 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
> 
> > Date: Fri, 22 Jun 2012 08:58:19 +0300
> > From: Eli Zaretskii <eliz@gnu.org>
> > Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
> > 
> > > >> > The problem with your suggestion is that the GDB index is not a
> > > >> > concept index, it is all the indices lumped into one.  But I would be
> > > >> > OK if we separate the concept index from the rest, and then we could
> > > >> > have "Concept Index" and "Command and Variable Index".
> > > >>
> > > >> I'd rather not go there as it's a big change for little gain.
> > > >
> > > > ??? It's as simple as modifying the "@syncodeindex" directives at the
> > > > beginning of gdb.texinfo, and then adding 2 @node lines for the two
> > > > indices, instead of the current one.  All the rest will be done by
> > > > makeinfo.  Am I missing something?
> > > 
> > > Sorry, I assumed that we'd have to check and perhaps update each index
> > > entry to see that it's in the right category.
> > 
> > No.  We already have separate index categories: see the @kindex,
> > @findex, @vindex, etc. directives, in addition to @cindex, that we
> > have all over the manual.  It's just that these 4 directives at the
> > beginning of gdb.texinfo:
> > 
> >   @syncodeindex ky cp
> >   @syncodeindex tp cp
> > 
> >   @c readline appendices use @vindex, @findex and @ftable,
> >   @c annotate.texi and gdbmi use @findex.
> >   @syncodeindex vr cp
> >   @syncodeindex fn cp
> > 
> > arrange for all of them to be lumped into a single index "cp" (which
> > stands for "Concept Index"), and so this directive in the single
> > "Index" node we have:
> > 
> >   @printindex cp
> > 
> > prints all of the index entries together.
> > 
> > > Your texinfo foo is better than mine - could you post a patch?
> > 
> > OK.
> 
> Here it is.  Does this solve your problem?
> 
> 
> Index: gdb.texinfo
> ===================================================================
> RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
> retrieving revision 1.978
> diff -u -p -r1.978 gdb.texinfo
> --- gdb.texinfo	22 Jun 2012 08:37:49 -0000	1.978
> +++ gdb.texinfo	22 Jun 2012 10:01:35 -0000
> @@ -18,13 +18,17 @@
>  @end iftex
>  
>  @finalout
> -@syncodeindex ky cp
> -@syncodeindex tp cp
> +@c To avoid file-name clashes between index.html and Index.html, when
> +@c the manual is produced on a Posix host and then moved to a
> +@c case-insensitive filesystem (e.g., MS-Windows), we separate the
> +@c indices into two: Concept Index and all the rest.
> +@syncodeindex ky fn
> +@syncodeindex tp fn
>  
>  @c readline appendices use @vindex, @findex and @ftable,
>  @c annotate.texi and gdbmi use @findex.
> -@syncodeindex vr cp
> -@syncodeindex fn cp
> +@syncodeindex vr fn
> +@syncodeindex fn fn
>  
>  @c !!set GDB manual's edition---not the same as GDB version!
>  @c This is updated by GNU Press.
> @@ -182,7 +186,9 @@ software in general.  We will miss him.
>  * Copying::			GNU General Public License says
>                                  how you can copy and share GDB
>  * GNU Free Documentation License::  The license for this documentation
> -* Index::                       Index
> +* Concept Index::               Index of @value{GDBN} concepts
> +* Command and Variable Index::  Index of @value{GDBN} commands, variables,
> +                                  functions, and Python data types
>  @end menu
>  
>  @end ifnottex
> @@ -1780,8 +1786,9 @@ In addition to @code{help}, you can use 
>  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}.
> +under @code{info} and under @code{show} in the Command, Variable, and
> +Function Index point to all the sub-commands.  @xref{Command and Variable
> +Index}.
>  
>  @c @group
>  @table @code
> @@ -40415,11 +40422,16 @@ A string in the constant pool is zero-te
>  @appendix GNU Free Documentation License
>  @include fdl.texi
>  
> -@node Index
> -@unnumbered Index
> +@node Concept Index
> +@unnumbered Concept Index
>  
>  @printindex cp
>  
> +@node Command and Variable Index
> +@unnumbered Command, Variable, and Function Index
> +
> +@printindex fn
> +
>  @tex
>  % I think something like @@colophon should be in texinfo.  In the
>  % meantime:
> 

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

On 2 July 2012 07:55, Eli Zaretskii <eliz@gnu.org> wrote:
> Ping!  Should I commit this?

It fixes my issue,

-- Michael

>> Date: Fri, 22 Jun 2012 13:02:46 +0300
>> From: Eli Zaretskii <eliz@gnu.org>
>> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
>>
>> > Date: Fri, 22 Jun 2012 08:58:19 +0300
>> > From: Eli Zaretskii <eliz@gnu.org>
>> > Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
>> >
>> > > >> > The problem with your suggestion is that the GDB index is not a
>> > > >> > concept index, it is all the indices lumped into one.  But I would be
>> > > >> > OK if we separate the concept index from the rest, and then we could
>> > > >> > have "Concept Index" and "Command and Variable Index".
>> > > >>
>> > > >> I'd rather not go there as it's a big change for little gain.
>> > > >
>> > > > ??? It's as simple as modifying the "@syncodeindex" directives at the
>> > > > beginning of gdb.texinfo, and then adding 2 @node lines for the two
>> > > > indices, instead of the current one.  All the rest will be done by
>> > > > makeinfo.  Am I missing something?
>> > >
>> > > Sorry, I assumed that we'd have to check and perhaps update each index
>> > > entry to see that it's in the right category.
>> >
>> > No.  We already have separate index categories: see the @kindex,
>> > @findex, @vindex, etc. directives, in addition to @cindex, that we
>> > have all over the manual.  It's just that these 4 directives at the
>> > beginning of gdb.texinfo:
>> >
>> >   @syncodeindex ky cp
>> >   @syncodeindex tp cp
>> >
>> >   @c readline appendices use @vindex, @findex and @ftable,
>> >   @c annotate.texi and gdbmi use @findex.
>> >   @syncodeindex vr cp
>> >   @syncodeindex fn cp
>> >
>> > arrange for all of them to be lumped into a single index "cp" (which
>> > stands for "Concept Index"), and so this directive in the single
>> > "Index" node we have:
>> >
>> >   @printindex cp
>> >
>> > prints all of the index entries together.
>> >
>> > > Your texinfo foo is better than mine - could you post a patch?
>> >
>> > OK.
>>
>> Here it is.  Does this solve your problem?
>>
>>
>> Index: gdb.texinfo
>> ===================================================================
>> RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
>> retrieving revision 1.978
>> diff -u -p -r1.978 gdb.texinfo
>> --- gdb.texinfo       22 Jun 2012 08:37:49 -0000      1.978
>> +++ gdb.texinfo       22 Jun 2012 10:01:35 -0000
>> @@ -18,13 +18,17 @@
>>  @end iftex
>>
>>  @finalout
>> -@syncodeindex ky cp
>> -@syncodeindex tp cp
>> +@c To avoid file-name clashes between index.html and Index.html, when
>> +@c the manual is produced on a Posix host and then moved to a
>> +@c case-insensitive filesystem (e.g., MS-Windows), we separate the
>> +@c indices into two: Concept Index and all the rest.
>> +@syncodeindex ky fn
>> +@syncodeindex tp fn
>>
>>  @c readline appendices use @vindex, @findex and @ftable,
>>  @c annotate.texi and gdbmi use @findex.
>> -@syncodeindex vr cp
>> -@syncodeindex fn cp
>> +@syncodeindex vr fn
>> +@syncodeindex fn fn
>>
>>  @c !!set GDB manual's edition---not the same as GDB version!
>>  @c This is updated by GNU Press.
>> @@ -182,7 +186,9 @@ software in general.  We will miss him.
>>  * Copying::                  GNU General Public License says
>>                                  how you can copy and share GDB
>>  * GNU Free Documentation License::  The license for this documentation
>> -* Index::                       Index
>> +* Concept Index::               Index of @value{GDBN} concepts
>> +* Command and Variable Index::  Index of @value{GDBN} commands, variables,
>> +                                  functions, and Python data types
>>  @end menu
>>
>>  @end ifnottex
>> @@ -1780,8 +1786,9 @@ In addition to @code{help}, you can use
>>  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}.
>> +under @code{info} and under @code{show} in the Command, Variable, and
>> +Function Index point to all the sub-commands.  @xref{Command and Variable
>> +Index}.
>>
>>  @c @group
>>  @table @code
>> @@ -40415,11 +40422,16 @@ A string in the constant pool is zero-te
>>  @appendix GNU Free Documentation License
>>  @include fdl.texi
>>
>> -@node Index
>> -@unnumbered Index
>> +@node Concept Index
>> +@unnumbered Concept Index
>>
>>  @printindex cp
>>
>> +@node Command and Variable Index
>> +@unnumbered Command, Variable, and Function Index
>> +
>> +@printindex fn
>> +
>>  @tex
>>  % I think something like @@colophon should be in texinfo.  In the
>>  % meantime:
>>

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> From: Michael Hope <michael.hope@linaro.org>
> Date: Mon, 2 Jul 2012 13:02:56 +1200
> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-patches@sourceware.org
> 
> On 2 July 2012 07:55, Eli Zaretskii <eliz@gnu.org> wrote:
> > Ping!  Should I commit this?
> 
> It fixes my issue,

Committed.

RE: [PATCH, doc]: Rename Index node to prevent file collision

[Terry Guo]

Hi Eli,

When "make html" for gdbint.texi on case-insensitive Mac OS X, we still meet
index.html and Index.html issue. Could you please also apply same fix to
gdbint.texi? Thanks.

BR,
Terry

> -----Original Message-----
> From: gdb-patches-owner@sourceware.org [mailto:gdb-patches-
> owner@sourceware.org] On Behalf Of Michael Hope
> Sent: Monday, July 02, 2012 9:03 AM
> To: Eli Zaretskii
> Cc: brobecker@adacore.com; joseph@codesourcery.com; gdb-
> patches@sourceware.org
> Subject: Re: [PATCH, doc]: Rename Index node to prevent file collision
> 
> On 2 July 2012 07:55, Eli Zaretskii <eliz@gnu.org> wrote:
> > Ping!  Should I commit this?
> 
> It fixes my issue,
> 
> -- Michael
> 
> >> Date: Fri, 22 Jun 2012 13:02:46 +0300
> >> From: Eli Zaretskii <eliz@gnu.org>
> >> Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-
> patches@sourceware.org
> >>
> >> > Date: Fri, 22 Jun 2012 08:58:19 +0300
> >> > From: Eli Zaretskii <eliz@gnu.org>
> >> > Cc: brobecker@adacore.com, joseph@codesourcery.com, gdb-
> patches@sourceware.org
> >> >
> >> > > >> > The problem with your suggestion is that the GDB index is
> not a
> >> > > >> > concept index, it is all the indices lumped into one.  But
> I would be
> >> > > >> > OK if we separate the concept index from the rest, and then
> we could
> >> > > >> > have "Concept Index" and "Command and Variable Index".
> >> > > >>
> >> > > >> I'd rather not go there as it's a big change for little gain.
> >> > > >
> >> > > > ??? It's as simple as modifying the "@syncodeindex" directives
> at the
> >> > > > beginning of gdb.texinfo, and then adding 2 @node lines for
> the two
> >> > > > indices, instead of the current one.  All the rest will be
> done by
> >> > > > makeinfo.  Am I missing something?
> >> > >
> >> > > Sorry, I assumed that we'd have to check and perhaps update each
> index
> >> > > entry to see that it's in the right category.
> >> >
> >> > No.  We already have separate index categories: see the @kindex,
> >> > @findex, @vindex, etc. directives, in addition to @cindex, that we
> >> > have all over the manual.  It's just that these 4 directives at
> the
> >> > beginning of gdb.texinfo:
> >> >
> >> >   @syncodeindex ky cp
> >> >   @syncodeindex tp cp
> >> >
> >> >   @c readline appendices use @vindex, @findex and @ftable,
> >> >   @c annotate.texi and gdbmi use @findex.
> >> >   @syncodeindex vr cp
> >> >   @syncodeindex fn cp
> >> >
> >> > arrange for all of them to be lumped into a single index "cp"
> (which
> >> > stands for "Concept Index"), and so this directive in the single
> >> > "Index" node we have:
> >> >
> >> >   @printindex cp
> >> >
> >> > prints all of the index entries together.
> >> >
> >> > > Your texinfo foo is better than mine - could you post a patch?
> >> >
> >> > OK.
> >>
> >> Here it is.  Does this solve your problem?
> >>
> >>
> >> Index: gdb.texinfo
> >> ===================================================================
> >> RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
> >> retrieving revision 1.978
> >> diff -u -p -r1.978 gdb.texinfo
> >> --- gdb.texinfo       22 Jun 2012 08:37:49 -0000      1.978
> >> +++ gdb.texinfo       22 Jun 2012 10:01:35 -0000
> >> @@ -18,13 +18,17 @@
> >>  @end iftex
> >>
> >>  @finalout
> >> -@syncodeindex ky cp
> >> -@syncodeindex tp cp
> >> +@c To avoid file-name clashes between index.html and Index.html,
> when
> >> +@c the manual is produced on a Posix host and then moved to a
> >> +@c case-insensitive filesystem (e.g., MS-Windows), we separate the
> >> +@c indices into two: Concept Index and all the rest.
> >> +@syncodeindex ky fn
> >> +@syncodeindex tp fn
> >>
> >>  @c readline appendices use @vindex, @findex and @ftable,
> >>  @c annotate.texi and gdbmi use @findex.
> >> -@syncodeindex vr cp
> >> -@syncodeindex fn cp
> >> +@syncodeindex vr fn
> >> +@syncodeindex fn fn
> >>
> >>  @c !!set GDB manual's edition---not the same as GDB version!
> >>  @c This is updated by GNU Press.
> >> @@ -182,7 +186,9 @@ software in general.  We will miss him.
> >>  * Copying::                  GNU General Public License says
> >>                                  how you can copy and share GDB
> >>  * GNU Free Documentation License::  The license for this
> documentation
> >> -* Index::                       Index
> >> +* Concept Index::               Index of @value{GDBN} concepts
> >> +* Command and Variable Index::  Index of @value{GDBN} commands,
> variables,
> >> +                                  functions, and Python data types
> >>  @end menu
> >>
> >>  @end ifnottex
> >> @@ -1780,8 +1786,9 @@ In addition to @code{help}, you can use
> >>  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}.
> >> +under @code{info} and under @code{show} in the Command, Variable,
> and
> >> +Function Index point to all the sub-commands.  @xref{Command and
> Variable
> >> +Index}.
> >>
> >>  @c @group
> >>  @table @code
> >> @@ -40415,11 +40422,16 @@ A string in the constant pool is zero-te
> >>  @appendix GNU Free Documentation License
> >>  @include fdl.texi
> >>
> >> -@node Index
> >> -@unnumbered Index
> >> +@node Concept Index
> >> +@unnumbered Concept Index
> >>
> >>  @printindex cp
> >>
> >> +@node Command and Variable Index
> >> +@unnumbered Command, Variable, and Function Index
> >> +
> >> +@printindex fn
> >> +
> >>  @tex
> >>  % I think something like @@colophon should be in texinfo.  In the
> >>  % meantime:
> >>

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> From: "Terry Guo" <terry.guo@arm.com>
> Cc: <brobecker@adacore.com>,
> 	<joseph@codesourcery.com>,
> 	<gdb-patches@sourceware.org>,
> 	"'Michael Hope'" <michael.hope@linaro.org>
> Date: Wed, 11 Jul 2012 13:14:59 +0800
> 
> Hi Eli,
> 
> When "make html" for gdbint.texi on case-insensitive Mac OS X, we still meet
> index.html and Index.html issue. Could you please also apply same fix to
> gdbint.texi? Thanks.

Done with the patch below.


2012-07-12  Eli Zaretskii  <eliz@gnu.org>

	* gdbint.texinfo: Remove @syncodeindex directives that put all the
	indices into a single node "Index".  Instead, join function and
	variable indices into a single index, separate from the concept
	index.  Requested in
	http://sourceware.org/ml/gdb-patches/2012-07/msg00146.html.
	(Top): Update the top-level menu: instead of one "Index" there are
	now separate entries "Concept Index" and "Function and Variable
	Index".
	(Concept Index, Function and Variable Index): New nodes.
	(Index): Node deleted.

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.338
diff -u -r1.338 gdbint.texinfo
--- gdbint.texinfo	15 Jun 2012 09:21:36 -0000	1.338
+++ gdbint.texinfo	12 Jul 2012 07:55:15 -0000
@@ -28,9 +28,7 @@
 @insertcopying
 @end ifnottex
 
-
-@syncodeindex fn cp
-@syncodeindex vr cp
+@syncodeindex vr fn
 
 @titlepage
 @title @value{GDBN} Internals
@@ -93,7 +91,8 @@
 
 * GDB Observers::  @value{GDBN} Currently available observers
 * GNU Free Documentation License::  The license for this documentation
-* Index::
+* Concept Index::
+* Function and Variable Index::
 @end menu
 
 @node Summary
@@ -8132,9 +8131,14 @@
 @appendix GNU Free Documentation License
 @include fdl.texi
 
-@node Index
-@unnumbered Index
+@node Concept Index
+@unnumbered Concept Index
 
 @printindex cp
 
+@node Function and Variable Index
+@unnumbered Function and Variable Index
+
+@printindex fn
+
 @bye

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Eli Zaretskii]

> From: Michael Hope <michael.hope@linaro.org>
> Date: Fri, 15 Jun 2012 09:43:21 +1200
> Cc: "Joseph S. Myers" <joseph@codesourcery.com>, gdb-patches@sourceware.org
> 
> > Michael, is your setup also that you produce the HTML files on a Posix
> > host, but then deploy them on Windows?
> 
> Yip.  We supply pre-built toolchains for Linux and Windows[1].  The
> build is crtosstool-NG based, runs on Ubuntu Lucid, and uses the LSB
> compilers for Linux and the mingw cross compilers for Windows.  We
> cross-make the manuals the same as we cross-build the compiler.

Can you simply concatenate the two [iI]ndex.html files into the same
file?

> The makeinfo manual says: """If makeinfo is run on a system which does
> not distinguish case in filenames, nodes which are the same except for
> case will also be folded into the same output file.""".

What that means is that the file index.html should have 2 nodes on it,
each with its own label, so HTML references work correctly.  Why is
this a problem?

Re: [PATCH, doc]: Rename Index node to prevent file collision

[Michael Hope]

On 15 June 2012 19:28, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Michael Hope <michael.hope@linaro.org>
>> Date: Fri, 15 Jun 2012 09:43:21 +1200
>> Cc: "Joseph S. Myers" <joseph@codesourcery.com>, gdb-patches@sourceware.org
>>
>> > Michael, is your setup also that you produce the HTML files on a Posix
>> > host, but then deploy them on Windows?
>>
>> Yip.  We supply pre-built toolchains for Linux and Windows[1].  The
>> build is crtosstool-NG based, runs on Ubuntu Lucid, and uses the LSB
>> compilers for Linux and the mingw cross compilers for Windows.  We
>> cross-make the manuals the same as we cross-build the compiler.
>
> Can you simply concatenate the two [iI]ndex.html files into the same
> file?

Not without rewriting the HTML versions as each have their own head and body.

>> The makeinfo manual says: """If makeinfo is run on a system which does
>> not distinguish case in filenames, nodes which are the same except for
>> case will also be folded into the same output file.""".
>
> What that means is that the file index.html should have 2 nodes on it,
> each with its own label, so HTML references work correctly.  Why is
> this a problem?

It's not what the author asked for and confuses the reader by
increasing the clutter.  The Top node introduces the user to the
documentation and should be minimal.

There's no way of doing this in makeinfo 4.13b on a case insensitive
filesystem.  If we need to patch makeinfo then I'd rather have one
file per node.

-- Michael