Re: HTML <title> node names: Not emitting 'Top (Manual name)'

[email protected] Sat, 16 Mar 2024 15:13:04 +0100
Newsgroups gmane.comp.tex.texinfo.general
Message-ID <[email protected]> 
On Sat, Mar 16, 2024 at 09:29:59AM +0200, Eli Zaretskii wrote:
> > For example, I looked at the mentioned code at
> > https://git.savannah.gnu.org/cgit/emacs.git/tree/admin/admin.el
> > (the manual-html-fix-* functions) and it is not instantly apparent what
> > all of the code is supposed to achieve.
> 
> Welcome to the club.  The person(s) who wrote that code are no longer
> active in Emacs development, so asking them is not an option.

Is there somebody still overseeing that process in term of desired
output?

> My suggestion is to compare the original HTML files produced by
> makeinfo with the massaged files on the GNU Software site, and try
> guessing from the diffs what that code is trying to do.  My hope is
> that any HTML expert (which I am not) will have a good guess by
> looking at the diffs (and possibly also at how the results of
> processing are shown in a browser, as compared to the original HTML
> files produced by makeinfo).

I did that.  There are some changes that I understand, but some that I
don't.  I know almost nothing about lisp, but looking at the code and at
the output, it seems to me that most of the code does nothing nowadays,
or have unintended consequences.  It seems actually that this code was
mainly targeting Texinfo 5 (and older) makeinfo HTML output but has not
really been changed to work with more recent releases.  This is visible
in constructs that are matched that are, in general, no longer present,
although it is unclear whether matching is intended or not.

Here are my interrogations.  First I have three questions about removed
HTML in the that look suspicious to me.  I think that it should be
checked if this is intended, my wild guess is that it is not:
1) the Copyright notice in comments at the very beginning is removed.
2) the <link href=... rel=... > in <head> are removed, for example
  <link href="#Top" rel="start" title="top">
  <link href="#Starting-Rules" rel="next" title="Starting Rules">
3) For non split output, the first header/navigation panel is removed.

The other main interrogation is about the manual-html-fix-index-1,
manual-html-fix-index-2 defun and closing </div> code in manual-html-mono
manual-html-node.  Most of these codes seems to do nothing nowadays,
except for one thing, adding, right after <body ...> an
<div id="content" class="inner">
and adding matching </div>.  The matching </div> is at the very end of the
file for the mono manual, and right before the table of contents
in the node split index.html file.  It is not clear to me what this div
is used for.  I had a look at the CSS files, both
https://www.gnu.org/software/emacs/manual.css
https://www.gnu.org/style.css
and I did not find a mention of the 'inner' class.  The id="content" may
still be used to link from other HTML pages to those places in emacs
HTML manuals, but I think that this should be checked if this id is
really needed, it seems like a bad idea to add an id like that,
referring to the file should be better.  (If it is still needed, maybe
it could be placed on the <body> instead.)

My last important interrogation is about CSS.  The whole CSS added by
texi2any is removed, instead of using the possibility offered by the
command-line.  My feeling is that what is done right now would be better
achieved either by calling with
 --css-include=/software/emacs/manual.css
although it may not lead to the wanted result if there is some
disagreement between the CSS output bu texi2any and the emacs CSS.
Another possibility would be to add a file named, for example
import_emacs_css.css which would only contain

@import url('/software/emacs/manual.css');

and use
  --css-ref=..../import_emacs_css.css
at the command-line.

I think that it would be better if the texi2any CSS was kept as some is
important for some features, such as copiable links.  In the CSS file
https://www.gnu.org/style.css I also noticed that some parts refer to
classes no longer used, which is ok if old releases are targeted, but
the new class is not there, which makes wonder if some of the code is
still needed.



Some other remarks, but I would prefer if the issues were not fixed
actually ;-).

It seems to me that the manual-html-fix-node-div defun does nothing
for recent Texinfo releases.

I also think that the code in manual-html-node that tries to move
Copyright, starting with
                  ;; Move copyright notice to the end.
does nothing (though by looking at the code it could have), but
I think that it is better that it does nothing, this looks like a bad
idea to me.

-- 
Pat