From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Bob Rogers Newsgroups: gmane.emacs.devel Subject: Re: Plan of attack or division of labor for documenting cl-lib Date: Sat, 2 Dec 2023 16:50:56 -0800 Message-ID: <25963.53488.700728.314698@orion.rgrjr.com> References: <87zfys1x2o.fsf@enzu.ru> <25963.37003.97339.88214@orion.rgrjr.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="19554"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Ahmed Khanzada , emacs-devel@gnu.org To: =?iso-8859-1?Q?Jo=E3o_T=E1vora?= Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sun Dec 03 01:52:08 2023 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1r9aiM-0004pB-9D for ged-emacs-devel@m.gmane-mx.org; Sun, 03 Dec 2023 01:52:06 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r9ahO-0000E8-62; Sat, 02 Dec 2023 19:51:06 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r9ahK-0000Dh-7L for emacs-devel@gnu.org; Sat, 02 Dec 2023 19:51:02 -0500 Original-Received: from mail-oo1-xc2b.google.com ([2607:f8b0:4864:20::c2b]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1r9ahI-0003FS-C7 for emacs-devel@gnu.org; Sat, 02 Dec 2023 19:51:01 -0500 Original-Received: by mail-oo1-xc2b.google.com with SMTP id 006d021491bc7-58d08497aa1so2407877eaf.0 for ; Sat, 02 Dec 2023 16:50:59 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=rgrjr-com.20230601.gappssmtp.com; s=20230601; t=1701564659; x=1702169459; darn=gnu.org; h=references:in-reply-to:subject:cc:to:date:message-id :content-transfer-encoding:mime-version:from:from:to:cc:subject:date :message-id:reply-to; bh=BJxUaNg06uCUIdZyQN/eGC5ox5CNINs5+gjr/qQYfJ8=; b=sMttuoh7c/D1DpQZpdf95OhynQ1LjA24LZxZKRLR2Lll1FSFcgbjrCtDjTO7MG9my8 X2BVr71fzwzVfrknnwsh+5eHuTn6d93n/H9k+KhDPi04/4DBsH2ScNAMia4Vnr9ihotq H1URfe7X+VOBoBtrbHhE/mS5FokpONTDG+F2QwM9Sr76akTcXoWxcitaiI5MSGho/sTp bGBEUzFX6c3m8zzKqU42rZ9ajxdWLfb/aamvrRsxFV5BI8YP3lJz9umDXSJbYE7//lD6 xnhEpxw6x4ka2MBkLojZeZMESdPHEEjtjUdUbYcnde1V5oJh/oDLgkfvVHZscGU6+k0c vpDA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1701564659; x=1702169459; h=references:in-reply-to:subject:cc:to:date:message-id :content-transfer-encoding:mime-version:from:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=BJxUaNg06uCUIdZyQN/eGC5ox5CNINs5+gjr/qQYfJ8=; b=vVFtMJZ1b2T1AkZ2zBkx0OR9XG6jjngEkuph7UnhE2IZNXkdM5vjL0cEOZyOlqo7/v sacd1/01Kggx8cLdpGLnYXmPlsSi0osF4iUMiuS7/oSWyQ7Jnl1QCQzgNT7ddzBmEIt9 hAfDMlBEVcVg2eUyY5bQA0+OoZtKCNGQviysnIIfSCeacj495vRBAWd8fht7G1+okiNo cj4Eo5QgO3XH8NgtdEIXVgEMqzEkt7R/f5R6Wl2CzUT7Z3Unrry6M0MQfnvVmWtkPvM3 yZgY2tPjJntl95XaWeB3k/RUMg8vvXCfxngfMFk1Sl83jJCSaGwlPKS8uCBjI0HPy+h/ 9q2g== X-Gm-Message-State: AOJu0Yy0MFda6Cdjn9RLvyAoWu8qoP5ZYmOcp+OrzTVvzSxj7JSITEUW R+CEV+lo6dyM5CnSNFE14edlbA== X-Google-Smtp-Source: AGHT+IFgi0ea9j36+B9YWFFzXo3ChZ3kuo4x/5cwIZsEgm7feo1OWPqn+3ISfOwCigF6VLXDUm37Mg== X-Received: by 2002:a05:6358:90d:b0:16e:6185:cabc with SMTP id r13-20020a056358090d00b0016e6185cabcmr2646160rwi.27.1701564658508; Sat, 02 Dec 2023 16:50:58 -0800 (PST) Original-Received: from orion.rgrjr.com ([2600:1700:7c2c:e000::22]) by smtp.gmail.com with ESMTPSA id 5-20020a17090a1a4500b0027d05817fcdsm5855578pjl.0.2023.12.02.16.50.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 02 Dec 2023 16:50:57 -0800 (PST) In-Reply-To: X-Mailer: VM 8.2.0b under 30.0.50 (x86_64-pc-linux-gnu) Received-SPF: none client-ip=2607:f8b0:4864:20::c2b; envelope-from=rogers@rgrjr.com; helo=mail-oo1-xc2b.google.com X-Spam_score_int: -36 X-Spam_score: -3.7 X-Spam_bar: --- X-Spam_report: (-3.7 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, NICE_REPLY_A=-1.797, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_NONE=0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:313479 Archived-At: From: João Távora Date: Sat, 2 Dec 2023 21:54:17 +0000 On Sat, Dec 2, 2023 at 8:16 PM Bob Rogers 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