GNU bug report logs - #31683
emacs-lisp-intro.texi - opportunity to link eintr to elisp

Previous Next

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

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

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

From: Van L <van <at> scratch.space>
To: bug-gnu-emacs <at> gnu.org
Subject: emacs-lisp-intro.texi - opportunity to link eintr to elisp
Date: Sat, 2 Jun 2018 20:39:49 +1000

Hello.

The footnote at line 2150 *indirectly* links to (elisp) Printed Representation, which details what an expression is.

: 8cda6f8f44b (Glenn Morris             2007-09-06  2150) learn how to read it.@footnote{@code{(quote hello)} is an expansion of

At line 2508 in the summary is an opportunity to *directly* link the mention of expressions to (elisp) Printed Representation.

: 8cda6f8f44b (Glenn Morris             2007-09-06  2508) Lisp programs are made up of expressions, which are lists or single atoms.

(I will re-open this bug number for future opportunities to link eintr, elisp after it is closed.)

Message #10 received at 31683-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Van L <van <at> scratch.space>
Cc: 31683-done <at> debbugs.gnu.org
Subject: Re: bug#31683: emacs-lisp-intro.texi - opportunity to link eintr to
 elisp
Date: Sat, 02 Jun 2018 14:36:12 +0300

> From: Van L <van <at> scratch.space>
> Date: Sat, 2 Jun 2018 20:39:49 +1000
> 
> The footnote at line 2150 *indirectly* links to (elisp) Printed Representation, which details what an expression is.
> 
> : 8cda6f8f44b (Glenn Morris             2007-09-06  2150) learn how to read it.@footnote{@code{(quote hello)} is an expansion of

I don't think I agree: the relation to expressions is too far-fetched
here.

> At line 2508 in the summary is an opportunity to *directly* link the mention of expressions to (elisp) Printed Representation.
> 
> : 8cda6f8f44b (Glenn Morris             2007-09-06  2508) Lisp programs are made up of expressions, which are lists or single atoms.

Expressions were explained in the previous sub-sections, so I don't
think we need to add a cross-reference here.  (In any case, having
cross-references in a Summary is IME bad style, since it means we
failed to describe something in the parts being summarized.  A summary
should never say anything that wasn't already said before.)

> (I will re-open this bug number for future opportunities to link eintr, elisp after it is closed.)

Please don't, as each issue should be a separate bug report.

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

From: Van L <van <at> scratch.space>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31683-done <at> debbugs.gnu.org
Subject: Re: bug#31683: emacs-lisp-intro.texi - opportunity to link eintr to
 elisp
Date: Sat, 2 Jun 2018 23:30:35 +1000

> Eli Zaretskii writes:
> 
>> From: Van L <van <at> scratch.space>
>> Date: Sat, 2 Jun 2018 20:39:49 +1000
>> 
>> The footnote at line 2150 *indirectly* links to (elisp) Printed Representation, which details what an expression is.
>> 
>> : 8cda6f8f44b (Glenn Morris             2007-09-06  2150) learn how to read it.@footnote{@code{(quote hello)} is an expansion of
> 
> I don't think I agree: the relation to expressions is too far-fetched
> here.

#+BEGIN_EXAMPLE
8cda6f8f44b (Glenn Morris             2007-09-06  1151) The printed representation of both atoms and lists are called
8cda6f8f44b (Glenn Morris             2007-09-06  1152) @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.
8cda6f8f44b (Glenn Morris             2007-09-06  1153) The word @dfn{expression} by itself can refer to either the printed
8cda6f8f44b (Glenn Morris             2007-09-06  1154) representation, or to the atom or list as it is held internally in the
8cda6f8f44b (Glenn Morris             2007-09-06  1155) computer.  Often, people use the term @dfn{expression}
8cda6f8f44b (Glenn Morris             2007-09-06  1156) indiscriminately.  (Also, in many texts, the word @dfn{form} is used
8cda6f8f44b (Glenn Morris             2007-09-06  1157) as a synonym for expression.)

b8d4c8d0e93 doc/lispref/objects.texi (Glenn Morris        2007-09-06   95)   In other languages, an expression is text; it has no other form.  In
b8d4c8d0e93 doc/lispref/objects.texi (Glenn Morris        2007-09-06   96) Lisp, an expression is primarily a Lisp object and only secondarily the
b8d4c8d0e93 doc/lispref/objects.texi (Glenn Morris        2007-09-06   97) text that is the object's read syntax.  Often there is no need to
b8d4c8d0e93 doc/lispref/objects.texi (Glenn Morris        2007-09-06   98) emphasize this distinction, but you must keep it in the back of your
b8d4c8d0e93 doc/lispref/objects.texi (Glenn Morris        2007-09-06   99) mind, or you will occasionally be very confused.

#+END_EXAMPLE

Anyway. I find the above two snippets useful to link.

>> (I will re-open this bug number for future opportunities to link eintr, elisp after it is closed.)
> 
> Please don't, as each issue should be a separate bug report.

I won’t.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Van L <van <at> scratch.space>
Cc: 31683 <at> debbugs.gnu.org
Subject: Re: bug#31683: emacs-lisp-intro.texi - opportunity to link eintr to
 elisp
Date: Sat, 02 Jun 2018 17:13:18 +0300

> From: Van L <van <at> scratch.space>
> Date: Sat, 2 Jun 2018 23:30:35 +1000
> Cc: 31683-done <at> debbugs.gnu.org
> 
> >> : 8cda6f8f44b (Glenn Morris             2007-09-06  2150) learn how to read it.@footnote{@code{(quote hello)} is an expansion of
> > 
> > I don't think I agree: the relation to expressions is too far-fetched
> > here.
> 
> #+BEGIN_EXAMPLE
> 8cda6f8f44b (Glenn Morris             2007-09-06  1151) The printed representation of both atoms and lists are called
> 8cda6f8f44b (Glenn Morris             2007-09-06  1152) @dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}.

Which is actually related to the second location you mentioned, and
seems to explain enough of what an s-expression is to be
self-contained.

In general, this manual is not an introduction chapter for the ELisp
manual, and never wanted to be.  It only includes cross-references to
the ELisp manual where it just mentions some subtlety, but doesn't
describe it.  These two places don't seem like they fit.

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

From: Van L <van <at> scratch.space>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31683 <at> debbugs.gnu.org
Subject: Re: bug#31683: emacs-lisp-intro.texi - opportunity to link eintr to
 elisp
Date: Sun, 3 Jun 2018 12:11:48 +1000

> Eli Zaretskii writes:
> 
> Which is actually related to the second location you mentioned

Which was the summary section.

> In general, this manual is not an introduction chapter for the ELisp
> manual

The impression given in other discussion about this was the intention for eintr to be close and interwoven with elisp at a level of detail that bends over backwards for a ,non-programmer'.

There are in general two kinds of people. 

One digests the elisp. Straight away.

The other prefers eintr at first. 

Having tips of the elisp in the eintr is consciousness raising and invites the reader to go far one day.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Van L <van <at> scratch.space>
Cc: 31683 <at> debbugs.gnu.org
Subject: Re: bug#31683: emacs-lisp-intro.texi - opportunity to link eintr to
 elisp
Date: Sun, 03 Jun 2018 18:19:07 +0300

> From: Van L <van <at> scratch.space>
> Date: Sun, 3 Jun 2018 12:11:48 +1000
> Cc: 31683 <at> debbugs.gnu.org
> 
> 
> > Eli Zaretskii writes:
> > 
> > Which is actually related to the second location you mentioned
> 
> Which was the summary section.

Right.

> > In general, this manual is not an introduction chapter for the ELisp
> > manual
> 
> The impression given in other discussion about this was the intention for eintr to be close and interwoven with elisp at a level of detail that bends over backwards for a ,non-programmer'.
> 
> There are in general two kinds of people. 
> 
> One digests the elisp. Straight away.
> 
> The other prefers eintr at first. 
> 
> Having tips of the elisp in the eintr is consciousness raising and invites the reader to go far one day.

I'm not saying there should be no cross-references to ELisp -- we
already have quite a few.  I'm saying that having a cross-reference in
every place where we could possibly place one is not TRT for this
manual, because it is not a reference manual.

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

From: Van L <van <at> scratch.space>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 31683 <at> debbugs.gnu.org
Subject: Re: bug#31683: emacs-lisp-intro.texi - opportunity to link eintr to
 elisp
Date: Mon, 4 Jun 2018 11:26:40 +1000

> Eli Zaretskii writes:
> 
> because it is not a reference manual

I was motivated to make this suggestion only because I followed the footnote trail to two hops removed and found that snippet worth advertising to a new reader a second time incase they didn’t go the distance the first. Anyway. Your call.

Previous Next

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