emacs-28 24a6c7c8c0: Update and fix instructions and scripts for updating the Web pages

[Eli Zaretskii]

branch: emacs-28
commit 24a6c7c8c01a607c4cb60f72f762cfa9de3adc48
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Update and fix instructions and scripts for updating the Web pages
    
    * admin/admin.el (manual-html-fix-index-2): Support Texinfo 6.8
    and later by not converting TOC menus into tables.  (Bug#49719)
    * admin/upload-manuals (New directory): Invoke "cvs add" in
    $webdir, to pick up the correct CVSROOT.
    * admin/make-tarball.txt: Update the section about the Emacs Web
    pages.
    
    * etc/refcards/Makefile (pl-refcard.dvi): If mex.fmt cannot be
    found, invoke 'mex' instead of 'tex'.
---
 admin/admin.el         | 141 +++++++++++++++++++++++++------------------------
 admin/make-tarball.txt |  75 ++++++++++++++++++++++----
 admin/upload-manuals   |   5 +-
 etc/refcards/Makefile  |   7 +--
 4 files changed, 145 insertions(+), 83 deletions(-)

diff --git a/admin/admin.el b/admin/admin.el
index aa963be820..a6cb33017e 100644
--- a/admin/admin.el
+++ b/admin/admin.el
@@ -591,76 +591,81 @@ style=\"text-align:left\">")
                 (forward-line 1)
                 (setq done t)))))
     (let (done open-td tag desc)
-      ;; Convert the list that Makeinfo made into a table.
-      (or (search-forward "<ul class=\"menu\">" nil t)
-         ;; FIXME?  The following search seems dangerously lax.
-         (search-forward "<ul>"))
-      (replace-match "<table style=\"float:left\" width=\"100%\">")
-      (forward-line 1)
-      (while (not done)
-       (cond
-        ((or (looking-at "<li>\\(<a.+</a>\\):[ \t]+\\(.*\\)$")
-             (looking-at "<li>\\(<a.+</a>\\)$"))
-         (setq tag (match-string 1))
-         (setq desc (match-string 2))
-         (replace-match "" t t)
-         (when open-td
-           (save-excursion
-             (forward-char -1)
-             (skip-chars-backward " ")
-             (delete-region (point) (line-end-position))
-             (insert "</td>\n  </tr>")))
-         (insert "  <tr>\n    ")
-         (if table-workaround
-             ;; This works around a Firefox bug in the mono file.
-             (insert "<td bgcolor=\"white\">")
-           (insert "<td>"))
-         (insert tag "</td>\n    <td>" (or desc ""))
-         (setq open-td t))
-        ((eq (char-after) ?\n)
-         (delete-char 1)
-         ;; Negate the following `forward-line'.
-         (forward-line -1))
-        ((looking-at "<!-- ")
-         (search-forward "-->"))
-        ((looking-at "<p>[- ]*The Detailed Node Listing[- \n]*")
-         (replace-match "  </td></tr></table>\n
+      ;; Texinfo 6.8 and later doesn't produce <ul class="menu"> lists
+      ;; for the TOC menu, and the "description" part of each menu
+      ;; item is not there anymore.  So for HTML manuals produced by
+      ;; those newer versions of Texinfo we punt and leave the menu in
+      ;; its original form.
+      (when (or (search-forward "<ul class=\"menu\">" nil t)
+               ;; FIXME?  The following search seems dangerously lax.
+               (search-forward "<ul>"))
+        ;; Convert the list that Makeinfo made into a table.
+        (replace-match "<table style=\"float:left\" width=\"100%\">")
+        (forward-line 1)
+        (while (not done)
+         (cond
+          ((or (looking-at "<li>\\(<a.+</a>\\):[ \t]+\\(.*\\)$")
+               (looking-at "<li>\\(<a.+</a>\\)$"))
+           (setq tag (match-string 1))
+           (setq desc (match-string 2))
+           (replace-match "" t t)
+           (when open-td
+             (save-excursion
+               (forward-char -1)
+               (skip-chars-backward " ")
+               (delete-region (point) (line-end-position))
+               (insert "</td>\n  </tr>")))
+           (insert "  <tr>\n    ")
+           (if table-workaround
+               ;; This works around a Firefox bug in the mono file.
+               (insert "<td bgcolor=\"white\">")
+             (insert "<td>"))
+           (insert tag "</td>\n    <td>" (or desc ""))
+           (setq open-td t))
+          ((eq (char-after) ?\n)
+           (delete-char 1)
+           ;; Negate the following `forward-line'.
+           (forward-line -1))
+          ((looking-at "<!-- ")
+           (search-forward "-->"))
+          ((looking-at "<p>[- ]*The Detailed Node Listing[- \n]*")
+           (replace-match "  </td></tr></table>\n
 <h3>Detailed Node Listing</h3>\n\n" t t)
-         (search-forward "<p>")
-         ;; FIXME Fragile!
-         ;; The Emacs and Elisp manual have some text at the
-         ;; start of the detailed menu that is not part of the menu.
-         ;; Other manuals do not.
-         (if (looking-at "Here are some other nodes")
-             (search-forward "<p>"))
-         (goto-char (match-beginning 0))
-         (skip-chars-backward "\n ")
-         (setq open-td nil)
-         (insert "</p>\n\n<table  style=\"float:left\" width=\"100%\">"))
-        ((looking-at "</li></ul>")
-         (replace-match "" t t))
-        ((looking-at "<p>")
-         (replace-match "" t t)
-         (when open-td
-           (insert "  </td></tr>")
-           (setq open-td nil))
-         (insert "  <tr>
+           (search-forward "<p>")
+           ;; FIXME Fragile!
+           ;; The Emacs and Elisp manual have some text at the
+           ;; start of the detailed menu that is not part of the menu.
+           ;; Other manuals do not.
+           (if (looking-at "Here are some other nodes")
+               (search-forward "<p>"))
+           (goto-char (match-beginning 0))
+           (skip-chars-backward "\n ")
+           (setq open-td nil)
+           (insert "</p>\n\n<table  style=\"float:left\" width=\"100%\">"))
+          ((looking-at "</li></ul>")
+           (replace-match "" t t))
+          ((looking-at "<p>")
+           (replace-match "" t t)
+           (when open-td
+             (insert "  </td></tr>")
+             (setq open-td nil))
+           (insert "  <tr>
     <th colspan=\"2\" align=\"left\" style=\"text-align:left\">")
-         (if (re-search-forward "</p>[ \t\n]*<ul class=\"menu\">" nil t)
-             (replace-match "  </th></tr>")))
-        ((looking-at "[ \t]*</ul>[ \t]*$")
-         (replace-match
-          (if open-td
-              "  </td></tr>\n</table>"
-            "</table>") t t)
-         (setq done t))
-        (t
-         (if (eobp)
-             (error "Parse error in %s"
-                    (file-name-nondirectory buffer-file-name)))
-         (unless open-td
-           (setq done t))))
-       (forward-line 1)))))
+           (if (re-search-forward "</p>[ \t\n]*<ul class=\"menu\">" nil t)
+               (replace-match "  </th></tr>")))
+          ((looking-at "[ \t]*</ul>[ \t]*$")
+           (replace-match
+            (if open-td
+                "  </td></tr>\n</table>"
+              "</table>") t t)
+           (setq done t))
+          (t
+           (if (eobp)
+               (error "Parse error in %s"
+                      (file-name-nondirectory buffer-file-name)))
+           (unless open-td
+             (setq done t))))
+         (forward-line 1))))))
 
 
 (defconst make-manuals-dist-output-variables
diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index ec69302dae..17a4d9f807 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -315,17 +315,70 @@ looks like this:
        </div>
     </div>
 
-Regenerate the various manuals in manual/.
-The scripts admin/make-manuals and admin/upload-manuals summarize the process.
-
-If you have Texinfo installed locally, make-manuals might fail if it
-cannot find epsf.tex.  In that case define in the environment
-
-  TEXINPUTS=:/path/to/texinfo-tree/doc
-
-where /path/to/texinfo-tree is the absolute file name of the top-level
-directory where you have the Texinfo source tree.  Then re-run
-make-manuals.
+Next, regenerate the various manuals in HTML, PDF, and PS formats:
+
+  Invoke ./admin/make-manuals from the top-level directory of the
+  Emacs source tree that contains the manuals for which you want to
+  produce HTML docs.  This creates the 'manual' directory and
+  populates it with the necessary files.
+
+  If you have Texinfo installed locally, make-manuals might fail if it
+  cannot find epsf.tex.  In that case define in the environment
+
+    TEXINPUTS=:/path/to/texinfo-tree/doc
+
+  where /path/to/texinfo-tree is the absolute file name of the
+  top-level directory where you have the Texinfo source tree.  Then
+  re-run make-manuals.
+
+  make-manuals can also fail if the HTML manuals produced by Texinfo
+  violate some of the assumptions admin/admin.el makes about the
+  format of the produced HTML.  Debug these problems and resolve them,
+  then re-run make-manuals.  (Each time you run make-manuals, it
+  empties the manuals/ directory and regenerates the files there, but
+  if the files in manuals/ can be used without regeneration, i.e. if
+  the problem you solved doesn't affect the produced HTML, you can
+  invoke make-manuals with the -c switch, which will make the process
+  much faster.)
+
+Now change to the 'manual' directory and invoke upload-manuals:
+
+    ../admin/updload-manuals /path/to/webpages/cvs/checkout
+
+  where /path/to/webpages/cvs/checkout is the place where you have the
+  CVS checkout of the Emacs Web pages, with subdirectories 'manual'
+  and 'refcards'.  This moves the produced manuals to directories in
+  the Web pages CVS checkout tree, and also invokes CVS commands to
+  commit changed files, add new files, and remove stale files that are
+  no longer part of the manuals.
+
+  If upload-manuals fails, resolve the problems and re-invoke it.
+  This requires running make-manuals again, since upload-manuals
+  destructively modifies the 'manual' directory where you invoke it.
+  Also, upload-manuals invokes "cvs commit -f", so if you run it
+  several times, some files will be committed more than once even
+  though they were not changed in-between.  Suck it up.
+
+  All the added and removed files need to be committed, so next fire
+  up Emacs, type "C-x v d" to invoke vc-dir on the Web pages checkout,
+  and use "C-x v v" and other VC commands to commit all the files that
+  upload-manuals didn't automatically commit.  (You can also do that
+  with manual CVS commands, of course, but this is not recommended.)
+
+  Next, make sure that manual/index.html file is consistent with the
+  info/dir file in the branch for which you are producing the manuals,
+  in that it mentions all the manuals.  It could be outdated if
+  manuals were added or removed since the last release.
+
+  For each new manual, a file manual/MANUAL.html (where MANUAL is the
+  name of the manual) should be created from the template in
+  manual/eww.html, after editing the title and the Copyright years,
+  and the links in it changed to point to the appropriate files in the
+  manual/html_node/ and manual/html_mono/ subdirectories.
+
+  In addition, the file refcards/index.html should be audited to make
+  sure it includes the up-to-date list of refcards actually produced
+  and put under that subdirectory.
 
 Browsing <https://web.cvs.savannah.gnu.org/viewvc/?root=emacs> is one
 way to check for any files that still need updating.
