From 24a6c7c8c01a607c4cb60f72f762cfa9de3adc48 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 8 Apr 2022 21:11:16 +0300
Subject: [PATCH] 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 aa963be8208..a6cb33017ef 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 ec69302dae8..17a4d9f807b 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 1fa9865e657..1b7950ede80 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 6f8913c5f01..4c5daa9f44c 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
 
-- 
2.39.2