Generated GDB documentation have colliding files on a case insensitive files system

Generated GDB documentation have colliding files on a case insensitive files system

[Torbjorn SVENSSON]

Hi,

If the HTML documentation is put on a case insensitive files system 
(like those used in Windows), there are 2 files that collides:
qMemTags.html and QMemTags.html.

Both the files contains a simple redirect to their corresponding anchor 
in General-Query-Packets.html, and there appears to be no link to 
[qQ]MemTags.html in any of the other generated HTML files.
I'm currently leaning towards that these redirect files are not really 
needed and that they should have been omitted.

As it's correct to document both qMemTags and QMemTags, and that the two 
RSP commands are indeed different, I see the following potential 
solutions to the collision:

* Leave it as is and live with the collision for users extracting an 
archive with the HTML documentation on a case insensitive files system.

* Use the "--no-split" argument to makeinfo to generate a single big 
HTML file for all the documentation rather than one HTML file per @node. 
This solution might have other consequences that I'm not aware of as 
there are multiple texi files in the GDB source tree...

* After invoking makeinfo, remove all the generated redirect pages 
(appears to be ~214 files).


Is there any other solution that I have no thought of?

What solution is preferred?

I've also started a thread on the bug-texinfo list about adding a 
warning for this problem when running the makeinfo command. The thread 
can be found here: 
https://lists.gnu.org/archive/html/bug-texinfo/2023-01/msg00030.html

Kind regards,
Torbjörn

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Eli Zaretskii]

> Date: Sat, 7 Jan 2023 10:21:49 +0100
> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> CC: Eli Zaretskii <eliz@gnu.org>
> 
> If the HTML documentation is put on a case insensitive files system 
> (like those used in Windows), there are 2 files that collides:
> qMemTags.html and QMemTags.html.
> 
> Both the files contains a simple redirect to their corresponding anchor 
> in General-Query-Packets.html, and there appears to be no link to 
> [qQ]MemTags.html in any of the other generated HTML files.
> I'm currently leaning towards that these redirect files are not really 
> needed and that they should have been omitted.
> 
> As it's correct to document both qMemTags and QMemTags, and that the two 
> RSP commands are indeed different, I see the following potential 
> solutions to the collision:
> 
> * Leave it as is and live with the collision for users extracting an 
> archive with the HTML documentation on a case insensitive files system.
> 
> * Use the "--no-split" argument to makeinfo to generate a single big 
> HTML file for all the documentation rather than one HTML file per @node. 
> This solution might have other consequences that I'm not aware of as 
> there are multiple texi files in the GDB source tree...
> 
> * After invoking makeinfo, remove all the generated redirect pages 
> (appears to be ~214 files).
> 
> 
> Is there any other solution that I have no thought of?

Yes, there are other solutions.  For example, one of the files could
have been renamed to a different name, when the collision is detected.

FWIW, the old makeinfo 4.x did succeed to avoid file-name conflicts in
this and other similar cases.  That solution it used was lost when
makeinfo was reimplemented in Perl, and AFAIU it cannot be easily
adopted by the current makeinfo implementation, because it changed the
way nodes are references in the "<a href" links of the produced HTML.

> I've also started a thread on the bug-texinfo list about adding a 
> warning for this problem when running the makeinfo command. The thread 
> can be found here: 
> https://lists.gnu.org/archive/html/bug-texinfo/2023-01/msg00030.html

Let's wait for that other discussion to conclude, and then take it
from there.  I'd prefer a solution in Texinfo rather than in GDB, as
this is a general problem.

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Torbjorn SVENSSON]

On 2023-01-07 10:37, Eli Zaretskii wrote:
>> Date: Sat, 7 Jan 2023 10:21:49 +0100
>> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
>> CC: Eli Zaretskii <eliz@gnu.org>
>>
>> If the HTML documentation is put on a case insensitive files system
>> (like those used in Windows), there are 2 files that collides:
>> qMemTags.html and QMemTags.html.
>>
>> Both the files contains a simple redirect to their corresponding anchor
>> in General-Query-Packets.html, and there appears to be no link to
>> [qQ]MemTags.html in any of the other generated HTML files.
>> I'm currently leaning towards that these redirect files are not really
>> needed and that they should have been omitted.
>>
>> As it's correct to document both qMemTags and QMemTags, and that the two
>> RSP commands are indeed different, I see the following potential
>> solutions to the collision:
>>
>> * Leave it as is and live with the collision for users extracting an
>> archive with the HTML documentation on a case insensitive files system.
>>
>> * Use the "--no-split" argument to makeinfo to generate a single big
>> HTML file for all the documentation rather than one HTML file per @node.
>> This solution might have other consequences that I'm not aware of as
>> there are multiple texi files in the GDB source tree...
>>
>> * After invoking makeinfo, remove all the generated redirect pages
>> (appears to be ~214 files).
>>
>>
>> Is there any other solution that I have no thought of?
> 
> Yes, there are other solutions.  For example, one of the files could
> have been renamed to a different name, when the collision is detected.
> 
> FWIW, the old makeinfo 4.x did succeed to avoid file-name conflicts in
> this and other similar cases.  That solution it used was lost when
> makeinfo was reimplemented in Perl, and AFAIU it cannot be easily
> adopted by the current makeinfo implementation, because it changed the
> way nodes are references in the "<a href" links of the produced HTML.