diff --git a/admin/upload-manuals b/admin/upload-manuals
index 1fa9865e65..1b7950ede8 100755
--- a/admin/upload-manuals
+++ b/admin/upload-manuals
@@ -334,7 +334,10 @@ for d in html_node/*; do
     [ -e $webdir/manual/$d ] || {
         echo "New directory: $d"
         mkdir $webdir/manual/$d
-        $cvs add $webdir/manual/$d || die "add error"
+        (
+            cd $webdir/manual
+            $cvs add $d || die "add error"
+        )
     }
 
     new=
diff --git a/etc/refcards/Makefile b/etc/refcards/Makefile
index 6f8913c5f0..4c5daa9f44 100644
--- a/etc/refcards/Makefile
+++ b/etc/refcards/Makefile
@@ -233,10 +233,11 @@ pl-refcard.pdf: $(pl_refcard_deps)
        fi
        $(ENVADD) pdftex -output-format=pdf pl-refcard.tex
 pl-refcard.dvi: $(pl_refcard_deps)
-       if ! kpsewhich -format=fmt mex > /dev/null; then \
-         echo "No mex format found."; false; \
+       if kpsewhich -format=fmt mex > /dev/null; then \
+         $(ENVADD) tex pl-refcard.tex; \
+       else \
+         $(ENVADD) mex pl-refcard.tex; \
        fi
-       $(ENVADD) tex pl-refcard.tex
 pl-refcard.ps: pl-refcard.dvi
        dvips -t a4 -o $@ pl-refcard.dvi