From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.devel Subject: Re: Fwd: version vs edition numbers in Emacs manuals Date: Tue, 12 Nov 2019 11:32:00 -0800 Organization: UCLA Computer Science Department Message-ID: References: <87h83brvxg.fsf@wjsullivan.net> <0a820310-d4ce-d9ab-32b0-5d22c00d2122@cs.ucla.edu> <87sgmvozz9.fsf@wjsullivan.net> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------4233259F241294AE6A6C87FD" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="256381"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.0 Cc: Emacs development discussions To: John Sullivan Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Nov 12 20:33:15 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iUbub-0014X4-Lu for ged-emacs-devel@m.gmane.org; Tue, 12 Nov 2019 20:33:13 +0100 Original-Received: from localhost ([::1]:39170 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iUbuZ-0007XI-Hs for ged-emacs-devel@m.gmane.org; Tue, 12 Nov 2019 14:33:11 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47563) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iUbtY-0007Wf-Hv for emacs-devel@gnu.org; Tue, 12 Nov 2019 14:32:10 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iUbtW-0004MY-Gs for emacs-devel@gnu.org; Tue, 12 Nov 2019 14:32:08 -0500 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:60898) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1iUbtW-0004MK-6h for emacs-devel@gnu.org; Tue, 12 Nov 2019 14:32:06 -0500 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id EE00B16056A; Tue, 12 Nov 2019 11:32:04 -0800 (PST) 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 zE4mpbUcE1r1; Tue, 12 Nov 2019 11:32:03 -0800 (PST) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 802D916056C; Tue, 12 Nov 2019 11:32:03 -0800 (PST) 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 wbNi_ic-1gkR; Tue, 12 Nov 2019 11:32:03 -0800 (PST) Original-Received: from Penguin.CS.UCLA.EDU (Penguin.CS.UCLA.EDU [131.179.64.200]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 6073616056A; Tue, 12 Nov 2019 11:32:03 -0800 (PST) In-Reply-To: <87sgmvozz9.fsf@wjsullivan.net> 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.23 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:242114 Archived-At: This is a multi-part message in MIME format. --------------4233259F241294AE6A6C87FD Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit On 11/10/19 7:26 PM, John Sullivan wrote: > maybe the solution could be to have two online > versions, one that corresponds to print and is only updated when a new > print version is made, and the other is the one that the developers with > each release or whenever they feel is appropriate? And that latter > version would not have any edition number. We wouldn't have any problem > with the primary canonical manual link > (https://www.gnu.org/software/emacs/manual/emacs.html) being used for > the online-only version. What do you think? Sounds good. This can be done by Texinfo flags, which are set for the printed version and generate an edition number, and are clear for the canonical online/info manual and do not generate an edition number. I installed the attached patch into the GNU Emacs master to do this. We can tweak it as needed later. --------------4233259F241294AE6A6C87FD Content-Type: text/x-patch; charset=UTF-8; name="0001-Conditionally-omit-edition-numbers-dates-in-doc.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename*0="0001-Conditionally-omit-edition-numbers-dates-in-doc.patch" >From 787bb984e964dac56ac773864581286d46f1d5e1 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Tue, 12 Nov 2019 11:29:00 -0800 Subject: [PATCH] Conditionally omit edition numbers, dates in doc This redoes the 2019-11-02T00:24:02!eggert@cs.ucla.edu patch, updated after consultation with John Sullivan. Omit printed edition numbers in online manuals while keeping them in printed manuals. In online manuals the edition numbers seem to cause more confusion than they cure; e.g., https://shop.fsf.org/books/gnu-emacs-manual-18th-edition-v-261 currently advertises "18th edition" even as it points to https://www.gnu.org/software/emacs/manual/pdf/emacs.pdf which says "Seventeenth Edition". It is simpler and less confusing to stick to one version number like "27.0" in online manuals. For printed manuals people can run, e.g., "texi2any -D 'EDITION Nineteenth'" when generating the 19th printed edition of the Emacs manual. * doc/emacs/emacs.texi (EDITION): * doc/lispintro/emacs-lisp-intro.texi (edition-number, update-date): * doc/lispref/elisp.texi (VERSION, DATE): Remove definitions. Instead, let the person printing the book specify these values, with the default being the online version which does not have printed edition numbers. * doc/lispintro/emacs-lisp-intro.texi (titlepage-edition-number): New flag, for the edition number as it appears on the title page. --- doc/emacs/emacs.texi | 32 ++++++++++++++--------------- doc/lispintro/emacs-lisp-intro.texi | 24 ++++++++++++++-------- doc/lispref/elisp.texi | 20 ++++++++++-------- 3 files changed, 41 insertions(+), 35 deletions(-) diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index a7967ecaee..d23e682cc8 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -3,28 +3,21 @@ @setfilename ../../info/emacs.info @settitle GNU Emacs Manual @include docstyle.texi - -@c The edition number appears in more than one place in this file -@c I don't really know what it means... -@c For example, it has said "Sixteenth" since sometime in the Emacs 22 -@c series, all through 23, and into 24. So it is not very useful IMO, -@c and offers nothing that EMACSVER does not. I guess it relates -@c mainly to the published book sold by the FSF. Hence no longer -@c bother including it except iftex. Really, I think it should not be -@c here at all (since anyone can make a pdf version), but should just -@c be something added by the FSF during the publishing process. -@c Also, the lispref uses a float (3.0), whereas this uses an ordinal, -@c so the format is not even consistent. -@set EDITION Seventeenth @include emacsver.texi +@c When printing, define EDITION to be the printed edition number, in +@c the preferred style for ordinal edition numbers. E.g., run the +@c shell command "texi2any -D 'EDITION Nineteenth'" for the 19th +@c printed edition where the edition number is spelled out in English. +@c This relates mainly to the published book sold by the FSF. + @copying -@iftex +@ifset EDITION This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* -@end iftex -@ifnottex +@end ifset +@ifclear EDITION This is the @cite{GNU Emacs Manual}, -@end ifnottex +@end ifclear updated for Emacs version @value{EMACSVER}. Copyright @copyright{} 1985--1987, 1993--2019 Free Software Foundation, Inc. @@ -82,7 +75,12 @@ @sp 6 @center @titlefont{GNU Emacs Manual} @sp 4 +@ifset EDITION @center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}. +@end ifset +@ifclear EDITION +@center Updated for Emacs Version @value{EMACSVER} +@end ifclear @sp 5 @center Richard Stallman et al. @page diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 489ba8d6ef..710e64f457 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -63,10 +63,6 @@ \global\hbadness=6666 % don't worry about not-too-underfull boxes @end tex -@c These refer to the printed book sold by the FSF. -@set edition-number 3.10 -@set update-date 28 October 2009 - @c For next or subsequent edition: @c create function using with-output-to-temp-buffer @c create a major mode, with keymaps @@ -102,16 +98,24 @@ * Emacs Lisp Intro: (eintr). A simple introduction to Emacs Lisp programming. @end direntry +@c When printing, define edition-number to be the printed edition +@c number, titlepage-edition-number to be the spelled out edition +@c number suitable for the title page, and update-date to be the date, +@c in the preferred style for these. E.g., run the shell command: +@c texi2any -D 'edition-number 3.11' \ +@c -D 'titlepage-edition-number Revised Third Edtion' \ +@c -D 'update-date 31 March 2020' +@c This relates mainly to the published book sold by the FSF. + @copying This is @cite{An Introduction to Programming in Emacs Lisp}, for people who are not programmers. @sp 1 -@iftex +@ifset edition-number Edition @value{edition-number}, @value{update-date} -@end iftex -@ifnottex +@end ifset +@sp 1 Distributed with Emacs version @value{EMACSVER}. -@end ifnottex @sp 1 Copyright @copyright{} 1990--1995, 1997, 2001--2019 Free Software Foundation, Inc. @@ -173,7 +177,9 @@ @sp 2 @center @titlefont{Programming in Emacs Lisp} @sp 2 -@center Revised Third Edition +@ifset titlepage-edition-number +@center @value{titlepage-edition-number} +@end ifset @sp 4 @center by Robert J. Chassell diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index d667c51d78..72ad8a751d 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -52,12 +52,7 @@ @end ifset @end tex - -@c Version of the manual and of Emacs. -@c (See comments for EDITION in emacs.texi) -@set VERSION 3.1 @include emacsver.texi -@set DATE October 2014 @c in general, keep the following line commented out, unless doing a @c copy of this manual that will be published. The manual should go @@ -90,13 +85,18 @@ @c We use the "type index" to index new functions and variables. @c @syncodeindex tp fn +@c When printing, define VERSION to be the printed edition number and +@c DATE to be the printed edition's date. E.g., run the shell command +@c "texi2any -D 'VERSION 3.2' -D 'DATE 31 March 2020'". This relates +@c mainly to the published book sold by the FSF. + @copying -@iftex +@ifset VERSION This is edition @value{VERSION} of the @cite{GNU Emacs Lisp Reference Manual},@* -@end iftex -@ifnottex +@end ifset +@ifclear VERSION This is the @cite{GNU Emacs Lisp Reference Manual} -@end ifnottex +@end ifclear corresponding to Emacs version @value{EMACSVER}. Copyright @copyright{} 1990--1996, 1998--2019 Free Software Foundation, Inc. @@ -127,7 +127,9 @@ @subtitle @value{voltitle} @end ifset @subtitle For Emacs Version @value{EMACSVER} +@ifset VERSION @subtitle Revision @value{VERSION}, @value{DATE} +@end ifset @author by Bil Lewis, Dan LaLiberte, Richard Stallman, @author the GNU Manual Group, et al. -- 2.23.0 --------------4233259F241294AE6A6C87FD--