Ok. I've never really cared about how the makeinfo command works for 
even looked at the implementation prior to noticing this issue and 
sending the patch yesterday.

Do you see any use of the ~214 redirect pages in the GDB context?

> 
>> I've also started a thread on the bug-texinfo list about adding a
>> warning for this problem when running the makeinfo command. The thread
>> can be found here:
>> https://lists.gnu.org/archive/html/bug-texinfo/2023-01/msg00030.html
> 
> Let's wait for that other discussion to conclude, and then take it
> from there.  I'd prefer a solution in Texinfo rather than in GDB, as
> this is a general problem.

I agree.

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Eli Zaretskii]

> Date: Sat, 7 Jan 2023 10:42:11 +0100
> CC: <gdb-patches@sourceware.org>
> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> 
> Do you see any use of the ~214 redirect pages in the GDB context?

Sorry, I don't understand the question.  What do you mean by "see any
use" in this context?

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Torbjorn SVENSSON]

On 2023-01-07 11:43, Eli Zaretskii wrote:
>> Date: Sat, 7 Jan 2023 10:42:11 +0100
>> CC: <gdb-patches@sourceware.org>
>> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
>>
>> Do you see any use of the ~214 redirect pages in the GDB context?
> 
> Sorry, I don't understand the question.  What do you mean by "see any
> use" in this context?

I was considering if the redirect files could simply be removed from the 
GDB documentation tree or if they are actually used for inter components 
references.

I'm more or less trying to find the best solution for GDB.

There is the possibility to rename one of the [qQ]MemTags anchors in the 
GDB documentation, but that will also include the alternative name in 
the redirect page and it would require all the @xref etc to be updated 
to the renamed anchor.

Even if we get a solution merged in texinfo, it will take years for it 
to get activity used, and in the mean while, we are stuck with this 
issue in GDB.

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Eli Zaretskii]

> Date: Sat, 7 Jan 2023 11:52:45 +0100
> CC: <gdb-patches@sourceware.org>
> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> 
> On 2023-01-07 11:43, Eli Zaretskii wrote:
> >> Date: Sat, 7 Jan 2023 10:42:11 +0100
> >> CC: <gdb-patches@sourceware.org>
> >> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> >>
> >> Do you see any use of the ~214 redirect pages in the GDB context?
> > 
> > Sorry, I don't understand the question.  What do you mean by "see any
> > use" in this context?
> 
> I was considering if the redirect files could simply be removed from the 
> GDB documentation tree or if they are actually used for inter components 
> references.

They are produced by makeinfo, and they are produced for a reason, no?

> I'm more or less trying to find the best solution for GDB.
> 
> There is the possibility to rename one of the [qQ]MemTags anchors in the 
> GDB documentation, but that will also include the alternative name in 
> the redirect page and it would require all the @xref etc to be updated 
> to the renamed anchor.
> 
> Even if we get a solution merged in texinfo, it will take years for it 
> to get activity used, and in the mean while, we are stuck with this 
> issue in GDB.

I still don't want to make any conclusions until the Texinfo
discussion is completed.  How do you know there's no solution with the
existing Texinfo versions?

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Torbjorn SVENSSON]

On 2023-01-07 12:08, Eli Zaretskii wrote:
>> Date: Sat, 7 Jan 2023 11:52:45 +0100
>> CC: <gdb-patches@sourceware.org>
>> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
>>
>> On 2023-01-07 11:43, Eli Zaretskii wrote:
>>>> Date: Sat, 7 Jan 2023 10:42:11 +0100
>>>> CC: <gdb-patches@sourceware.org>
>>>> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
>>>>
>>>> Do you see any use of the ~214 redirect pages in the GDB context?
>>>
>>> Sorry, I don't understand the question.  What do you mean by "see any
>>> use" in this context?
>>
>> I was considering if the redirect files could simply be removed from the
>> GDB documentation tree or if they are actually used for inter components
>> references.
> 
> They are produced by makeinfo, and they are produced for a reason, no?

