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