> Date: Sat, 16 Mar 2024 15:13:04 +0100 > From: pertu...@free.fr > Cc: Gavin Smith <gavinsmith0...@gmail.com>, ar...@aarsen.me, > help-texinfo@gnu.org > > 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?
I do, but I just quickly compare how the new and the previous manuals look, to make sure the look-and-feel are preserved. I don't review (and frequently don't even understand well enough) the stuff that is not shown, but which affects the browser reaction to some gestures. > > 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. Is it important? > 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"> Look at how the produced HTML looks vs the one on the site: those links are the "Short TOC", which is completely redundant for reading the manual on-line. > 3) For non split output, the first header/navigation panel is removed. Because it is not relevant and confusing. It has links to "Distribution", "Contents", and "Index", all unnecessary, because they are right there in the TOC. > 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. Sorry, I don't know. > 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. Maybe. I know very little about CSS and its effects on the produced HTML manuals. > It seems to me that the manual-html-fix-node-div defun does nothing > for recent Texinfo releases. That's possible and completely reasonable. I explained why we don't want to rely on how recent the Texinfo installation is on the system where the Emacs release is being worked on.