Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Adam Sjøgren]

Ten years ago I was confused by the documentation of car and cdr:

  ,----
  | (car LIST)
  | 
  | Return the car of LIST.  If arg is nil, return nil.
  `----

  ,----
  | (cdr LIST)
  | 
  | Return the cdr of LIST.  If arg is nil, return nil.
  `----

Which is which?!?

And I suggested a (bogus) improvement¹ based on reading too much into
the four letters L I S and T in the descriptions excerpted above.

While trying to write some basic elisp recently, I again realized that I
had forgotten which of car and cdr is which.

Based on one of the replies to my previous documentation improvement
attempt, I saw that there might be a way to improve the documentation
for my newbie case, without introducing something that is factually
wrong.

How about:

  ,----
  | (car '(a . b))
  | 
  | Return a.  If arg is nil, return nil.
  `----

  ,----
  | (cdr '(a . b))
  | 
  | Return b.  If arg is nil, return nil.
  `----

?

This variant of the documentation contains more information: what part
of the cons cell is returned by either function.

Also it doesn't use the four letters L I S and T, which might lead
somebody who hasn't read and memorized the Lisp intro, like me, to think
that what car/cdr works on is actually a LIST.

What do you think?

Hm, I realize now that you can call car and cdr on things that don't
look like '(a . b), so maybe this suggestion is as bad as the old one.
Maybe I should just try to stick to the mnemonic that car comes before
cdr alphabetically.

Or what about:

  ,----
  | (car LIST)
  | 
  | Return the car of LIST, eg if LIST is '(a . b) return a.  If arg is nil, return nil.
  `----

  ,----
  | (cdr LIST)
  | 
  | Return the cdr of LIST, eg if LIST is '(a . b) return b.  If arg is nil, return nil.
  `----


  Ducking,

   Adam


¹ https://debbugs.gnu.org/cgi/bugreport.cgi?bug=9082

-- 
 "You know, I *thought* earth's gravity felt                Adam Sjøgren
  exceptionally strong today."                         asjo@koldfront.dk

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Andreas Schwab]

Dotted notation isn't suitable for newcomers.

If you don't know what a list is, read the Emacs Lisp Intro.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[tomas]

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

On Wed, Jul 14, 2021 at 05:05:24PM +0200, Adam Sjøgren wrote:
> Ten years ago I was confused by the documentation of car and cdr:
> 
>   ,----
>   | (car LIST)
>   | 
>   | Return the car of LIST.  If arg is nil, return nil.
>   `----
> 
>   ,----
>   | (cdr LIST)
>   | 
>   | Return the cdr of LIST.  If arg is nil, return nil.
>   `----

Yes, this is quite a bit of LISP lore, which is based on how lists
are built of pairs. You have to keep those two concepts apart...

> Or what about:
> 
>   ,----
>   | (car LIST)
>   | 
>   | Return the car of LIST, eg if LIST is '(a . b) return a.  If arg is nil, return nil.
>   `----
> 
>   ,----
>   | (cdr LIST)
>   | 
>   | Return the cdr of LIST, eg if LIST is '(a . b) return b.  If arg is nil, return nil.
>   `----

... this, for example, doesn't exactly work: '(a . b) is not a (proper) list (unless
b is a list itself).

I think there's no way around drawing some box-and-pointer diagrams yourself.

