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 kIx5CieBZGNd2gAAbAwnHQ (envelope-from ) for ; Fri, 04 Nov 2022 04:04:07 +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 ABV8CieBZGOuDAEAauVa8A (envelope-from ) for ; Fri, 04 Nov 2022 04:04:07 +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 E728DD628 for ; Fri, 4 Nov 2022 04:04:06 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqmzG-0000Oa-PJ; Thu, 03 Nov 2022 23:03:19 -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 1oqmzA-00088w-6z for emacs-orgmode@gnu.org; Thu, 03 Nov 2022 23:03:13 -0400 Received: from mail-lf1-x129.google.com ([2a00:1450:4864:20::129]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oqmz8-0001pa-9A for emacs-orgmode@gnu.org; Thu, 03 Nov 2022 23:03:11 -0400 Received: by mail-lf1-x129.google.com with SMTP id f37so5724110lfv.8 for ; Thu, 03 Nov 2022 20:03:09 -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=XYcvRdZt/CBberw3v9CYIYSk+8tI0WxGdC0L16Dx0KI=; b=TxFxD4lUVf03DOiuyQTgpL1mKZ7PVI+MPL3QOUJaGsQ9PJ8m4wysh+yGpGU4YhrMY6 r55YcNmDDXxHpKh8LKXaTTkZRwKkeGv3SES68PU91gIwxa4UH+xajNMHxfAWv/0bBkD+ nv683spXMdOiwE4y2XT22yU0M0QzNzF3EeAKPzFwPQ54sl8EVgcT+iOm3sw1KwSm3NIN So4ly7fsTsF6T2JQht3gPz+2bUZ6zVWRyZiZ4IxLQXPu43AEbsgiF9yJtqo63YX2hkbU PNIvJAMwUxUoH+cPSSPc3L7lASBWlnv5HeBRpx6fgZCZULhBNO4jqKxWh8YxwTWxdlCv 3zgg== 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=XYcvRdZt/CBberw3v9CYIYSk+8tI0WxGdC0L16Dx0KI=; b=REtJSj4NzC1/blLWvD5VYc0w6eV//VvWSfyUXwWB+srVyusalcXc0yckenK+2rt5mg yjuJoENbAZpfTxZl3Mu9ySJCRa4U+hDouHiL8XZIACgReFoo90UhvqJ1j86gPmIzxD6j OxDeIhDWYuSGS78jzKe/Z5a2cIdncU02k+gfR42I82BuVk+uS9xOAqvHSJp12VM/N6xc SsZgcB30mf1XUJRfWJH/GDeA9A7/FneA6zou4BjE0VQ/oYjwEs69S/prPyqe4nuY+mQi UsrtXZsEGO03DuYni46HFcVTcpXFmDU4fsbiYXhXdiNKyxhuxA7YoeK5qO1ZvUb8j34X KQ3w== X-Gm-Message-State: ACrzQf0gvedReeZ6cMx7AtpzEffQT5jjZbLcK5QfmSBGIgrHLS1clmYu 0OT3bzC5SOA9RTIx8cj5B+/vGPBngm8W96aAGhs= X-Google-Smtp-Source: AMsMyM5WcGORB2MpwrP8F4/AsH3dUfbB/V0aQamZnzzO6QkgXbAY8+m7UB8g+z6fkmm1h69acXhcCzXMDp2/9m9mKrQ= X-Received: by 2002:a05:6512:3b99:b0:4a2:6151:84fb with SMTP id g25-20020a0565123b9900b004a2615184fbmr14316644lfv.613.1667530987173; Thu, 03 Nov 2022 20:03:07 -0700 (PDT) MIME-Version: 1.0 Received: by 2002:a05:6520:4af1:b0:22a:e96a:7f9b with HTTP; Thu, 3 Nov 2022 20:03:05 -0700 (PDT) In-Reply-To: References: <87bkpqbwef.fsf@posteo.net> From: Samuel Wales Date: Thu, 3 Nov 2022 20:03:05 -0700 Message-ID: Subject: Re: Docstrings and literate programming (good practices?) To: =?UTF-8?Q?Rudolf_Adamkovi=C4=8D?= Cc: =?UTF-8?Q?Juan_Manuel_Mac=C3=ADas?= , orgmode Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2a00:1450:4864:20::129; envelope-from=samologist@gmail.com; helo=mail-lf1-x129.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=1667531046; 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=XYcvRdZt/CBberw3v9CYIYSk+8tI0WxGdC0L16Dx0KI=; b=pgQEiff9/P5RHtr3KT0ScC5EkYcv4L1oYm4QqHNKOHNg80Qosepy+es0FnTU7BXjPYTV4+ k3QEq40ADOJc5tdCqAH4x62oAClFS8hk1dEKwPt6T6WN7o9eBtF082HmlXh3UiOwTuqU0J B8GgfxU5PDFCxtsZsjIWjMfW0YzpVYSoZoDUOUjNbevUjiJ3tUK4Z1wIOEXCStTt7V9FD1 BnwZwBrugazv0AzaDpFWHRhPD5E+qFCUBmhuP20BZuk0YvwZm6iX7U7RZY1Eog4K9Bb7Fn s48a/0XMIJwYwico2s7ECKNCklfVNg0Ds8NQOP8Ha9IlaVP/eReCEGCMCVamZQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667531046; a=rsa-sha256; cv=none; b=Cm+EruMrRHdysXR7BMQhkU8SAqSaJog1FJE2mdONwY0qIM+Lt3VGfxe/HgcHaL6EdfaIGX SKt59Ym0yWbADjlM7Ca1Q37U1STTYs8D1OH7fRo7BPzQVMYyxSpdc3KDiFtWf7DTkNPiDj aEUfjfOIauXT9ogeyyrxKg9GW3fufwKlkzpg1GqzVzgu3PYMHlbT4zl7dr04LEjgimLIhG OuUIMGHTZir4dTa9YgBCTcKeqF5ZCaVCMznxKgGTloIljOclp2lIe2r3U8SDBoowiMllsl QA9V43v7R7Kwp9VjPgFOo5WxM5C60PD4hScej2hk2PNGa6ClHSDCo1u27KbpiA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=TxFxD4lU; 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: -4.00 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=TxFxD4lU; 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: E728DD628 X-Spam-Score: -4.00 X-Migadu-Scanner: scn1.migadu.com X-TUID: lAMFla87uImv 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? would that be a good practice? seems useful abstractly. On 11/3/22, Rudolf Adamkovi=C4=8D wrote: > Juan Manuel Mac=C3=ADas writes: > > Hello Juan! > >> I can duplicate the text, but it seems to be a bit redundant, right? >> So what is the best way to proceed when doing literate programming >> with any language that supports docstrings? Apologies in advance if >> the question is a bit silly, but I'm not a professional programmer and >> don't have an academic background in it, so I don't know if there is >> any good practice on these things :-) > > A "bit silly" question? I find your question rather profound. Thank > you for bringing it up! > > Personally, I recommend to use both docstrings and literate programming > idiomatically, not mixing them. > > Literate programming exposes thinking and exploration. > > For example, the literate portion can show different approaches you > tried but abandoned, something that does not belong to the function > itself, nor in its docstring. Or, it can include examples, piece-wise > performance analysis, computer science background, mathematical model, > citations of prior work, and so on. Add some assertions and you will > have literate tests as well. > > A docstring describes the function from the outside, as a black box, and > if you did a good job with it, it makes it simpler for the consumer to > use your function. > > Literate programming, on the other hand, goes deeper. It describes the > thinking that went into the function, comfortably exposing its insides > and opening the black box of its abstraction. > > Rudy > -- > "Strange as it may sound, the power of mathematics rests on its evasion > of all unnecessary thought and on its wonderful saving of mental > operations." > -- Ernst Mach, 1838-1916 > > Rudolf Adamkovi=C4=8D [he/him] > Studenohorsk=C3=A1 25 > 84103 Bratislava > Slovakia > > --=20 The Kafka Pandemic A blog about science, health, human rights, and misopathy: https://thekafkapandemic.blogspot.com