GNU bug report logs - #46084
26.3; Elisp manual: provide a link to (eintro) up front

Previous Next

Package: emacs;

Reported by: Drew Adams <drew.adams <at> oracle.com>

Date: Sun, 24 Jan 2021 18:57:01 UTC

Severity: wishlist

Found in version 26.3

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 46084 in the body.
You can then email your comments to 46084 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Sun, 24 Jan 2021 18:57:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Sun, 24 Jan 2021 18:57:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 26.3; Elisp manual: provide a link to (eintro) up front
Date: Sun, 24 Jan 2021 18:55:56 +0000
Somewhere up front in the Elisp manual, please consider providing a link
to the eintr manual.  One possible place is in node (elisp)
`Introduction'.

Let people who arrive at the Elisp manual know that there is an intro to
Elisp.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Wed, 27 Jan 2021 02:50:02 GMT) Full text and rfc822 format available.

Message #8 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 46084 <at> debbugs.gnu.org
Subject: Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front
Date: Wed, 27 Jan 2021 03:49:14 +0100
Drew Adams <drew.adams <at> oracle.com> writes:

> Somewhere up front in the Elisp manual, please consider providing a link
> to the eintr manual.  One possible place is in node (elisp)
> `Introduction'.
>
> Let people who arrive at the Elisp manual know that there is an intro to
> Elisp.

The eintr manual is for people who aren't programmers.  The lispref
manual is a reference manual (for programmers).  So adding a link like
that doesn't seem to make much sense.  Closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no




bug closed, send any further explanations to 46084 <at> debbugs.gnu.org and Drew Adams <drew.adams <at> oracle.com> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Wed, 27 Jan 2021 02:50:02 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Wed, 27 Jan 2021 02:59:01 GMT) Full text and rfc822 format available.

Message #13 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: "46084 <at> debbugs.gnu.org" <46084 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to
 (eintro) up front
Date: Wed, 27 Jan 2021 02:58:48 +0000
> The eintr manual is for people who aren't programmers.  The lispref
> manual is a reference manual (for programmers).  So adding a link like
> that doesn't seem to make much sense.  Closing.

That makes NO sense to me.

Everyone who uses Lisp is still learning it.

Anyone who tries to learn Elisp can benefit from the Eintr help.

Anyone who uses the Eintr guidance can also benefit from referring to the Elisp manual for specific info about this or that thing that they're learning or they're interested in.

Many, many people will arrive directly at the Elisp manual - by googling, being referred from a website or mailing list, etc.  The Elisp manual is MUCH wider known and referred to by people.

An Elisp learner (and others) can _easily_ arrive at the Elisp manual, and not have the faintest idea that they might be able to benefit from the Eintr book.

Why on earth would we want to not help a reader of either manual know about the existence of the other?

Why do you think that reference books should not refer to user guides?  Or vice versa?  I can assure you that serious doc systems have tons of cross-references between reference material and guide material.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Thu, 28 Jan 2021 06:33:02 GMT) Full text and rfc822 format available.

Message #16 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 46084 <at> debbugs.gnu.org
Subject: Re: bug#46084: [External] : Re: bug#46084: 26.3;
 Elisp manual: provide a link to (eintro) up front
Date: Thu, 28 Jan 2021 01:31:54 -0500
[[[ 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. ]]]

I agree, let's make the link.  It costs almost nothing on any
dimension, and you're right that it will help some people.

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






Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Thu, 28 Jan 2021 14:15:02 GMT) Full text and rfc822 format available.

Message #19 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: larsi <at> gnus.org, 46084 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#46084: [External] : Re: bug#46084: 26.3;
 Elisp manual: provide a link to (eintro) up front
Date: Thu, 28 Jan 2021 16:14:21 +0200
> From: Richard Stallman <rms <at> gnu.org>
> Date: Thu, 28 Jan 2021 01:31:54 -0500
> Cc: larsi <at> gnus.org, 46084 <at> debbugs.gnu.org
> 
> I agree, let's make the link.  It costs almost nothing on any
> dimension, and you're right that it will help some people.

Did anyone look in the ELisp manual before writing about this issue?
Because there is already a link.  The ELisp manual says in its first
chapter, "Introduction":

     This manual attempts to be a full description of Emacs Lisp.  For a
  beginner’s introduction to Emacs Lisp, see ‘An Introduction to Emacs
  Lisp Programming’, by Bob Chassell, also published by the Free Software
  Foundation.  This manual presumes considerable familiarity with the use
  of Emacs for editing; see ‘The GNU Emacs Manual’ for this basic
  information.

What else is missing?




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Thu, 28 Jan 2021 15:17:01 GMT) Full text and rfc822 format available.

Message #22 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, "rms <at> gnu.org" <rms <at> gnu.org>
Cc: "larsi <at> gnus.org" <larsi <at> gnus.org>,
 "46084 <at> debbugs.gnu.org" <46084 <at> debbugs.gnu.org>
Subject: RE: bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual:
 provide a link to (eintro) up front
Date: Thu, 28 Jan 2021 15:16:09 +0000
> > I agree, let's make the link.  It costs almost nothing on any
> > dimension, and you're right that it will help some people.
> 
> Did anyone look in the ELisp manual before writing about this issue?

