* Plan of attack or division of labor for documenting cl-lib @ 2023-12-02 14:46 Ahmed Khanzada 2023-12-02 20:16 ` Bob Rogers 0 siblings, 1 reply; 7+ messages in thread From: Ahmed Khanzada @ 2023-12-02 14:46 UTC (permalink / raw) To: emacs-devel; +Cc: joaotavora, rogers 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* Plan of attack or division of labor for documenting cl-lib 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 0 siblings, 1 reply; 7+ messages in thread From: Bob Rogers @ 2023-12-02 20:16 UTC (permalink / raw) To: Ahmed Khanzada; +Cc: emacs-devel, joaotavora 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/ ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Plan of attack or division of labor for documenting cl-lib 2023-12-02 20:16 ` Bob Rogers @ 2023-12-02 21:54 ` João Távora 2023-12-03 0:50 ` Bob Rogers ` (2 more replies) 0 siblings, 3 replies; 7+ messages in thread From: João Távora @ 2023-12-02 21:54 UTC (permalink / raw) To: Bob Rogers; +Cc: Ahmed Khanzada, emacs-devel 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Plan of attack or division of labor for documenting cl-lib 2023-12-02 21:54 ` João Távora @ 2023-12-03 0:50 ` Bob Rogers [not found] ` <25963.53547.739157.559536@orion.rgrjr.com> 2023-12-04 3:10 ` Richard Stallman 2 siblings, 0 replies; 7+ messages in thread From: Bob Rogers @ 2023-12-03 0:50 UTC (permalink / raw) To: João Távora; +Cc: Ahmed Khanzada, emacs-devel 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
[parent not found: <25963.53547.739157.559536@orion.rgrjr.com>]
* Re: Plan of attack or division of labor for documenting cl-lib [not found] ` <25963.53547.739157.559536@orion.rgrjr.com> @ 2023-12-03 19:55 ` Ahmed Khanzada 0 siblings, 0 replies; 7+ messages in thread From: Ahmed Khanzada @ 2023-12-03 19:55 UTC (permalink / raw) To: Bob Rogers, João Távora; +Cc: emacs-devel 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Plan of attack or division of labor for documenting cl-lib 2023-12-02 21:54 ` João Távora 2023-12-03 0:50 ` Bob Rogers [not found] ` <25963.53547.739157.559536@orion.rgrjr.com> @ 2023-12-04 3:10 ` Richard Stallman 2023-12-04 4:57 ` tomas 2 siblings, 1 reply; 7+ messages in thread From: Richard Stallman @ 2023-12-04 3:10 UTC (permalink / raw) To: João Távora; +Cc: rogers, me, emacs-devel [[[ 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) ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: Plan of attack or division of labor for documenting cl-lib 2023-12-04 3:10 ` Richard Stallman @ 2023-12-04 4:57 ` tomas 0 siblings, 0 replies; 7+ messages in thread From: tomas @ 2023-12-04 4:57 UTC (permalink / raw) To: Richard Stallman Cc: João Távora, rogers, me, emacs-devel [-- 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 --] ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2023-12-04 4:57 UTC | newest] Thread overview: 7+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 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 [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
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.