From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id EYHbFaDBZGMeUAAAbAwnHQ (envelope-from ) for ; Fri, 04 Nov 2022 08:39:12 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id eGDCFKDBZGPHowAAauVa8A (envelope-from ) for ; Fri, 04 Nov 2022 08:39:12 +0100 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id E047D1A948 for ; Fri, 4 Nov 2022 08:39:11 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqrEo-00087n-0V; Fri, 04 Nov 2022 03:35:38 -0400 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 1oqqtY-0006Kl-OR for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 03:13:42 -0400 Received: from mail-lj1-x233.google.com ([2a00:1450:4864:20::233]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oqqtS-0000tG-D0 for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 03:13:38 -0400 Received: by mail-lj1-x233.google.com with SMTP id a15so5111257ljb.7 for ; Fri, 04 Nov 2022 00:13:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:cc:to:subject:message-id:date:from :references:in-reply-to:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=POBegb8Gq9Svl/i73238gS8VPKaJAE5KYK/Yyt8b9+k=; b=RJiHfOPG4ictG5+LchjU23zpZ1loItYubULq23OfN17n9fMNzG7Qa8G3CLuT51IBNy gKnnjN3q37MnsTxARv6I5pxDTdFphX7gkCn9zFW9u1rsNwaRJoACCklKHHAAPmKrNRPL kNlZ5hpoZE19xBFKcsUl9s9OaEmUJJvKuz+U9m4Miw7YmS1d14GY/hGHdIF7a2PtXHgR rbuUyuSm3YzWfeuA6V26qGHDvxokSC95hTpg6qORMhDk6RN4HgYEqfBzTfDcxIiw5VBP iKk8qvNZ4dXrkR7N8eh0fJHMgLIbVgXUgyQHorwkBVqHYTfOdtkdbKlBYdHa3B3c4eE7 uaqw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:cc:to:subject:message-id:date:from :references:in-reply-to:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=POBegb8Gq9Svl/i73238gS8VPKaJAE5KYK/Yyt8b9+k=; b=KswJXAba9HA2mNEZ7S9HQmG6AoR3nklq8sfEONbsu21ky5j2oCh8iVo0oud75GpnVY hlBzO5DOeAMpVLCJPSetYD3xdFOk9TkfANtZu/Uft80ieRNSc2pROUMzIfQ9emk0Tp1a uhj3RQCRDSMEb+fh+0+vMkGmpyHahIQHhTSxQAqeJfkEXBuhK2ZJD5rX5JqWx+lnNNUJ D/rAKMrGjzL7S3P0AbokG07yBJ/nf7ff6ILgV/2elE+AiKTgQcYjwYS/eGLLbphaNtte w0lGgcjtHy3H3U3vb9o6YNP2YnRgO3ib4uqTNoXGNMBq1RVJr6ModwK3l1FBpQQyNHwI mVvw== X-Gm-Message-State: ACrzQf346y1ECwfvdfmcfVFqnm5+m8U0/2xVATq2Twd5d2yZi5ahu1AQ Q4c5w9KV3vLllkLCpk31bRCNe4dCUtKoWebdGF4= X-Google-Smtp-Source: AMsMyM7XqBxvnGQIymBDWIcJtTasxAvg/S8qZK6HiwZxIe3wkHf+oykpTJAnyGtiAIwnkGSv2iD2oaP0xENhSegwJMo= X-Received: by 2002:a05:651c:2226:b0:277:4818:a1ca with SMTP id y38-20020a05651c222600b002774818a1camr1739151ljq.361.1667546012071; Fri, 04 Nov 2022 00:13:32 -0700 (PDT) MIME-Version: 1.0 Received: by 2002:a05:6520:4af1:b0:22a:e96a:7f9b with HTTP; Fri, 4 Nov 2022 00:13:30 -0700 (PDT) In-Reply-To: <87mt976x6f.fsf@mbork.pl> References: <87bkpqbwef.fsf@posteo.net> <87mt976x6f.fsf@mbork.pl> From: Samuel Wales Date: Fri, 4 Nov 2022 00:13:30 -0700 Message-ID: Subject: Re: Docstrings and literate programming (good practices?) To: Marcin Borkowski Cc: tomas@tuxteam.de, emacs-orgmode@gnu.org Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2a00:1450:4864:20::233; envelope-from=samologist@gmail.com; helo=mail-lj1-x233.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "Emacs-orgmode" Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1667547552; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=POBegb8Gq9Svl/i73238gS8VPKaJAE5KYK/Yyt8b9+k=; b=b2QSWshbHa0WMVbAsOjCcz855KMA27xwYkeUWH+8rF/0fPGZYLWKQPJLPoaLNbeHlQ1jDU FT5OnridXNVhxyqZ53RCAetZJ6HoVncjJMGgqMOyHChrXmps41mLzjUsDOEi2z8kp4K2HK Z86hWsA2ydQ+o9sPhdJhCSk96aPvd5pbu9NUBioBPOIRzjtatcHnya5VDOMTWVSeE4rBrw PxnSCg7ts9X/tBu7eMssFhJppXOX4/aiYTMO/0LV9ZuHxjB9WleUGFcyhURSdEyiW0U7dj mX+3O1sJ3+vEbCYlSCRhJdQd6NvP4/U+BB/m2xJgfH2wVGVHmVIABrJKnaPA6w== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667547552; a=rsa-sha256; cv=none; b=iN+7o6gTai0zwz3x2HroqmvrkiEskm81M8l4J9/dLOlmvMyZPLzg0XpscdyxHrD99AvFJO fvXuE5Gp6t+E3ymlmpI0DcIWKn6FTry5If9Zd6uE6yVD+5fQjC+3ZlCSC4jTWUFk3DePTR 5vKjZRSOUzQSbz7MHk/Mtl/0217GcYpQo6wBFmM9jJ4Q8ZVFS8DAaqcaMT1YdTtFHXL21K gWj0aCsBZzPDew5CklgnWUK5x7MFtIK4RfrbKS61cK9fvUpZCqsKsFLCDpw1vkvmUdban1 4nm2e1kIwCDYzWDkEjU2rykTN40mCvDnC0sipozUrqPOQ/BHuqM0jWVdRy4I7w== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=RJiHfOPG; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -9.00 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=RJiHfOPG; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: E047D1A948 X-Spam-Score: -9.00 X-Migadu-Scanner: scn0.migadu.com X-TUID: gLAdZgyzrPq7 my dry sensibilities say don't write ht same thing in the manual that is well written in the docstring. idk the issues however, other than that once you do it in two places murphy's law says they will get out of sync. but surely an extractor could look for an interactive spec and things like htat could subset the functions and text. On 11/3/22, Marcin Borkowski wrote: > > On 2022-11-04, at 06:45, tomas@tuxteam.de wrote: > >> On Thu, Nov 03, 2022 at 08:03:05PM -0700, Samuel Wales wrote: >>> i wonder if emacs or org has what you might call semi-literate or >>> etaretil docstring functions? >>> >>> for example, you have a body of non-literate elisp code, and you have >>> a manual. it could be redundant to describe commands and what they do >>> and their options, if the docstrings are good. >>> >>> why not include the docstrings of all commands in some nice format in >>> the .org manual via some mechanism? >> >> Ah. Javadoc and their descendants. I tend to call that "illiterate >> programming"... > > I spat my tea. :-) Thanks, that's a nice one! > > Though this _may_ work in some cases. For example, imagine you divide > your package into two files =E2=80=93 one with user-facing commands and a= nother > one with internal functions. If you order the former one carefully, the > "extract docstrings" might actually work as a documentation. > > Still, a "normal" documentation seems a better (even if more > time-consuming) options. > > Also, such docstring-based documentation is still better than none. > > Best, > > -- > Marcin Borkowski > http://mbork.pl > > --=20 The Kafka Pandemic A blog about science, health, human rights, and misopathy: https://thekafkapandemic.blogspot.com