diff options
author | Eli Zaretskii <eliz@gnu.org> | 2022-04-08 21:11:16 +0300 |
---|---|---|
committer | Eli Zaretskii <eliz@gnu.org> | 2022-04-08 21:11:16 +0300 |
commit | 24a6c7c8c01a607c4cb60f72f762cfa9de3adc48 (patch) | |
tree | 4e54ee39f87629f85fa3b66bc061c1f01fee1295 /admin | |
parent | 886339747b8d34fc09fd69a143cf548daf92dce6 (diff) | |
download | emacs-24a6c7c8c01a607c4cb60f72f762cfa9de3adc48.tar.gz |
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'.
Diffstat (limited to 'admin')
-rw-r--r-- | admin/admin.el | 141 | ||||
-rw-r--r-- | admin/make-tarball.txt | 75 | ||||
-rwxr-xr-x | admin/upload-manuals | 5 |
3 files changed, 141 insertions, 80 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= |