version vs edition numbers in Emacs manuals

version vs edition numbers in Emacs manuals

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 638 bytes --]

I noticed Glenn's comment at the start of doc/emacs/emacs.texi that 
EDITION (which was "Seventeenth") offers nothing that EMACSVER 
("27.0.50") does not. I'd go further and say that it's a net minus, 
since it's confusing to have competing version numbers for the same thing.

Although separating software version numbers from book edition numbers 
made sense in the old days when most users had only low-resolution 
displays and/or printers, nowadays the practice appears to be more 
trouble than it's worth. So I installed the attached patch, to switch 
the main Emacs manuals to simple version numbers like "27.0". Comments 
welcome.

[-- Attachment #2: 0001-Omit-edition-numbers-and-dates-in-manuals.patch --]
[-- Type: text/x-patch, Size: 4946 bytes --]

From d12c5c21c5aa143965e41e7cd6f8f4a62818e0b5 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 1 Nov 2019 17:24:02 -0700
Subject: [PATCH] Omit edition numbers and dates in manuals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

These 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 "26.3".  If we
need a separate edition number for each printed manual for
some reason (marketing?) we can put “@ifset printed-edition”
around anything specific to the printed editions.
(as opposed to online PDF copies).
* doc/emacs/emacs.texi (EDITION):
* doc/lispintro/emacs-lisp-intro.texi (edition-number, update-date):
* doc/lispref/elisp.texi (VERSION, DATE):
Remove, and remove uses.
---
 doc/emacs/emacs.texi                | 20 +-------------------
 doc/lispintro/emacs-lisp-intro.texi |  7 -------
 doc/lispref/elisp.texi              | 13 +------------
 3 files changed, 2 insertions(+), 38 deletions(-)

diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index a7967ecaee..678ccb9ba5 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -3,28 +3,10 @@
 @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
 
 @copying
-@iftex
-This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@*
-@end iftex
-@ifnottex
 This is the @cite{GNU Emacs Manual},
-@end ifnottex
 updated for Emacs version @value{EMACSVER}.
 
 Copyright @copyright{} 1985--1987, 1993--2019 Free Software Foundation, Inc.
@@ -82,7 +64,7 @@
 @sp 6
 @center @titlefont{GNU Emacs Manual}
 @sp 4
-@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}.
+@center Updated for Emacs Version @value{EMACSVER}
 @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..9ad4cf102e 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
@@ -106,9 +102,6 @@
 This is @cite{An Introduction to Programming in Emacs Lisp}, for
 people who are not programmers.
 @sp 1
-@iftex
-Edition @value{edition-number}, @value{update-date}
-@end iftex
 @ifnottex
 Distributed with Emacs version @value{EMACSVER}.
 @end ifnottex
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index d667c51d78..652175c395 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
@@ -91,12 +86,7 @@
 @c @syncodeindex tp fn
 
 @copying
-@iftex
-This is edition @value{VERSION} of the @cite{GNU Emacs Lisp Reference Manual},@*
-@end iftex
-@ifnottex
-This is the @cite{GNU Emacs Lisp Reference Manual}
-@end ifnottex
+This is the @cite{GNU Emacs Lisp Reference Manual},
 corresponding to Emacs version @value{EMACSVER}.
 
 Copyright @copyright{} 1990--1996, 1998--2019 Free Software Foundation, Inc.
@@ -127,7 +117,6 @@
 @subtitle @value{voltitle}
 @end ifset
 @subtitle For Emacs Version @value{EMACSVER}
-@subtitle Revision @value{VERSION}, @value{DATE}
 
 @author by Bil Lewis, Dan LaLiberte, Richard Stallman,
 @author the GNU Manual Group, et al.
-- 
2.23.0

Re: version vs edition numbers in Emacs manuals

[Jean-Christophe Helary]

> On Nov 2, 2019, at 9:35, Paul Eggert <eggert@cs.ucla.edu> wrote:
> 
> I noticed Glenn's comment at the start of doc/emacs/emacs.texi that EDITION (which was "Seventeenth") offers nothing that EMACSVER ("27.0.50") does not. I'd go further and say that it's a net minus, since it's confusing to have competing version numbers for the same thing.
> 
> Although separating software version numbers from book edition numbers made sense in the old days when most users had only low-resolution displays and/or printers, nowadays the practice appears to be more trouble than it's worth. So I installed the attached patch, to switch the main Emacs manuals to simple version numbers like "27.0". Comments welcome.

This makes a lot of sense.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: version vs edition numbers in Emacs manuals

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Fri, 1 Nov 2019 17:35:53 -0700
> 
> I noticed Glenn's comment at the start of doc/emacs/emacs.texi that 
> EDITION (which was "Seventeenth") offers nothing that EMACSVER 
> ("27.0.50") does not. I'd go further and say that it's a net minus, 
> since it's confusing to have competing version numbers for the same thing.
> 
> Although separating software version numbers from book edition numbers 
> made sense in the old days when most users had only low-resolution 
> displays and/or printers, nowadays the practice appears to be more 
> trouble than it's worth. So I installed the attached patch, to switch 
> the main Emacs manuals to simple version numbers like "27.0". Comments 
> welcome.

I've reverted this.

We cannot unilaterally remove this stuff, we must talk to the FSF
publishing people and have their agreement first, because they will
need to know it is now their responsibility to keep track of the
edition number.  The edition appears on the book's cover: e.g., my
copy of the latest Emacs Manual says "Eighteenth edition for GNU Emacs
version 26.1".

Richard, who we should talk to about changing this?

Re: version vs edition numbers in Emacs manuals

[Paul Eggert]

On 11/2/19 12:59 AM, Eli Zaretskii wrote:

> We cannot unilaterally remove this stuff, we must talk to the FSF
> publishing people and have their agreement first

