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

Michael Hope
2012-06-21T04:20:28Z

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