From: Paul Eggert <eggert@cs.ucla.edu>
To: Glenn Morris <rgm@gnu.org>
Cc: Emacs development discussions <emacs-devel@gnu.org>
Subject: Re: procedure for creating online Emacs manual?
Date: Fri, 30 Mar 2018 16:23:37 -0700 [thread overview]
Message-ID: <112b96b9-ec4d-d5b2-b813-999d7004becc@cs.ucla.edu> (raw)
In-Reply-To: <i9d0zls6ko.fsf@fencepost.gnu.org>
[-- Attachment #1: Type: text/plain, Size: 2457 bytes --]
On 03/30/2018 12:32 PM, Glenn Morris wrote:
> I don't think there were any (?) changes to the manual between 25.2
> and the latest release (ie 25.3).
OK. It is confusing that the latest release is 25.3 but the online
manuals say 25.2, but we can live with it if it's too much trouble to fix.
>> What's the procedure for generating the online manual from the
>> released version?
> It is summarized at the end of admin/make-tarball.txt.
> Basically it uses M-x make-manuals from admin/admin.el.
Thanks. I tried to follow that procedure but came up dry. I fixed the
problems that I found (e.g., we don't put refcards up on the web any
more) by installing the attached into 'master', and left in a FIXME for
the stuff I couldn't figure out. Plus, I altered the instructions so
that the tarballs are reproducible. (It wouldn't hurt to go reproducible
even for Emacs 26 but I was leery of changing distribution instructions
in the emacs-26 branch.)
I couldn't build the refcards on Fedora 27, due to some problem with
larm1000 (see below). Maybe we should stop maintaining the refcards
since we no longer put them on the web? I doubt whether they're used
much any more and the whole idea of a refcard is so 1980s anyway. Stefan
hinted at doing that here:
https://lists.gnu.org/archive/html/emacs-devel/2016-11/msg00715.html
Here's the failed refcard build on Fedora:
$ make -C etc/refcards pdf ps
...
pdflatex ru-refcard.tex
This is pdfTeX, Version 3.14159265-2.6-1.40.17 (TeX Live 2016)
(preloaded format=pdflatex)
restricted \write18 enabled.
entering extended mode
(./ru-refcard.tex
LaTeX2e <2016/03/31>
Babel <3.9r> and hyphenation patterns for 22 language(s) loaded.
(/usr/share/texlive/texmf-dist/tex/latex/base/article.cls
Document Class: article 2014/09/29 v1.4h Standard LaTeX document class
...
kpathsea: Running mktextfm larm1000
/usr/share/texlive/texmf-dist/web2c/mktexnam: Could not map source
abbreviation for larm1000.
/usr/share/texlive/texmf-dist/web2c/mktexnam: Need to update ?
mktextfm: Running mf-nowin -progname=mf \mode:=ljfour; mag:=1;
nonstopmode; input larm1000
This is METAFONT, Version 2.7182818 (TeX Live 2016) (preloaded base=mf)
kpathsea: Running mktexmf larm1000
! I can't find file `larm1000'.
<*> ...ljfour; mag:=1; nonstopmode; input larm1000
...
Transcript written on ru-refcard.log.
make: *** [Makefile:262: ru-refcard.pdf] Error 1
[-- Attachment #2: 0001-Improve-doc-for-web-pages-reproducible-tarballs.patch --]
[-- Type: text/x-patch, Size: 4090 bytes --]
From ae0187535bec4ff114e994c9da83be07b1f7ff4f Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 30 Mar 2018 16:11:45 -0700
Subject: [PATCH] Improve doc for web pages; reproducible tarballs
* admin/make-tarball.txt: Make the tarballs more reproducible.
Fix instructions for web pages as best I can (they are still
incomplete).
* make-dist (default_gzip): Add --no-name for gzip.
(taropt): Add options to make the build more reproducible.
---
admin/make-tarball.txt | 34 +++++++++++++++++++++++++---------
make-dist | 8 ++++----
2 files changed, 29 insertions(+), 13 deletions(-)
diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index ac6d15d6ce..19edeb79e6 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -123,7 +123,7 @@ General steps (for each step, check for possible errors):
9. Decide what compression schemes to offer.
For a release, at least gz and xz:
- gzip --best -c emacs-NEW.tar > emacs-NEW.tar.gz
+ gzip --best --no-name -c emacs-NEW.tar > emacs-NEW.tar.gz
xz -c emacs-NEW.tar > emacs-NEW.tar.xz
For pretests, just xz is probably fine (saves bandwidth).
@@ -197,7 +197,6 @@ The pages to update are:
emacs.html (for a new major release, a more thorough update is needed)
history.html
-add the new NEWS file as news/NEWS.xx.y
For every new release, a banner is displayed on top of the emacs.html
page. Uncomment and the release banner in emacs.html. Keep it on the
@@ -210,15 +209,32 @@ manual/html_node directory, delete any old manual pages that are no
longer present.
Tar up the generated html_node/emacs/ and elisp/ directories and update
-the files manual/elisp.html_node.tar.gz and emacs.html_node.tar.gz.
+the files manual/elisp.html_node.tar.gz and emacs.html_node.tar.gz.
+Use GNU Tar as follows so that the tarballs are reproducible:
-Use M-x make-manuals-dist from admin/admin.el to update the
-manual/texi/ tarfiles.
-
-Add compressed copies of the main info pages from the tarfile to manual/info/.
+cd manual
+tar='tar --numeric-owner --owner=0 --group=0 --mode=go+u,go-w --sort=name'
+gzip='gzip --best --no-name'
+$tar -cf - html_node/emacs | $gzip >emacs.html_node.tar.gz
+$tar -cf - html_node/elisp | $gzip >elisp.html_node.tar.gz
-Update the refcards/pdf/ and ps/ directories, and also
-refcards/emacs-refcards.tar.gz (use make -C etc/refcards pdf ps dist).
+Use M-x make-manuals-dist from admin/admin.el to update the
+manual/*.tar files.
+
+Add compressed copies of the main info pages from the tarfile to manual/info/
+as follows:
+
+cd manual
+mkdir info
+gzip --best --no-name <../info/eintr.info >info/eintr.info.gz
+gzip --best --no-name <../info/elisp.info >info/elisp.info.gz
+gzip --best --no-name <../info/emacs.info >info/emacs.info.gz
+
+FIXME: The above instructions are not quite complete, as they do not
+specify how to copy the generated files in the 'manual' directory to
+the corresponding web files. Also, they are missing some files, e.g.,
+they generate manual/html_mono/ada-mode.html but do not generate the
+top-level ada-mode.html file for the one-node-per-page version.
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/make-dist b/make-dist
index 26247b37bc..48c7fb4fb7 100755
--- a/make-dist
+++ b/make-dist
@@ -639,14 +639,14 @@ files=
case "${default_gzip}" in
bzip2) gzip_extension=.bz2 ;;
xz) gzip_extension=.xz ;;
- gzip) gzip_extension=.gz ; default_gzip="gzip --best";;
+ gzip) gzip_extension=.gz ; default_gzip="gzip --best --no-name";;
*) gzip_extension= ;;
esac
echo "Creating tar file"
- taropt=
- [ "$verbose" = "yes" ] && taropt=v
+ taropt='--numeric-owner --owner=0 --group=0 --mode=go+u,go-w --sort=name'
+ [ "$verbose" = "yes" ] && taropt="$taropt --verbose"
- (cd ${tempparent} ; tar c${taropt}f - ${emacsname} ) \
+ (cd ${tempparent} ; tar $taropt -cf - ${emacsname} ) \
| ${default_gzip} \
> ${emacsname}.tar${gzip_extension}
fi
--
2.14.3
next prev parent reply other threads:[~2018-03-30 23:23 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-03-30 19:07 procedure for creating online Emacs manual? Paul Eggert
2018-03-30 19:32 ` Glenn Morris
2018-03-30 23:23 ` Paul Eggert [this message]
2018-03-31 0:58 ` Glenn Morris
2018-04-01 21:20 ` Paul Eggert
2018-04-02 18:26 ` Glenn Morris
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=112b96b9-ec4d-d5b2-b813-999d7004becc@cs.ucla.edu \
--to=eggert@cs.ucla.edu \
--cc=emacs-devel@gnu.org \
--cc=rgm@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.