According to the other thread, they are generated to easy cross linking 
the documentation. There is nothing in the documentation that will 
generate a link to any of these files, so hence the question if they are 
needed by GDB.

> 
>> I'm more or less trying to find the best solution for GDB.
>>
>> There is the possibility to rename one of the [qQ]MemTags anchors in the
>> GDB documentation, but that will also include the alternative name in
>> the redirect page and it would require all the @xref etc to be updated
>> to the renamed anchor.
>>
>> Even if we get a solution merged in texinfo, it will take years for it
>> to get activity used, and in the mean while, we are stuck with this
>> issue in GDB.
> 
> I still don't want to make any conclusions until the Texinfo
> discussion is completed.  How do you know there's no solution with the
> existing Texinfo versions?

As I understood it, it was proved that the redirect pages were colliding 
and no way around that in current implementation, but maybe I 
misunderstood the reply...

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Eli Zaretskii]

> Date: Mon, 9 Jan 2023 07:51:17 +0100
> CC: <gdb-patches@sourceware.org>
> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> 
> >> I was considering if the redirect files could simply be removed from the
> >> GDB documentation tree or if they are actually used for inter components
> >> references.
> > 
> > They are produced by makeinfo, and they are produced for a reason, no?
> 
> According to the other thread, they are generated to easy cross linking 
> the documentation. There is nothing in the documentation that will 
> generate a link to any of these files, so hence the question if they are 
> needed by GDB.

Maybe I'm confused, but don't you above answer your own question?
"Easy cross linking" is the reason.

> >> Even if we get a solution merged in texinfo, it will take years for it
> >> to get activity used, and in the mean while, we are stuck with this
> >> issue in GDB.
> > 
> > I still don't want to make any conclusions until the Texinfo
> > discussion is completed.  How do you know there's no solution with the
> > existing Texinfo versions?
> 
> As I understood it, it was proved that the redirect pages were colliding 
> and no way around that in current implementation, but maybe I 
> misunderstood the reply...

AFAIU, it's a bug in Texinfo.  I hope they will solve it at some
point.

But now let me turn the table and ask you why we as a project should
care about HTML version of the manual being installed on MS-Windows?

Having said that, I have no serious objections to changing the name of
the anchor if it will solve the problem for you.

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Torbjorn SVENSSON]

On 2023-01-09 13:24, Eli Zaretskii wrote:
>> Date: Mon, 9 Jan 2023 07:51:17 +0100
>> CC: <gdb-patches@sourceware.org>
>> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
>>
>>>> I was considering if the redirect files could simply be removed from the
>>>> GDB documentation tree or if they are actually used for inter components
>>>> references.
>>>
>>> They are produced by makeinfo, and they are produced for a reason, no?
>>
>> According to the other thread, they are generated to easy cross linking
>> the documentation. There is nothing in the documentation that will
>> generate a link to any of these files, so hence the question if they are
>> needed by GDB.
> 
> Maybe I'm confused, but don't you above answer your own question?
> "Easy cross linking" is the reason.

Well, cross linking from other manuals.
Does this requirement jump the need to actually have all the content? :)

> 
>>>> Even if we get a solution merged in texinfo, it will take years for it
>>>> to get activity used, and in the mean while, we are stuck with this
>>>> issue in GDB.
>>>
>>> I still don't want to make any conclusions until the Texinfo
>>> discussion is completed.  How do you know there's no solution with the
>>> existing Texinfo versions?
>>
>> As I understood it, it was proved that the redirect pages were colliding
>> and no way around that in current implementation, but maybe I
>> misunderstood the reply...
> 
> AFAIU, it's a bug in Texinfo.  I hope they will solve it at some
> point.
> 
> But now let me turn the table and ask you why we as a project should
> care about HTML version of the manual being installed on MS-Windows?

I'm just seeing that there are toolchains out there that contains a 
prebuilt GCC and GDB and that they contain documentation in the form of 
HTML files. I suppose these packages could be seen as the bad part here, 
but is it really so. Can't GDB improve the way the HTML manuals are 
constructed in a way that would work regardless of where they end up?


> Having said that, I have no serious objections to changing the name of
> the anchor if it will solve the problem for you.

Looks like there will a warning emitted now when generating the HTML 
files if there are more than one anchor/node with a unique name on case 
insensitive files systems as long as the CASE_INSENSITIVE_FILENAMES 
option is set with the next version of Texinfo.

