From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.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 wDFlIZtrYmOVcwEAbAwnHQ (envelope-from ) for ; Wed, 02 Nov 2022 14:07:39 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id 2IdWIZtrYmPAagEA9RJhRA (envelope-from ) for ; Wed, 02 Nov 2022 14:07:39 +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 1ED112F68A for ; Wed, 2 Nov 2022 14:07:38 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqDBX-0006V0-Pi; Wed, 02 Nov 2022 08:49:35 -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 1oqDBI-0006Tn-P2 for emacs-orgmode@gnu.org; Wed, 02 Nov 2022 08:49:29 -0400 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqDBG-0004pq-Sr for emacs-orgmode@gnu.org; Wed, 02 Nov 2022 08:49:20 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 76BBC240104 for ; Wed, 2 Nov 2022 13:49:16 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1667393356; bh=9LTNEmwJsgUASjqyExF+j3aIo3mjePB4ZkGcZSP3qZ8=; h=From:To:Cc:Subject:Date:From; b=hR/dTI8zIewoVk8lkpVYzZLjX5igMa1eK1I1zJ2aWaAMnAQVlfFvZ9U45u3PIVnDN KRosH9rVkN4hXT3MpbUshtlMYcvX2zkcmCOzhgAy4gE/BKta3bk6vxk4TlYea5uHI7 GHysY4MDGz4OOyZWQzO5imwYPoX6fRTE8waQrjW1avLXiyA2dm2a5gemK+mTQwWTJz LcG6X8o56NLuwOR72DcUkLMWtzIn9WpkM/zOH0Q6CYyDpLBG7x0MdLVJS4eoUGuSa3 vaX5Vrrym1x/Rsz+rbKC/AoeMXdwT+anVPQT//oFG1A4BHmhj4h/mNKQW4hqUiVFut 9vbFJDcruo0Ug== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4N2RXq4W72z6tn4; Wed, 2 Nov 2022 13:49:14 +0100 (CET) From: =?utf-8?Q?Juan_Manuel_Mac=C3=ADas?= To: Ihor Radchenko Cc: orgmode Subject: Re: Docstrings and literate programming (good practices?) References: <87bkpqbwef.fsf@posteo.net> <87v8nxkewc.fsf@localhost> Date: Wed, 02 Nov 2022 12:49:12 +0000 In-Reply-To: <87v8nxkewc.fsf@localhost> (Ihor Radchenko's message of "Wed, 02 Nov 2022 07:13:23 +0000") Message-ID: <87leot1pyv.fsf@posteo.net> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=185.67.36.66; envelope-from=maciaschain@posteo.net; helo=mout02.posteo.de 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, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, 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=1667394459; 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:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=tdHObHWKgsLhy/oq0oPlnBCwPEvg2/Sh9zFqA/xxHPU=; b=bstNh3Q05b20PlAq3g+4qkOU2SRQ3IDThJ661zM9/fwdyOtwmpj36Uq6LfXxT9IG+i1dlW 59+u+inv/zTfrDb+CF2PFwQoy4OIxrTcxa94vW6wXiWR6r593YblJWC1gJYjdE+JLMZVir 0MAXm2cDGd7JOEKjhGpPiHJ+MdP9Qx1W0TfHjQWo4DzAhiJZVXSh2lyERbbxQU6V6SrA3z AdreZzDoTpwEL5BL0rre9I+72z7HRIsaCmRlC68B7q0LfxfTYe4hZjNdvzGZkR8BeWBoux jX3ThsISfZswTyNVJPcCBNwUee0iHksReF+gMc6c/awo6eJstQN1wP7HF4Xmnw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667394459; a=rsa-sha256; cv=none; b=tJqHCiBYFOvV9JLgzPoJf8pAhvHUwALzKOHfazg7ytkgtYP/6DFxfUIbGr7ZR9/09acqvo EIpH1ilQ/bm3cgi2jfZGMCSo9rIlkOjw8rz0zL6tDelWxMipbp9E48EZhiqqtvyss147CD gEaKjSgIldobVKzRA6+NxH27pnUZgYaeHWYzBR/PHA78HU7G293YpPebRBmRgvZTo4oqYq JfaNB7en7SGQ0ajA21lIIWEy2cyu+geDbvXyNg9s7DAYphU8MHnuUD+uWNNly3vCtYcMa3 hDZb2nW4pdeMqNRziSHAS7Nf8ay+Wz1vL04Y1eP3fD3/wKRfIXeDTGLh8+87mg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b="hR/dTI8z"; dmarc=pass (policy=none) header.from=posteo.net; 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.29 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b="hR/dTI8z"; dmarc=pass (policy=none) header.from=posteo.net; 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: 1ED112F68A X-Spam-Score: -9.29 X-Migadu-Scanner: scn0.migadu.com X-TUID: C8P/fsgotxEn Ihor Radchenko writes: > Why do you need to strip docstring on export? Hi Ihor, Thanks for the suggestion. The problem with doing it this way is that the paragraph is exported as verbatim, and I want it to be exported as a normal part of the text. For example, in a PDF or HTML it would say something like: --- This awesome function is for blah blah, and makes blah blah, when blah blah. [the function code] --- But in the source file, that text would be a docstring, inside the function code. Actually I don't know if it's good practice to do it like this, hence my doubts about how to 'marry' the literate programming concept with languages that support docstring, which, somehow, are largely self-documenting (thanks to the existence of the docstring itself) . The scenario would rather be in long, multi-paragraph docstrings. Then this dilemma comes to me: if I am doing literate programming and I want to explain in detail what the function x does, I write it in the main text as part of the documentation. But also that explanation should be a docstring, in the source file. I understand that the docstring would not appear in the PDF (to avoid redundancy), but I don't know if it would be a good practice either, since the docstring belongs to the code... In short, my dilemma is: how to do good literate programming with a language like Elisp, which is almost self-documenting in its code? (So one can learn a lot about Elisp just by reading the code in the *.el files, without going to the documentation (which is a great strength of Elisp, by the way). Best regards, Juan Manuel