Please post older versions of GNU Emacs manuals on the web

Please post older versions of GNU Emacs manuals on the web

[Drew Adams]

If you have a version of GNU Emacs older than 24.4 then you are
lucky to still have `defadvice' documented in the Elisp manual.

(This useful doc _never_ should have been removed from the manual.
But that is not the point of this post.)

Suppose you are using Emacs 24.3 (or Emacs 23 or...).  You visit
the Elisp manual and you use `i defadvice' to visit the advice doc.

You want to visit the same manual section on line (HTTP).  Perhaps
you want to bookmark it for use when you do not have Emacs available.
Or maybe you want to send the URL to someone or post it in online
Emacs help.  Or maybe you want to print some of the HTML pages.

Here's the rub.  Only the manuals for the latest Emacs release
are available on line.  And because Emacs (unwisely) removed the
doc for `defadvice', you are out of luck.  There is no online doc
for you.

Can GNU Emacs not provide its users with the doc for more
than one release on line?  How hard and how costly is that?

In many cases providing this service is maybe not so important,
because Emacs tends to add more than it subtracts (mostly
monotonic).  But in a case such as the wholesale decapitation
of `defadvice' doc you are really out of luck on the web.

Wrt `defadvice', the big concession that was made was to
keep the doc in the Lisp source code, as comments.  That's
piss-poor IMHO, but at least it shows some contrition for
the sin of removing useful doc from users.

How about posting multiple versions of the Emacs doc on line?

---

FWIW, I use a simple command, bound to `G' in Info, to
visit the current Info node on the web.  Sounds silly, but
I use it several times a day, to provide links in answers
I give to online Emacs questions.  (Of course, I also tell
users the preferred method of accessing the doc, `C-h i'.)

(defun Info-goto-node-web (node &optional flip-new-win)
  "Use `browse-url' to go to Info node NODE using a Web browser.
With a prefix arg, reverse the effect of option
option`browse-url-new-window-flag'.

NODE is the name of a node in the GNU Emacs or Elisp manual.
Alternatively, NODE can have the form (MANUAL)NODE, where MANUAL is
\"emacs\" or \"elisp\" and NODE is the name of the node in that
manual.  Empty NODE in (MANUAL) defaults to the `Top' node."
  (interactive
    (list (Info-read-node-name "Go to node: " Info-current-node)
          current-prefix-arg))
  (require 'browse-url)
  (unless Info-current-file
    (error "This command must be invoked from Info"))
  (browse-url (Info-url-for-node node)
              (list (if flip-new-win
                        (not browse-url-new-window-flag)
                      browse-url-new-window-flag))))

Re: Please post older versions of GNU Emacs manuals on the web

[Eli Zaretskii]

> Date: Sat, 2 Jan 2016 08:46:17 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> Suppose you are using Emacs 24.3 (or Emacs 23 or...).  You visit
> the Elisp manual and you use `i defadvice' to visit the advice doc.
> 
> You want to visit the same manual section on line (HTTP).  Perhaps
> you want to bookmark it for use when you do not have Emacs available.
> Or maybe you want to send the URL to someone or post it in online
> Emacs help.  Or maybe you want to print some of the HTML pages.
> 
> Here's the rub.  Only the manuals for the latest Emacs release
> are available on line.  And because Emacs (unwisely) removed the
> doc for `defadvice', you are out of luck.  There is no online doc
> for you.

Nothing can ever be "removed" from the Internet.  You can find your
v24.3 version of ELisp manual, and in it the chapter about advising,
here:

  https://web.archive.org/web/20121224105042/http://www.gnu.org/software/emacs/manual/html_node/elisp/Advising-Functions.html#Advising-Functions

(Google for "wayback machine" if you want to find old versions of some
URLs, including URLs that no longer exist.)

Re: Please post older versions of GNU Emacs manuals on the web

[John Wiegley]

>>>>> Drew Adams <drew.adams@oracle.com> writes:

> If you have a version of GNU Emacs older than 24.4 then you are lucky to
> still have `defadvice' documented in the Elisp manual.

Maybe we should have a "deprecated features" manual, where text gets moved
after it is removed from the Elisp manual? Even though 25.1 may not use
defadvice, it still allows such code to be written, which means you'll
probably run across such code in the future and would like to read
documentation on how it works.

I can understand taking it out of the manual, but it would be nice to have
another manual for "features you may well run into in the wild, though you
shouldn't write new code this way". I'm not proposing maintaining such a
manual actively, but just copying deprecated sections like the "defadvice"
content directly into it instead of deletion.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

RE: Please post older versions of GNU Emacs manuals on the web

[Drew Adams]

> > If you have a version of GNU Emacs older than 24.4 then you are lucky to
> > still have `defadvice' documented in the Elisp manual.
> 
> Maybe we should have a "deprecated features" manual, where text gets moved
> after it is removed from the Elisp manual? Even though 25.1 may not use
> defadvice, it still allows such code to be written, which means you'll
> probably run across such code in the future and would like to read
> documentation on how it works.
> 
> I can understand taking it out of the manual, but it would be nice to have
> another manual for "features you may well run into in the wild, though you
> shouldn't write new code this way". I'm not proposing maintaining such a
> manual actively, but just copying deprecated sections like the "defadvice"
> content directly into it instead of deletion.

I'm not against our doing what you suggest (as I say, IMO the `defadvice'
doc should never have been removed from the manual, at least as long as
it is still supported (while deprecated)).

