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

[Torbjorn SVENSSON]

On 2023-01-07 11:09, Patrice Dumas wrote:
> 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.

If this is clear that I should have been using the 
CASE_INSENSITIVE_FILENAMES setting, why is it not always active?
Again, when running makeinfo, there is nothing that indicates where the 
output will be placed and it's out of makeinfo's possibility to identify 
the problems that lies ahead if transferred to a file system that is 
case insensitive. If there is a feature that detects the problem when 
running makeinfo on a file system that is case insensitive, that's 
great, but why does it need to be handled differently from file systems 
that are case sensitive?
I, as a user, would expect to have the same documentation generated 
regardless if I happen to run makeinfo on a Windows host or a GNU/Linux 
host. Doesn't that requirement make sense to you?

> > 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.

I can buy the idea of not having an automatic redirect in the case of a 
conflict. Would you like me to try to write a patch for that scenario?

> > 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.

In the newlib case, there were a chapter (Iconv.html) and a node 
(iconv.html) and the solution that "fixed" the problem was to rename the 
chapter. I suppose this is also a problem in the current implementation 
of text2any as it's simply pushed to the user to resolve rather than 
having the tool generate unique filenames/aborting in the case of 
conflicting filenames.

> 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.