all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
From: Bob Rogers <rogers@rgrjr.com>
To: "João Távora" <joaotavora@gmail.com>
Cc: Ahmed Khanzada <me@enzu.ru>, emacs-devel@gnu.org
Subject: Re: Plan of attack or division of labor for documenting cl-lib
Date: Sat, 2 Dec 2023 16:50:56 -0800	[thread overview]
Message-ID: <25963.53488.700728.314698@orion.rgrjr.com> (raw)
In-Reply-To: <CALDnm53CTJUnp=0v534nex3vpncprDYLSAzSEvg=GSu0tamx+A@mail.gmail.com>

   From: João Távora <joaotavora@gmail.com>
   Date: Sat, 2 Dec 2023 21:54:17 +0000

   On Sat, Dec 2, 2023 at 8:16 PM Bob Rogers <rogers@rgrjr.com> wrote:

   >    I was wondering if we should portion out work so that no one
   >    duplicates effort?

   > Good idea.

   Yes.  Various notes, in no particular order of importance:

   * I've got a number of docstring already done in a branch
     called feature/cl-lib-improvements, mostly to cl-seq.el

Excellent; great to see you've been thinking (and working) along these
lines.

   . . .

   * It is also useful to note that there is a open-source
     version of the Common Lisp specification with a license
     that is much more permissive than LispWork's Hyperspec . . 

Nice; thanks.

   * When editing docstrings, I'd say it's a good idea to edit
     them (even if they've been already been touched by someone
     else) so that the language and formulations of common elements
     are consistent.  For example, I've been editing the last
     line of docstrings so they look like:

       (fn FUNCTION SEQ &key FROM-END START END INITIAL-VALUE KEY...)

     instead of

       (fn FUNCTION SEQ [KEYWORD VALUE]...)"

     And then I try relatively hard to describe the keyword arguments
     (of 'cl-reduce', in this case) in the order that they appear in
     this list.

Yes; seems to me that just amounts to bringing them up to Emacs
documentation standards.

   * Sometimes I also add this formulaic reference to the manual:

       TEST and KEY are keyword arguments.  See info node
       `(cl) Program Structure > Argument Lists' for details.

     But I've not yet decided if it's a good idea to repeat this
     in every docstring.  Maybe, given the apparent unfamiliarity
     with keyword arguments by some Emacs developers.

Sigh.  This wouldn't be necessary if &key were to appear in emacs 30
. . . but I suppose we shouldn't count on that.

   * Be very careful when describing these utils as some of
     them aren't perfect implementations of the CL spec and we
     may need to remain bug-compatible . . .

Good point.

     . . . In the case of cl-mismatch I'm thinking we should fix the
     bugs and deal with any flak.

Bug-fixing is good, but it seems to me this is affects a controversial
area of the code.  Perhaps it would be better to separate documentation
and unrelated code changes?

   * Unit tests are very welcome too.  Place them in

       test/lisp/emacs-lisp/cl-lib-tests.el
       test/lisp/emacs-lisp/cl-seq-tests.el
       test/lisp/emacs-lisp/cl-macs-tests.el

   Let me know what you think of this plan,
   João

I like it; count me in.

					-- Bob



  reply	other threads:[~2023-12-03  0:50 UTC|newest]

Thread overview: 7+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-12-02 14:46 Plan of attack or division of labor for documenting cl-lib Ahmed Khanzada
2023-12-02 20:16 ` Bob Rogers
2023-12-02 21:54   ` João Távora
2023-12-03  0:50     ` Bob Rogers [this message]
     [not found]     ` <25963.53547.739157.559536@orion.rgrjr.com>
2023-12-03 19:55       ` Ahmed Khanzada
2023-12-04  3:10     ` Richard Stallman
2023-12-04  4:57       ` tomas

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=25963.53488.700728.314698@orion.rgrjr.com \
    --to=rogers@rgrjr.com \
    --cc=emacs-devel@gnu.org \
    --cc=joaotavora@gmail.com \
    --cc=me@enzu.ru \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.