On 2023-01-06 22:52, Gavin Smith wrote:
On Fri, Jan 06, 2023 at 08:47:52PM +0100, Patrice Dumas wrote:
On Fri, Jan 06, 2023 at 01:28:04PM +0100, Torbjörn SVENSSON wrote:
Hi,
I can't find where to send patches, so pardon me if this is the wrong
channel.
It is the right channel.
I recently noticed a problem doing a building GDB for Windows on a
GNU/Linux host. The documentation contains 'qMemTags' and 'QMemTags'
and as GDB is using the --split-size argument, the --node-files is
automatically activated and a bunch of redirect files are generated,
including qMemTags.html and QMemTags.html. As these 2 files have the
"same" filename on Windows, the content of one of them will be used,
but it's unpredictable witch one. So, to make the developers aware
of this situation, I added a simple warning to makeinfo about the
potential problem for case insensitive file systems.
I recall some discussion on this list, and I remember that the end
result was that it was not a good thing to consider something special
on platforms that have case sensitive filesystems. One possibility would
be to have the warning emitted conditionally on having the
CASE_INSENSITIVE_FILENAMES customization variable set. With that setup,
also, I think that the warning will be emitted only in case of a conflict
between a redirection node and another file, conflict among normal file
output will be silenced because the nodes will simply be appended
without trying to open a new file.
I agree, it would be fine to have warning if more than one node/"output
unit" actually gets appended to an output file because of
CASE_INSENSITIVE_FILENAMES.
The manual seems to imply that CASE_INSENSITIVE_FILENAMES does not
need to be set by the user if the file system is case insensitive. If
that is true, then the following shouldn't happen:
As these 2 files have the "same" filename on Windows, the content
of one of them will be used, but it's unpredictable witch one.
It shouldn't happen that the output is lost for the contents of
one of the files - all the output should be present in the file.
Can we confirm what is actually happening?
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
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.
What I've noticed is this problem for redirection pages, but maybe it
can happen for other kinds of output pages too?
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?
If you want to look at the GDB documentation (where this issue was
noticed 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?
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.
There are some issues with the patch, I think.
* the warning messages comes somewhat too late, there is not much
information on the node or nodes conflicting, it is up to the user
to find out which nodes are in clonflict. Maybe this check should
be done before, and even quite early, after the determination of the
file names, but before any actual output. Maybe after the call of
_set_root_commands_targets_node_files and only if NODE_FILES is set.
Maybe in Texinfo::Convert::Converter::set_tree_unit_file or
Texinfo::Covert::HTML::_html_set_pages_files. The following in the
latter function already keeps track of how often an output file
is used:
$self->set_tree_unit_file($tree_unit, $filename);
my $tree_unit_filename = $tree_unit->{'structure'}->{'unit_filename'};
$self->{'file_counters'}->{$tree_unit_filename} = 0
if (!exists($self->{'file_counters'}->{$tree_unit_filename}));
$self->{'file_counters'}->{$tree_unit_filename}++;
I haven't investigated it but I suspect this counter only goes above
1 if there is the case-insensitive filename issue, in which case
a warning could be issued that multiple "tree units" are being
concatenated in a single file.