Yes, I did.

> Because there is already a link.

Not that I see.  At least not in Emacs 26.3
(or 27.1, or the latest 28 MS Windows
snapshot I have).

> The ELisp manual says in its first chapter, "Introduction":
> 
>      This manual attempts to be a full description of Emacs Lisp.  For
> a
>   beginner’s introduction to Emacs Lisp, see ‘An Introduction to Emacs
>   Lisp Programming’, by Bob Chassell, also published by the Free
> Software
>   Foundation.  This manual presumes considerable familiarity with the
> use
>   of Emacs for editing; see ‘The GNU Emacs Manual’ for this basic
>   information.
> 
> What else is missing?

A link (as the enhancement request says).  Not just
a textual mention of the manual's title, but an Info
link.
___

And while we're at it, please consider adding a link
(a link) to the Emacs manual, as well.

Textual references are great.  Linked textual refs
are even better.
___

BTW, "This manual" can be misunderstood in the last
sentence you quoted.  We presumably want it to mean,
like the first "This manual" of the paragraph, the
Elisp manual.  But immediately following mention of
Eintr, it becomes a bit ambiguous.  Better to make
explicit which manual is meant.


Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Thu, 28 Jan 2021 15:29:01 GMT) Full text and rfc822 format available.

Message #25 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, rms <at> gnu.org, 46084 <at> debbugs.gnu.org
Subject: Re: bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual:
 provide a link to (eintro) up front
Date: Thu, 28 Jan 2021 17:28:31 +0200
> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "larsi <at> gnus.org" <larsi <at> gnus.org>,
>         "46084 <at> debbugs.gnu.org"
> 	<46084 <at> debbugs.gnu.org>
> Date: Thu, 28 Jan 2021 15:16:09 +0000
> 
> > Because there is already a link.
> 
> Not that I see.  At least not in Emacs 26.3
> (or 27.1, or the latest 28 MS Windows
> snapshot I have).

Maybe your Info manuals are (severely) outdated.  This text is there
as far back as Emacs 23.

> > What else is missing?
> 
> A link (as the enhancement request says).  Not just
> a textual mention of the manual's title, but an Info
> link.
> ___
> 
> And while we're at it, please consider adding a link
> (a link) to the Emacs manual, as well.
> 
> Textual references are great.  Linked textual refs
> are even better.
> ___
> 
> BTW, "This manual" can be misunderstood in the last
> sentence you quoted.  We presumably want it to mean,
> like the first "This manual" of the paragraph, the
> Elisp manual.  But immediately following mention of
> Eintr, it becomes a bit ambiguous.  Better to make
> explicit which manual is meant.

Nothing is ever good enough, sigh.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Thu, 28 Jan 2021 15:47:01 GMT) Full text and rfc822 format available.

Message #28 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "larsi <at> gnus.org" <larsi <at> gnus.org>, "rms <at> gnu.org" <rms <at> gnu.org>,
 "46084 <at> debbugs.gnu.org" <46084 <at> debbugs.gnu.org>
Subject: RE: bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual:
 provide a link to (eintro) up front
Date: Thu, 28 Jan 2021 15:46:17 +0000
> > > Because there is already a link.
> >
> > Not that I see.  At least not in Emacs 26.3
> > (or 27.1, or the latest 28 MS Windows
> > snapshot I have).
>
> Maybe your Info manuals are (severely) outdated.
> This text is there as far back as Emacs 23.

I confirmed that the text is there.  And I
reiterated that the enhancement request is
about a missing link, not missing text.

> Nothing is ever good enough, sigh.

Please don't take it personally.  There's
always room for improvement, yes.

I'm a writer, and every writer knows that
it's very easy to write something that can
be misunderstood, and that nearly everything
is ripe for a possible rewrite.

That added suggestion about "This manual"
is a nit - not important.  It's not what
this enhancement request is about.  I wrote
"BTW," and separated that minor suggestion
from the other text.

The enhancement request is just to add a
link to the Eintr manual from the Elisp
manual, preferably up front somewhere, e.g.
in the Introduction.




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#46084; Package emacs. (Fri, 29 Jan 2021 06:36:01 GMT) Full text and rfc822 format available.

Message #31 received at 46084 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: eliz <at> gnu.org, larsi <at> gnus.org, 46084 <at> debbugs.gnu.org
Subject: Re: bug#46084: [External] : Re: bug#46084: 26.3;
 Elisp manual: provide a link to (eintro) up front
Date: Fri, 29 Jan 2021 01:35:49 -0500
[[[ 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. ]]]

  > > Nothing is ever good enough, sigh.

  > Please don't take it personally.  There's
  > always room for improvement, yes.

I like that way of looking at it.

We have all overlooked opportunities to make Emacs better.
When people suggest one that we overlooked, that gives us a chance
to make up for the omission.

It's GNU Project policy to thank people for bug reports.
That's not meant to be perfunctory.  Without bug reports
we would not know what er need to do.  So please think
about appreciation for them.

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






bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Fri, 26 Feb 2021 12:24:16 GMT) Full text and rfc822 format available.

This bug report was last modified 4 years and 170 days ago.

Previous Next


GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.