Re: [PATCH] Warn user when 2 files conflict on a case insensitive fs

[Patrice Dumas]

On Sat, Jan 07, 2023 at 09:52:17AM +0100, Torbjorn SVENSSON wrote:
> 
> Okay, maybe I was unclear in the first mail.
> What I'm doing is building the manual on a GNU/Linux system with a case
> sensitive file system. This means that the build is fine and there is no way
> for the makeinfo command to know what implications the generated filenames
> will have in the future. What happens later is that the tree containing the
> binaries and the documentation is zip'ed and put on a Windows system with a
> case insensitive file system. During the unzip'ing of the file, the 2
> qMemTags.html and QMemTags.html files collide and the zip utility asks the
> user to replace/append/ignore/... and I would like to avoid having this
> question at all.
> An example of such a package can be download from 
> https://developer.arm.com/-/media/Files/downloads/gnu/11.3.rel1/binrel/arm-gnu-toolchain-11.3.rel1-mingw-w64-i686-arm-none-eabi.zip?rev=82f0e95b5a7740d9899e6ce375df8106&hash=E8C79FCFC43534AC1D691CBEE00F34D0

This is very clear, and for that use case setting CASE_INSENSITIVE_FILENAMES
should really be what you should do.  CASE_INSENSITIVE_FILENAMES works
as intended for nodes with the same file name, they are concatenated,
such that there is no problem later on case insensitive filesystems.
However, with redirection files, which would be created for anchors when
split at node, but created for every node if not split,
CASE_INSENSITIVE_FILENAMES does not work as intended, as two conflicting
files are created. 

> To make the developer of the documentation aware of this possible problem
> further down the road, I tried to add the warning in the most generic
> function I could find in the sources of makeinfo command, but it might be
> the wrong place.

Indeed, I think that it should be in a more specific place, stating
something clearer about redirection file, for instance that a
redirection file cannot be created for @node XX because @anchor YY (or
@float label) is already associated to that redirection file.  Another
even more involved solution would be to remove the automatic redirection
when there are two nodes redirected from a redirection page, and only
leave the text for the user to click on.  Or use javascript to do the
redirection, and without javascript there would be a need to click on
the appropriate link.

> What I've noticed is this problem for redirection pages, but maybe it can
> happen for other kinds of output pages too?

See above why it should not happen for other pages, at least if
CASE_INSENSITIVE_FILENAMES is set, as they will be concatenated.

> Will makeinfo ever generate a reference to one of these redirection pages or
> are they there just to provide an easy way to jump to the right anchor in
> the other generated pages?

There is never a reference to those redirection pages from the document,
they are instead here to redirect links to those pages.  The use case we
had in mind for doing those redirects is not an easy way to jump to the
right anchor, but such that cross manual links to @anchor work as
intended.  How cross-references are constructed is described in details
in the manual

https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref.html

There is a mention of the issue of case-insensitive file names and why
is may not be an issue at the end of the node, but it does not cover
redirection mpages, for which the mismatch is problematic as there is
only one possible redirection per file based on the file name:
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Xref-Node-Name-Expansion.html

The redirection pages are not described that much, there is a
mention in
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/HTML-Splitting.html


> in), you can see it online here:
> https://sourceware.org/gdb/current/onlinedocs/gdb/qMemTags.html
> https://sourceware.org/gdb/current/onlinedocs/gdb/QMemTags.html
> 
> Both those redirect pages redirect to "General-Query-Packets.html#qMemTags"
> and "General-Query-Packets.html#QMemTags" respectivly. Would makeinfo ever
> generate a link to one of the qMemTags.html or QMemTags.html or will it
> always us the anchor in General-Query-Packets.html in this example?

It will use the anchor in General-Query-Packets.html from inside the
manual.

> The GDB documentation is built using the following command on my system:
> makeinfo --split-size=5000000 --split-size=5000000 \
>  -DHAVE_MAKEINFO_CLICK --html  \
>   -I /src/gdb/gdb/doc/../../readline/readline/doc \
>   -I /src/gdb/gdb/doc/../mi \
>   -I /src/gdb/gdb/doc \
>   /src/gdb/gdb/doc/gdb.texinfo
> 
> From the GDB point of view (still to be confirmed), I believe the
> documentation should be split on the @node level and that all the redirect
> pages to the @item nodes for the various RSP commands in the example above
> is not desired. If the undesired redirect pages where not generated, then
> the issue that I'm currently seeing would not be visible. I suppose it could
> still happen if the @node is using different case (like
> https://sourceware.org/pipermail/newlib/2022/020032.html) but that's a
> slightly different topic.

Indeed, which is already correctly convered, I think.


Another different topic and possible more problematic issue is what
happens when generating the manual on a case-insensitive filesystem and
CASE_INSENSITIVE_FILENAMES is not set.  I think that the output is
incorrect, but let's see the result of Eli test.

-- 
Pat