Plan of attack or division of labor for documenting cl-lib

Plan of attack or division of labor for documenting cl-lib

[Ahmed Khanzada]

I just finished reading the cl-lib thread (well, most of it)

A conclusion was that cl-lib should have improved documentation, and a
few people were willing to do so. I have CC'd a couple people that I noticed.

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

Christmas break is coming up, so I think some of us will have the time.

If someone can't finish their commitment, as often happens, the others
can jump in.

Ahmed

Plan of attack or division of labor for documenting cl-lib

[Bob Rogers]

   From: Ahmed Khanzada <me@enzu.ru>
   Date: Sat, 02 Dec 2023 09:46:39 -0500

   I just finished reading the cl-lib thread (well, most of it)

   A conclusion was that cl-lib should have improved documentation, and
   a few people were willing to do so. I have CC'd a couple people that
   I noticed.

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

Good idea.

   Christmas break is coming up, so I think some of us will have the time.

   If someone can't finish their commitment, as often happens, the others
   can jump in.

   Ahmed

I suggest the two of you each pick an end of the file and work toward
the middle, and I will jump in when I can.  (I am currently stymied by
having been unable to figure out how to request commit privileges to the
Emacs repo; those in the know may consider this a plea for guidance.)

					-- Bob Rogers
					   http://www.rgrjr.com/

Re: Plan of attack or division of labor for documenting cl-lib

[João Távora]

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

* In this branch I'm not only doing docstring improvements,
  but also reworking some internals, adding tests, and improving
  performance of some utilities.

* I propose we continue work on this branch, as it is easy
  to check (via vc-print-log, vc-version-history, or whatever
  your preferred Git tool is) what has already been done and
  by whom.

* To simplify things, I've pushed this branch over to my GitHub
  fork of Emacs

    https://github.com/joaotavora/emacs

  I can grant commit privileges to anyone who messages me
  privately with an interest in contributing this work.  Of
  course, you can also contribute patches to this branch via
  email (either via the bug tracker or by messaging me).

* After all the work has been done, or has reached some
  kind of milestone, we can integrate it in Emacs proper.

* It is important to check that you have your FSF copyright
  assignments in place.

* 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.
  I haven't yet checked the license to see if it is GPL compatible
  and thus if we can derive some work from it.  Here is the URL:

    https://cl-community-spec.github.io/pages/index.html

  even if the license isn't compatible it is a nice resource
  nonetheless.

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

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

* 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.  cl-loop is a notable example,
  but other more innocent-looking utils like cl-mismatch are
  affected.  In other cases, our utils go some unneeded extra miles
  like cl-set-difference guaranteeing relative order.  In this
  last case we shouldn't describe that in the docstring, IMO, but
  that feature must stay.  In the case of cl-mismatch I'm thinking
  we should fix the bugs and deal with any flak.

* 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

Re: Plan of attack or division of labor for documenting cl-lib

[Bob Rogers]

   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

Re: Plan of attack or division of labor for documenting cl-lib

[Ahmed Khanzada]

Yup, this sounds good. After I submit my first PR against your emacs
fork on GitHub, feel free to give me commit rights.

I have already submitted documentation to the FSF to contribute to Emacs.

Re: Plan of attack or division of labor for documenting cl-lib

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

Please do not invite people to use github for work on GNU Emacs.
Using github for development excludes people who refuse to run nonfree
software.

See https://www.gnu.org/software/repo-criteria-evaluation.html for
more details, and for other repos that respect freedom more.

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

Re: Plan of attack or division of labor for documenting cl-lib

[tomas]

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

On Sun, Dec 03, 2023 at 10:10:47PM -0500, Richard Stallman wrote:
> [[[ 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. ]]]
> 
> Please do not invite people to use github for work on GNU Emacs.

Thanks.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]