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

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

[Drew Adams]

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

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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#46084: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front

[Drew Adams]

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

bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front

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

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)

bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Thu, 28 Jan 2021 01:31:54 -0500
> Cc: larsi@gnus.org, 46084@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?

bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front

[Drew Adams]

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

bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "larsi@gnus.org" <larsi@gnus.org>,
>         "46084@debbugs.gnu.org"
> 	<46084@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.

bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front

[Drew Adams]

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

bug#46084: [External] : Re: bug#46084: 26.3; Elisp manual: provide a link to (eintro) up front

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

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