But what I propose is different.  And unlike what you suggest it should
require no extra effort, beyond the one-time effort of building the
HTML doc, which should not be a big deal.

My proposal is for GNU Emacs to post the complete Emacs and Elisp
manuals for older versions.  We could even add a command similar to
what I posted here, which takes the current release into account
when determining the URL.

Re: Please post older versions of GNU Emacs manuals on the web

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

  > My proposal is for GNU Emacs to post the complete Emacs and Elisp
  > manuals for older versions.  We could even add a command similar to
  > what I posted here, which takes the current release into account
  > when determining the URL.

I see no reason to object to having older manuals in
gnu.org/software/emacs, if someone wants to post them.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Please post older versions of GNU Emacs manuals on the web

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

  > Can GNU Emacs not provide its users with the doc for more
  > than one release on line?  How hard and how costly is that?

1+.

In addition, I think the text about defadvice was deleted from the
manual too soon.  Just because it is no longer the recommended
interface is no reason to remove it from the Lisp manual.

  > Nothing can ever be "removed" from the Internet.  You can find your
  > v24.3 version of ELisp manual, and in it the chapter about advising,
  > here:

Yes, one can do that, but `i defadvice' ought to work.

-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.

Re: Please post older versions of GNU Emacs manuals on the web

[John Wiegley]

>>>>> Richard Stallman <rms@gnu.org> writes:

> In addition, I think the text about defadvice was deleted from the manual
> too soon. Just because it is no longer the recommended interface is no
> reason to remove it from the Lisp manual.

OK, since there seems to be general agreement, how about we pull defadvice
back into the manual for 25.1, with a note that has been deprecated.

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

RE: Please post older versions of GNU Emacs manuals on the web

[Drew Adams]

> > In addition, I think the text about defadvice was deleted from the manual
> > too soon. Just because it is no longer the recommended interface is no
> > reason to remove it from the Lisp manual.
> 
> OK, since there seems to be general agreement, how about we pull defadvice
> back into the manual for 25.1, with a note that has been deprecated.

+1

Re: Please post older versions of GNU Emacs manuals on the web

[raman]

John Wiegley <jwiegley@gmail.com> writes:

1+.>>>>>> Richard Stallman <rms@gnu.org> writes:
>
>> In addition, I think the text about defadvice was deleted from the manual
>> too soon. Just because it is no longer the recommended interface is no
>> reason to remove it from the Lisp manual.
>
> OK, since there seems to be general agreement, how about we pull defadvice
> back into the manual for 25.1, with a note that has been deprecated.

-- 

Re: Please post older versions of GNU Emacs manuals on the web

[David Kastrup]

John Wiegley <jwiegley@gmail.com> writes:

>>>>>> Richard Stallman <rms@gnu.org> writes:
>
>> In addition, I think the text about defadvice was deleted from the
>> manual too soon. Just because it is no longer the recommended
>> interface is no reason to remove it from the Lisp manual.
>
> OK, since there seems to be general agreement, how about we pull
> defadvice back into the manual for 25.1, with a note that has been
> deprecated.

That seems to make sense.  However, Raman stated that nadvice does not
work for a number of use cases he currently uses defadvice for.  That
hole needs to be filled in some manner eventually, or we will never be
justified in completing deprecation.

-- 
David Kastrup

RE: Please post older versions of GNU Emacs manuals on the web

[Drew Adams]

> >> In addition, I think the text about defadvice was deleted from the
> >> manual too soon. Just because it is no longer the recommended
> >> interface is no reason to remove it from the Lisp manual.
> >
> > OK, since there seems to be general agreement, how about we pull
> > defadvice back into the manual for 25.1, with a note that has been
> > deprecated.
> 
> That seems to make sense.  However, Raman stated that nadvice does not
> work for a number of use cases he currently uses defadvice for.  That
> hole needs to be filled in some manner eventually, or we will never be
> justified in completing deprecation.

+1

There is also the question of using defadvice to modify a
doc string.  AFAICT, that is another hole unfilled by nadvice.

Re: Please post older versions of GNU Emacs manuals on the web

[Xue Fuqiao]

On Sun, Jan 3, 2016 at 12:46 AM, Drew Adams <drew.adams@oracle.com> wrote:

> How about posting multiple versions of the Emacs doc on line?

+1.

Projects like Python[1] and Atom[2] have multiple versions of online
documentation, and I often refer to docs for older versions of these
projects.  For Emacs, I think having multiple versions of online
documentation is more convenient than the alternative methods[3], for
both Emacs users and package developers.

Footnotes:

[1] https://www.python.org/doc/versions/
[2] https://atom.io/docs
[3] Such as skimming/searching the etc/NEWS.x files, using the Wayback
    Machine, or install older versions of Emacs and see their info files.

Re: Please post older versions of GNU Emacs manuals on the web

[raman]

1+. The decapitation of defadvice is indeed unfortunate -- it's
replacement (nadvice) doesn't do everything that the original defadvice
did --- and to my knowledge there were no known breakages with
defadvice. Since that change, the new advice layer  -- inconjunction
with the interactive-p change made some things harder, others
impossible -- for details see the comments in the code.

I hadn't realized that the documentation had been pulled -- guess it
makes sense from the overall perspective of what was essentially a move
to deprecate advice.


-- 

RE: Please post older versions of GNU Emacs manuals on the web

[Drew Adams]

> 1+. The decapitation of defadvice is indeed unfortunate -- it's
> replacement (nadvice) doesn't do everything that the original defadvice
> did --- and to my knowledge there were no known breakages with
> defadvice. Since that change, the new advice layer  -- inconjunction
> with the interactive-p change made some things harder, others
> impossible -- for details see the comments in the code.
> 
> I hadn't realized that the documentation had been pulled -- guess it
> makes sense from the overall perspective of what was essentially a move
> to deprecate advice.

IMO it was especially a move to promote the new.  Nothing about
deprecation calls for such doc removal.

Re: Please post older versions of GNU Emacs manuals on the web

[Teemu Likonen]

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

Drew Adams [2016-01-02 08:46:17-08] wrote:

> How about posting multiple versions of the Emacs doc on line?

A great example: PostgreSQL. Its documentation pages have a navigation
line with links that take user to the same (sub)page in different
PostgreSQL versions.

    This page in other versions: 9.1 / 9.2 / 9.3 / current (9.4) |
    Development versions: devel / 9.5 | Unsupported versions: 8.2 / 8.3
    / 8.4 / 9.0

For example, section "9.9. Date/Time Functions and Operators" for
PostgreSQL 9.4:
http://www.postgresql.org/docs/9.4/static/functions-datetime.html

Click a different version number in the navigation line and you stay in
the same section, just another PostgreSQL version.

-- 
/// Teemu Likonen   - .-..   <https://github.com/tlikonen> //
// PGP: 4E10 55DC 84E9 DFF6 13D7 8557 719D 69D3 2453 9450 ///

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

RE: Please post older versions of GNU Emacs manuals on the web

[Drew Adams]

> > Suppose you are using Emacs 24.3 (or Emacs 23 or...).  You visit
> > the Elisp manual and you use `i defadvice' to visit the advice doc.
> >
> > You want to visit the same manual section on line (HTTP).  Perhaps
> > you want to bookmark it for use when you do not have Emacs available.
> > Or maybe you want to send the URL to someone or post it in online
> > Emacs help.  Or maybe you want to print some of the HTML pages.
> >
> > Here's the rub.  Only the manuals for the latest Emacs release
> > are available on line.  And because Emacs (unwisely) removed the
> > doc for `defadvice', you are out of luck.  There is no online doc
> > for you.
> 
> Nothing can ever be "removed" from the Internet.  You can find your
> v24.3 version of ELisp manual, and in it the chapter about advising,
> here:
> 
> https://web.archive.org/web/20121224105042/http://www.gnu.org/software/emacs
> /manual/html_node/elisp/Advising-Functions.html#Advising-Functions
> 
> (Google for "wayback machine" if you want to find old versions of some
> URLs, including URLs that no longer exist.)

Sure, the Wayback Machine is a great resource, and the Internet
Archive responsible for it is a great place to visit in San Francisco.

But telling users to look to Internet archives (or to just google for
"defadvice emacs") does not really answer my question of "Why not?"
or respond to my proposal.

IMO we should offer Emacs users easy online access to the manuals for
older Emacs versions, the same way we offer them easy access to the
recent manuals and to both the recent and older versions of the software.

This is the least we could do to help users and show them respect.
It should not be easier to find information about older releases of
Oracle, Apple, Microsoft, or IBM software than it is to find such
info for Emacs.

Re: Please post older versions of GNU Emacs manuals on the web

[Ivan Shmakov]

>>>>> Drew Adams <drew.adams@oracle.com> writes:

[…]

 > Sure, the Wayback Machine is a great resource, and the Internet
 > Archive responsible for it is a great place to visit in San
 > Francisco.

 > But telling users to look to Internet archives (or to just google for
 > “defadvice emacs”) does not really answer my question of “Why not?”
 > or respond to my proposal.

	I see no reason we can’t do both: we can tell the users (or,
	rather, their UAs) to use the Wayback machine by providing links
	to the archived pages at http://gnu.org/s/emacs/manual/ – as
	well as all the Emacs documentation pages referenced there.
	With some effort, we could probably even link to the
	documentation for specific Emacs versions from there.

 > IMO we should offer Emacs users easy online access to the manuals for
 > older Emacs versions, the same way we offer them easy access to the
 > recent manuals and to both the recent and older versions of the
 > software.

 > This is the least we could do to help users and show them respect.
 > It should not be easier to find information about older releases of
 > Oracle, Apple, Microsoft, or IBM software than it is to find such
 > info for Emacs.

	I tend to agree that providing documentation for at least the
	latest releases of all the major versions is a well-established
	practice in the field, and I know of no reason why GNU in
	general – and not just Emacs – can’t follow it.

-- 
FSF associate member #7257  http://am-1.org/~ivan/      … 3013 B6A0 230E 334A

RE: Please post older versions of GNU Emacs manuals on the web

[Drew Adams]

> 1+.
> 
> In addition, I think the text about defadvice was deleted from the
> manual too soon.  Just because it is no longer the recommended
> interface is no reason to remove it from the Lisp manual.

See bug #16491.

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=16491