As I see it, there are 3 different options for the documentation in GDB:

1. Leave everything as is and forget about all users extracting a cross 
built GDB with documentation and let the users deal with duplicated files...

2. Set the CASE_INSENSITIVE_FILENAMES option and also change one of the 
anchors to have unique files. This will require Texinfo >7.0.1 that is 
not yet released.

3. Generate one single big HTML file. This should be supported with 
existing versions of Texinfo, although I haven't tested this option.
What would be needed in GDB sources is to replace the command line 
option --split-size with --no-split to avoid generating more than one file.


What option would you prefer?


Kind regards,
Torbjörn

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Eli Zaretskii]

> Date: Sun, 15 Jan 2023 18:22:54 +0100
> CC: <gdb-patches@sourceware.org>
> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> 
> As I see it, there are 3 different options for the documentation in GDB:
> 
> 1. Leave everything as is and forget about all users extracting a cross 
> built GDB with documentation and let the users deal with duplicated files...
> 
> 2. Set the CASE_INSENSITIVE_FILENAMES option and also change one of the 
> anchors to have unique files. This will require Texinfo >7.0.1 that is 
> not yet released.
> 
> 3. Generate one single big HTML file. This should be supported with 
> existing versions of Texinfo, although I haven't tested this option.
> What would be needed in GDB sources is to replace the command line 
> option --split-size with --no-split to avoid generating more than one file.
> 
> 
> What option would you prefer?

I think we should rename one of the anchors, and otherwise leave
things at that, because doing so will resolve the problem even without
using CASE_INSENSITIVE_FILENAMES and without waiting for a future
release of Texinfo, right?

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Torbjorn SVENSSON]

On 2023-01-15 18:39, Eli Zaretskii wrote:
>> Date: Sun, 15 Jan 2023 18:22:54 +0100
>> CC: <gdb-patches@sourceware.org>
>> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
>>
>> As I see it, there are 3 different options for the documentation in GDB:
>>
>> 1. Leave everything as is and forget about all users extracting a cross
>> built GDB with documentation and let the users deal with duplicated files...
>>
>> 2. Set the CASE_INSENSITIVE_FILENAMES option and also change one of the
>> anchors to have unique files. This will require Texinfo >7.0.1 that is
>> not yet released.
>>
>> 3. Generate one single big HTML file. This should be supported with
>> existing versions of Texinfo, although I haven't tested this option.
>> What would be needed in GDB sources is to replace the command line
>> option --split-size with --no-split to avoid generating more than one file.
>>
>>
>> What option would you prefer?
> 
> I think we should rename one of the anchors, and otherwise leave
> things at that, because doing so will resolve the problem even without
> using CASE_INSENSITIVE_FILENAMES and without waiting for a future
> release of Texinfo, right?

I suppose that would work, but there would be no indication of a 
potential future clash. Maybe that's okay anyway?

Re: Generated GDB documentation have colliding files on a case insensitive files system

[Eli Zaretskii]

> Date: Sun, 15 Jan 2023 18:43:53 +0100
> CC: <gdb-patches@sourceware.org>
> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> 
> On 2023-01-15 18:39, Eli Zaretskii wrote:
> >> Date: Sun, 15 Jan 2023 18:22:54 +0100
> >> CC: <gdb-patches@sourceware.org>
> >> From: Torbjorn SVENSSON <torbjorn.svensson@foss.st.com>
> >>
> >> As I see it, there are 3 different options for the documentation in GDB:
> >>
> >> 1. Leave everything as is and forget about all users extracting a cross
> >> built GDB with documentation and let the users deal with duplicated files...
> >>
> >> 2. Set the CASE_INSENSITIVE_FILENAMES option and also change one of the
> >> anchors to have unique files. This will require Texinfo >7.0.1 that is
> >> not yet released.
> >>
> >> 3. Generate one single big HTML file. This should be supported with
> >> existing versions of Texinfo, although I haven't tested this option.
> >> What would be needed in GDB sources is to replace the command line
> >> option --split-size with --no-split to avoid generating more than one file.
> >>
> >>
> >> What option would you prefer?
> > 
> > I think we should rename one of the anchors, and otherwise leave
> > things at that, because doing so will resolve the problem even without
> > using CASE_INSENSITIVE_FILENAMES and without waiting for a future
> > release of Texinfo, right?
> 
> I suppose that would work, but there would be no indication of a 
> potential future clash. Maybe that's okay anyway?

There's any number of potential problems that could potentially happen
in the future.  If we start worrying about all of them, we will have
no time to do anything useful.  Let's worry about problems that really
happen when they happen.