From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.devel Subject: Re: procedure for creating online Emacs manual? Date: Fri, 30 Mar 2018 16:23:37 -0700 Organization: UCLA Computer Science Department Message-ID: <112b96b9-ec4d-d5b2-b813-999d7004becc@cs.ucla.edu> References: <132c3a65-ac0a-49de-d9cd-1812aef336ae@cs.ucla.edu> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------922010E18A18931FC330C94B" X-Trace: blaine.gmane.org 1522452115 20076 195.159.176.226 (30 Mar 2018 23:21:55 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 30 Mar 2018 23:21:55 +0000 (UTC) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.6.0 Cc: Emacs development discussions To: Glenn Morris Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Mar 31 01:21:50 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1f23L9-00053v-VC for ged-emacs-devel@m.gmane.org; Sat, 31 Mar 2018 01:21:48 +0200 Original-Received: from localhost ([::1]:51860 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1f23NC-0001GK-1M for ged-emacs-devel@m.gmane.org; Fri, 30 Mar 2018 19:23:54 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54324) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1f23N2-0001Ce-7X for emacs-devel@gnu.org; Fri, 30 Mar 2018 19:23:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1f23My-0000HA-RU for emacs-devel@gnu.org; Fri, 30 Mar 2018 19:23:44 -0400 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:58660) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1f23My-0000Gh-HS; Fri, 30 Mar 2018 19:23:40 -0400 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 5C13516170F; Fri, 30 Mar 2018 16:23:39 -0700 (PDT) Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id G71E3W47Xhmv; Fri, 30 Mar 2018 16:23:37 -0700 (PDT) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id AF744161711; Fri, 30 Mar 2018 16:23:37 -0700 (PDT) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id NziVNe0P7R58; Fri, 30 Mar 2018 16:23:37 -0700 (PDT) Original-Received: from Penguin.CS.UCLA.EDU (Penguin.CS.UCLA.EDU [131.179.64.200]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 8D13616170F; Fri, 30 Mar 2018 16:23:37 -0700 (PDT) In-Reply-To: Content-Language: en-US X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 131.179.128.68 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:224191 Archived-At: This is a multi-part message in MIME format. --------------922010E18A18931FC330C94B Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable 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=20 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=20 problems that I found (e.g., we don't put refcards up on the web any=20 more) by installing the attached into 'master', and left in a FIXME for=20 the stuff I couldn't figure out. Plus, I altered the instructions so=20 that the tarballs are reproducible. (It wouldn't hurt to go reproducible=20 even for Emacs 26 but I was leery of changing distribution instructions=20 in the emacs-26 branch.) I couldn't build the refcards on Fedora 27, due to some problem with=20 larm1000 (see below). Maybe we should stop maintaining the refcards=20 since we no longer put them on the web? I doubt whether they're used=20 much any more and the whole idea of a refcard is so 1980s anyway. Stefan=20 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)=20 (preloaded format=3Dpdflatex) =C2=A0restricted \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=20 abbreviation=C2=A0 for larm1000. /usr/share/texlive/texmf-dist/web2c/mktexnam: Need to update ? mktextfm: Running mf-nowin -progname=3Dmf \mode:=3Dljfour; mag:=3D1;=20 nonstopmode; input larm1000 This is METAFONT, Version 2.7182818 (TeX Live 2016) (preloaded base=3Dmf) kpathsea: Running mktexmf larm1000 ! I can't find file `larm1000'. <*> ...ljfour; mag:=3D1; nonstopmode; input larm1000 ... Transcript written on ru-refcard.log. make: *** [Makefile:262: ru-refcard.pdf] Error 1 --------------922010E18A18931FC330C94B Content-Type: text/x-patch; name="0001-Improve-doc-for-web-pages-reproducible-tarballs.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename*0="0001-Improve-doc-for-web-pages-reproducible-tarballs.patch" >From ae0187535bec4ff114e994c9da83be07b1f7ff4f Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 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 --------------922010E18A18931FC330C94B--