If you are focusing on lists, perhaps the best way to view this is
that the car is the first element of the list and the cdr is the
rest of the list:

  (car '(a b c d e)) => 'a
  (cdr '(a b c d e)) => '(b c d e)

Now I don't know where your issue is. Is it the mnemonics for `car' and `cdr'?
Or the lack of a more thorough introduction on how lists are built of pairs?

Cheers
 - t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Adam Sjøgren <asjo@koldfront.dk>
> Date: Wed, 14 Jul 2021 17:05:24 +0200
> 
> Or what about:
> 
>   ,----
>   | (car LIST)
>   | 
>   | Return the car of LIST, eg if LIST is '(a . b) return a.  If arg is nil, return nil.
>   `----
> 
>   ,----
>   | (cdr LIST)
>   | 
>   | Return the cdr of LIST, eg if LIST is '(a . b) return b.  If arg is nil, return nil.
>   `----

The doc string nowadays includes a pointer to the ELisp manual, where
you can find a description of what is 'car' and what is 'cdr'.  I
think that's "good enough".

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> The doc string nowadays includes a pointer to the ELisp manual, where
> you can find a description of what is 'car' and what is 'cdr'.  I
> think that's "good enough".

The doc strings could say something terse like "The `car' is usually the
first element in LIST, and the `cdr' is usually the rest of LIST"
perhaps?

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

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: Adam Sjøgren <asjo@koldfront.dk>,  emacs-devel@gnu.org
> Date: Wed, 14 Jul 2021 18:03:00 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > The doc string nowadays includes a pointer to the ELisp manual, where
> > you can find a description of what is 'car' and what is 'cdr'.  I
> > think that's "good enough".
> 
> The doc strings could say something terse like "The `car' is usually the
> first element in LIST, and the `cdr' is usually the rest of LIST"
> perhaps?

Fine with me, although I'm not sure it would help if the reader really
doesn't know about these.

RE: [External] : Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Drew Adams]

> How about:
> 
>   ,----
>   | (car '(a . b))
>   |
>   | Return a.  If arg is nil, return nil.
>   `----
>   ,----
>   | (cdr '(a . b))
>   |
>   | Return b.  If arg is nil, return nil.
>   `----
>
> Or what about:
> 
>   ,----
>   | (car LIST)
>   |
>   | Return the car of LIST, eg if LIST is '(a . b) return a.  If arg is nil,
> return nil.
>   `----
> 
>   ,----
>   | (cdr LIST)
>   |
>   | Return the cdr of LIST, eg if LIST is '(a . b) return b.  If arg is nil,
> return nil.
>   `----


Allow Harold Abelson to present it:

https://www.youtube.com/watch?v=DrFkf-T-6Co

See 19:12 minutes into the recording.
In particular this, at 22:44:

  For any x and y:

    (car (cons x y)) is x
    (cdr (cons x y)) is y

That's it.  Starting from knowing _nothing_
about cons, car, and cdr, that pretty much
tells you everything.  It _defines_ all 3.

(This is an algebraic specification of an
abstract data type, where "cons" is an
_unspecified_ function (function symbol),
aka a "constructor".  It defines "car" and
"cdr", and it leaves "cons" undefined.)

Except that definition leaves out the nil
case (in most Lisps, including Elisp),
which is defined by this:

    (car nil) is nil
    (cdr nil) is nil

(And except for the case where "any x or
y" is, in effect, "bottom": where trying
to evaluate their sexps produces no x or
y _value_ - raises an error or doesn't
terminate.)

You don't need to know anything else about
what cons or nil are or might be, to
understand them, car, and cdr in the
context of pairs (and lists).

Sure, to know more about using them
practically you'll want to know about `eq'
and other things.  But as for what cons,
car, and cdr _are_ (and do), that's it.

(What you said is correct, but as others
have mentioned, the notation (a . b) needs
to first be understood.)

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> The doc strings could say something terse like "The `car' is usually the
> first element in LIST, and the `cdr' is usually the rest of LIST"
> perhaps?

The R6RS does it with examples:

(car pair)    procedure

Returns the contents of the car field of pair.

(car ’(a b c))                  ⇒  a
(car ’((a) b c d))              ⇒  (a)
(car ’(1 . 2))                  ⇒  1
(car ’())                 &assertion exception

https://docs.racket-lang.org/r6rs/r6rs-std/r6rs-Z-H-14.html#node_idx_612

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

>> The doc strings could say something terse like "The `car' is usually the
>> first element in LIST, and the `cdr' is usually the rest of LIST"
>> perhaps?
>
> Fine with me, although I'm not sure it would help if the reader really
> doesn't know about these.

Yeah, perhaps punting to the manual is the better strategy here.

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

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> The R6RS does it with examples:
>
> (car pair)    procedure
>
> Returns the contents of the car field of pair.
>
> (car ’(a b c))                  ⇒  a
> (car ’((a) b c d))              ⇒  (a)
> (car ’(1 . 2))                  ⇒  1
> (car ’())                 &assertion exception

Yeah, perhaps that'd be nice?  Something like:

(car '(a b c)) => a
(car '(1 . 2)) => 1
(car nil)      => nil                 
Also see `cdr'.

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

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Yeah, perhaps that'd be nice?  Something like:
>
> (car '(a b c)) => a
> (car '(1 . 2)) => 1
> (car nil)      => nil
> Also see `cdr'.

I like it.

In general, I think we should include more examples in our
documentation.  shortdoc.el is a step forward here, and it would be
even better if you could see those examples when you pull up the
docstring of a function.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 15 Jul 2021 13:39:54 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, Adam Sjøgren <asjo@koldfront.dk>, 
> 	Emacs developers <emacs-devel@gnu.org>
> 
> In general, I think we should include more examples in our
> documentation.  shortdoc.el is a step forward here, and it would be
> even better if you could see those examples when you pull up the
> docstring of a function.

IMO, examples are for the manual, not for the doc strings.  If some
parts of our manuals could benefit from more examples, patches for
that would be welcome.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Tim Cross]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Thu, 15 Jul 2021 13:39:54 +0200
>> Cc: Eli Zaretskii <eliz@gnu.org>, Adam Sjøgren <asjo@koldfront.dk>, 
>> 	Emacs developers <emacs-devel@gnu.org>
>> 
>> In general, I think we should include more examples in our
>> documentation.  shortdoc.el is a step forward here, and it would be
>> even better if you could see those examples when you pull up the
>> docstring of a function.
>
> IMO, examples are for the manual, not for the doc strings.  If some
> parts of our manuals could benefit from more examples, patches for
> that would be welcome.

I tend to agree. The doc strings should be short and concise and link to
the manual for more detailed explanation and examples. Things like eldoc
and tooltips can become annoying or overly distracting if they have lots
of text.

I do understand how the doc strings for car and cdr can seem less
helpful, especially as they are somewhat recursive i.e. I don't know
what the function 'car' does - docstring tells me it returns the car of
a list, but I still don't know what car is. However, to really
understand car (or cdr), you really need a bit more
understanding of lists, cons cells etc. So having a somewhat terse doc
string which includes a link to the manual may be a good thing as it
will encourage the user to look at the manual and possibly get some of
the additional information (plus caar, caadr, cddr etc).

-- 
Tim Cross

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Stefan Monnier]

Eli Zaretskii [2021-07-15 17:14:18] wrote:
>> From: Stefan Kangas <stefan@marxist.se>
>> Date: Thu, 15 Jul 2021 13:39:54 +0200
>> Cc: Eli Zaretskii <eliz@gnu.org>, Adam Sjøgren <asjo@koldfront.dk>, 
>> 	Emacs developers <emacs-devel@gnu.org>
>> In general, I think we should include more examples in our
>> documentation.  shortdoc.el is a step forward here, and it would be
>> even better if you could see those examples when you pull up the
>> docstring of a function.
>
> IMO, examples are for the manual, not for the doc strings.  If some
> parts of our manuals could benefit from more examples, patches for
> that would be welcome.

I think displaying the examples we have in shortdoc.el in the
*Help* buffer would make a lot of sense.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Yuan Fu]

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



> On Jul 15, 2021, at 11:21 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
> Eli Zaretskii [2021-07-15 17:14:18] wrote:
>>> From: Stefan Kangas <stefan@marxist.se>
>>> Date: Thu, 15 Jul 2021 13:39:54 +0200
>>> Cc: Eli Zaretskii <eliz@gnu.org>, Adam Sjøgren <asjo@koldfront.dk>, 
>>> 	Emacs developers <emacs-devel@gnu.org>
>>> In general, I think we should include more examples in our
>>> documentation.  shortdoc.el is a step forward here, and it would be
>>> even better if you could see those examples when you pull up the
>>> docstring of a function.
>> 
>> IMO, examples are for the manual, not for the doc strings.  If some
>> parts of our manuals could benefit from more examples, patches for
>> that would be welcome.
> 
> I think displaying the examples we have in shortdoc.el in the
> *Help* buffer would make a lot of sense.
> 
> 

Some one wrote quite a few examples here: https://github.com/xuchunyang/elisp-demos <https://github.com/xuchunyang/elisp-demos>

Yuan

[-- Attachment #2: Type: text/html, Size: 2070 bytes --]

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Stefan Monnier]

> However, to really understand car (or cdr), you really need a bit more
> understanding of lists, cons cells etc. So having a somewhat terse doc
> string which includes a link to the manual may be a good thing as it
> will encourage the user to look at the manual and possibly get some of
> the additional information (plus caar, caadr, cddr etc).

Agreed.  There's one detail that would be helpful, tho: make it clear
which is which, for those people who are familiar with the general idea
but aren't using Lisp often enough to remember which of `car` or `cdr`
return the right hand side of cons cell.


        Stefan

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> IMO, examples are for the manual, not for the doc strings.  If some
>> parts of our manuals could benefit from more examples, patches for
>> that would be welcome.

I think having some examples is fine in doc strings -- it can be
difficult to explain some concepts in words, but a simple example can be
a really efficient way to say what a function does.

But we should indeed not go overboard with examples in doc strings --
that's better left for the manual.

> I think displaying the examples we have in shortdoc.el in the
> *Help* buffer would make a lot of sense.

Yeah, I agree.

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

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eduardo Ochs]

There are some examples here too:
http://angg.twu.net/eev-intros/find-elisp-intro.html#2

(This is one of the sandboxed tutorials of eev.)
  Cheers,
    Eduardo Ochs
    http://angg.twu.net/#eev

On Thu, 15 Jul 2021 at 12:28, Yuan Fu <casouri@gmail.com> wrote:
>
>
>
> On Jul 15, 2021, at 11:21 AM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>
> Eli Zaretskii [2021-07-15 17:14:18] wrote:
>
> From: Stefan Kangas <stefan@marxist.se>
> Date: Thu, 15 Jul 2021 13:39:54 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, Adam Sjøgren <asjo@koldfront.dk>,
> Emacs developers <emacs-devel@gnu.org>
> In general, I think we should include more examples in our
> documentation.  shortdoc.el is a step forward here, and it would be
> even better if you could see those examples when you pull up the
> docstring of a function.
>
>
> IMO, examples are for the manual, not for the doc strings.  If some
> parts of our manuals could benefit from more examples, patches for
> that would be welcome.
>
>
> I think displaying the examples we have in shortdoc.el in the
> *Help* buffer would make a lot of sense.
>
>
>
> Some one wrote quite a few examples here: https://github.com/xuchunyang/elisp-demos
>
> Yuan

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Stefan Kangas <stefan@marxist.se>,  larsi@gnus.org,  asjo@koldfront.dk,
>   emacs-devel@gnu.org
> Date: Thu, 15 Jul 2021 11:21:42 -0400
> 
> > IMO, examples are for the manual, not for the doc strings.  If some
> > parts of our manuals could benefit from more examples, patches for
> > that would be welcome.
> 
> I think displaying the examples we have in shortdoc.el in the
> *Help* buffer would make a lot of sense.

Trivial examples bloat the session memory without any significant
effect on documentation quality.  People who must have examples should
really read the manual, IMO.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Thu, 15 Jul 2021 17:44:22 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, Stefan Kangas <stefan@marxist.se>,
>  asjo@koldfront.dk, emacs-devel@gnu.org
> 
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
> 
> >> IMO, examples are for the manual, not for the doc strings.  If some
> >> parts of our manuals could benefit from more examples, patches for
> >> that would be welcome.
> 
> I think having some examples is fine in doc strings -- it can be
> difficult to explain some concepts in words, but a simple example can be
> a really efficient way to say what a function does.
> 
> But we should indeed not go overboard with examples in doc strings --
> that's better left for the manual.

The danger of going overboard is exactly what bothers me.  Which is
why I think examples in doc strings should be used in exceptional
cases, where they are absolutely necessary.  Not as a "why not?"
addition.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Jean-Christophe Helary]

> On Jul 16, 2021, at 0:53, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Cc: Stefan Kangas <stefan@marxist.se>,  larsi@gnus.org,  asjo@koldfront.dk,
>>  emacs-devel@gnu.org
>> Date: Thu, 15 Jul 2021 11:21:42 -0400
>> 
>>> IMO, examples are for the manual, not for the doc strings.  If some
>>> parts of our manuals could benefit from more examples, patches for
>>> that would be welcome.
>> 
>> I think displaying the examples we have in shortdoc.el in the
>> *Help* buffer would make a lot of sense.
> 
> Trivial examples bloat the session memory without any significant
> effect on documentation quality.  People who must have examples should
> really read the manual, IMO.

For documentation "beginners", the helpful package and the inform package are *extremely* useful. I just discovered shortdoc, which looks really good and could definitely benefit from hypertext links to the function definitions (like helpful/inform offer).

I'd love to know if there are other documentation helpers around.

-- 
Jean-Christophe Helary @brandelune
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Lars Ingebrigtsen]

Jean-Christophe Helary <lists@traduction-libre.org> writes:

> I just discovered shortdoc, which
> looks really good and could definitely benefit from hypertext links to
> the function definitions (like helpful/inform offer).

I've now tweaked how the links in *Help* work so that they take you to
the proper place in the shortdoc buffer.

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

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Thu, 15 Jul 2021 18:30:35 +0200
> Cc: asjo@koldfront.dk, Eli Zaretskii <eliz@gnu.org>, stefan@marxist.se,
>  Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org
> 
> I've now tweaked how the links in *Help* work so that they take you to
> the proper place in the shortdoc buffer.

Thanks, but could we perhaps improve it?  The display looks something
like this now:

  split-string-shell-command is an autoloaded Lisp function in
  ‘shell.el’.

  (split-string-shell-command STRING)

    Other relevant functions are documented in the string group.
                                                   ------
    Probably introduced at or before Emacs version 28.1.
                                                   ----
  Split STRING (a shell command) into a list of strings.
  General shell syntax, like single and double quoting, as well as
  backslash quoting, is respected.

The new sentence interrupts the continuity, and now "Probably
introduced at ..." is missing the context and sounds like bad English.

I think it would be better to move the reference to other functions to
the end of the *Help* buffer text.  After all, it's a kind-of "See
also", which is normally found at the end.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> The new sentence interrupts the continuity, and now "Probably
> introduced at ..." is missing the context and sounds like bad English.
>
> I think it would be better to move the reference to other functions to
> the end of the *Help* buffer text.  After all, it's a kind-of "See
> also", which is normally found at the end.

That's true, but the "probably introduced" bit is the least important
thing in the *Help* buffer, so emphasising it in the current way is
unfortunate.

I think we should move it to the end of the buffer, or hide it by
default (with some button to reveal this and other less-than-vital
stuff).

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

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Cc: lists@traduction-libre.org,  asjo@koldfront.dk,  stefan@marxist.se,
>   monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Thu, 15 Jul 2021 19:01:40 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > The new sentence interrupts the continuity, and now "Probably
> > introduced at ..." is missing the context and sounds like bad English.
> >
> > I think it would be better to move the reference to other functions to
> > the end of the *Help* buffer text.  After all, it's a kind-of "See
> > also", which is normally found at the end.
> 
> That's true, but the "probably introduced" bit is the least important
> thing in the *Help* buffer, so emphasising it in the current way is
> unfortunate.
> 
> I think we should move it to the end of the buffer, or hide it by
> default (with some button to reveal this and other less-than-vital
> stuff).

That's orthogonal.

It is unreasonable to stick the reference to other functions before we
describe the current function.  It distracts and means the users need
to read more before they get to the "meat" for which they invoked the
help.  Let's not go overboard with these helpers: they are just
helpers, not the main part of the docs.  "See also" is at the end for
a reason.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Stefan Kangas]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> That's true, but the "probably introduced" bit is the least important
> thing in the *Help* buffer, so emphasising it in the current way is
> unfortunate.
>
> I think we should move it to the end of the buffer, or hide it by
> default (with some button to reveal this and other less-than-vital
> stuff).

Moving it to the end seems like an easy improvement to make.  I'm not
as sure about the shortdoc reference, as it seems more useful, but I
suppose we could move that to the end as well.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Lars Ingebrigtsen]

Stefan Kangas <stefan@marxist.se> writes:

> Moving it to the end seems like an easy improvement to make.  I'm not
> as sure about the shortdoc reference, as it seems more useful, but I
> suppose we could move that to the end as well.

Yup.  All the things that are now at the top (and indented) should be
moved to the end, I think.  (And the "probably" sentence needs to be
rephrased in that case.)

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

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Stefan Monnier]

> The danger of going overboard is exactly what bothers me.  Which is
> why I think examples in doc strings should be used in exceptional
> cases, where they are absolutely necessary.  Not as a "why not?"
> addition.

I don't think docstring should come with examples.  Examples should be
provided separately for use by shortdoc.el and friends.
Then `C-h f` can also show those examples, but it can place them
elsewhere (e.g. hidden by default with a button to show them or
something like that).


        Stefan

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Jean-Christophe Helary]

> On Jul 16, 2021, at 9:22, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> 
>> The danger of going overboard is exactly what bothers me.  Which is
>> why I think examples in doc strings should be used in exceptional
>> cases, where they are absolutely necessary.  Not as a "why not?"
>> addition.
> 
> I don't think docstring should come with examples.  Examples should be
> provided separately for use by shortdoc.el and friends.

Do you have a list of "friends"? 

What is the way to add examples to the shordoc display ?

> Then `C-h f` can also show those examples, but it can place them
> elsewhere (e.g. hidden by default with a button to show them or
> something like that).

So, that mechanism does not exist yet, correct ?

-- 
Jean-Christophe Helary @brandelune
https://mac4translators.blogspot.com
https://sr.ht/~brandelune/omegat-as-a-book/

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Lars Ingebrigtsen <larsi@gnus.org>,  stefan@marxist.se,
>   asjo@koldfront.dk,  emacs-devel@gnu.org
> Date: Thu, 15 Jul 2021 20:22:30 -0400
> 
> I don't think docstring should come with examples.  Examples should be
> provided separately for use by shortdoc.el and friends.
> Then `C-h f` can also show those examples, but it can place them
> elsewhere (e.g. hidden by default with a button to show them or
> something like that).

This suggestion is fine with me.  Thanks.

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Stefan Monnier]

Jean-Christophe Helary [2021-07-16 11:08:42] wrote:
>> On Jul 16, 2021, at 9:22, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
>>> The danger of going overboard is exactly what bothers me.  Which is
>>> why I think examples in doc strings should be used in exceptional
>>> cases, where they are absolutely necessary.  Not as a "why not?"
>>> addition.
>> I don't think docstring should come with examples.  Examples should be
>> provided separately for use by shortdoc.el and friends.
> Do you have a list of "friends"? 

I don't have many friends, I'm afraid, no ;-)

> What is the way to add examples to the shordoc display ?

I think currently you need to add them to shortdoc.el.

>> Then `C-h f` can also show those examples, but it can place them
>> elsewhere (e.g. hidden by default with a button to show them or
>> something like that).
> So, that mechanism does not exist yet, correct ?

Correct.


        Stefan

Re: Add hints to documentation of car and cdr for (e)lisp newcomers - take 2

[Basil L. Contovounesios]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> What is the way to add examples to the shordoc display ?
>
> I think currently you need to add them to shortdoc.el.

FWIW, packages can also use the macro define-short-documentation-group
or function shortdoc-add-function outside of shortdoc.el.

Their only current limitation is that they require shortdoc.el to be
loaded, so external packages that wish to avoid that and the required
backward-compatibility dance will inevitably resort to using
(with-eval-after-load 'shortdoc ...).  I'm fine with that, though.

-- 
Basil