OK, I'll write info@fsf.org about this, and CC: you and RMS.

Re: version vs edition numbers in Emacs manuals

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Sat, 2 Nov 2019 10:23:28 -0700
> 
> On 11/2/19 12:59 AM, Eli Zaretskii wrote:
> 
> > We cannot unilaterally remove this stuff, we must talk to the FSF
> > publishing people and have their agreement first
> 
> OK, I'll write info@fsf.org about this, and CC: you and RMS.

Thanks.

Re: version vs edition numbers in Emacs manuals

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Richard, who we should talk to about changing this?

Please talk with johns@fsf.org.  He would know who you need to work
with.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: Fwd: version vs edition numbers in Emacs manuals

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 856 bytes --]

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.

[-- Attachment #2: 0001-Conditionally-omit-edition-numbers-dates-in-doc.patch --]
[-- Type: text/x-patch, Size: 7014 bytes --]

From 787bb984e964dac56ac773864581286d46f1d5e1 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
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

Re: Fwd: version vs edition numbers in Emacs manuals

[Eli Zaretskii]

> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Tue, 12 Nov 2019 11:32:00 -0800
> Cc: Emacs development discussions <emacs-devel@gnu.org>
> 
> 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?

I didn't see John's response, not sure why.  Can someone forward it to
me?

> 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.

Sigh...  John said "WDYT", which assumed discussion, not an immediate
commit...

In any case, I'm not sure John was suggesting that someone will have
to manually type a texi2any command.  I think at the very least we
should have a separate target in the Makefile, and we should maintain
the last printed edition in some separate file, because no one will
remember that otherwise.  Please note that such a command will have
to be run to generate the on-line manual we have on the Web site.

The fact that some manuals use EDITION while others use VERSION also
doesn't make this very clean, IMO.

I'd also like to hear John's opinion about this solution.

Thanks.

Re: Fwd: version vs edition numbers in Emacs manuals

[Paul Eggert]

On 11/14/19 4:18 AM, Eli Zaretskii wrote:

> I didn't see John's response, not sure why.  Can someone forward it to
> me?

Sure, here it is:

> Paul Eggert <eggert@cs.ucla.edu> writes:
> 
>> On 11/10/19 6:25 PM, John Sullivan wrote:
>>> Can you fill me in more on how they are messed up? Thanks for your help.
>>
>> For example, the FSF bookstore web page
>> <https://shop.fsf.org/books/gnu-emacs-manual-18th-edition-v-261>
>> currently advertises the GNU Emacs 26.1 manual as the "18th edition,
>> v. 26.1" and the spine of the printed manual says "Eighteenth edition
>> for GNU Emacs version 26.1".
>>
>> In contrast, the online manual
>> <https://www.gnu.org/software/emacs/manual/emacs.html> says on its
>> title page "Seventeenth Edition, Updated for Emacs Version 26.3". That
>> is, the online manual says it is for an *earlier* manual edition, but
>> for a *later* Emacs version, than the printed manual.
>>
>> The edition number is incorrect and misleading, since the online
>> manual is in fact more up-to-date than the printed manual. So I'd like
>> to remove the edition number from the online manual. That way, the
>> online manual won't have incorrect information, and the people
>> printing the book can use whatever edition number they like without
>> having to coordinate with the Emacs developers.
>>
> 
> That makes sense to me. The Emacs developers do prepare the print
> version for us. We might like to keep an online version that matches the
> print version. So 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?


Getting back to Eli's email:

> we should have a separate target in the Makefile, and we should maintain
> the last printed edition in some separate file, because no one will
> remember that otherwise.

A separate Makefile target would be fine, but the separate file should 
be something that the FSF Press maintains. Having the edition numbers be 
in a file that Emacs developers maintain would continue to cause 
glitches like the ones noted above. The FSF Press is downstream from 
developers, they generate edition numbers at their convenience not 
developers', and they can and should be the ones who keep track of the 
edition numbers that they maintain.

> The fact that some manuals use EDITION while others use VERSION also
> doesn't make this very clean, IMO.

Yes, that area could easily be made more systematic. For example, we 
could systematically use just EDITION and DATE for all the FSF 
Press-maintained info.

Re: Fwd: version vs edition numbers in Emacs manuals

[Eli Zaretskii]

> Cc: johns@fsf.org, emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Thu, 14 Nov 2019 11:42:09 -0800
> 
> On 11/14/19 4:18 AM, Eli Zaretskii wrote:
> 
> > I didn't see John's response, not sure why.  Can someone forward it to
> > me?
> 
> Sure, here it is:

Thanks.

> > we should have a separate target in the Makefile, and we should maintain
> > the last printed edition in some separate file, because no one will
> > remember that otherwise.
> 
> A separate Makefile target would be fine, but the separate file should 
> be something that the FSF Press maintains.

How will that work in practice?  Isn't the printed version built by
using our Makefile's and our build infrastructure?  Then how can this
file be kept separate, and how will it be maintained to be available
when needed?

> The FSF Press is downstream from developers, they generate edition
> numbers at their convenience not developers', and they can and
> should be the ones who keep track of the edition numbers that they
> maintain.

Fine with me if that works.  But we must somehow make sure this
knowledge doesn't get lost.  Whoever prepares a manual for printing
should be aware that they need to do something that isn't already done
in the Emacs sources.  Maybe a simple README in those directories
could be the solution, e.g. if its name was indicative of its being a
necessary read when a manual is being prepared for printing.

Thoughts.

> > The fact that some manuals use EDITION while others use VERSION also
> > doesn't make this very clean, IMO.
> 
> Yes, that area could easily be made more systematic. For example, we 
> could systematically use just EDITION and DATE for all the FSF 
> Press-maintained info.

I'd like that, yes.