From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id kNOqLR1sYmNqPAEAbAwnHQ (envelope-from ) for ; Wed, 02 Nov 2022 14:09:49 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id IIKQLB1sYmOszgAAG6o9tA (envelope-from ) for ; Wed, 02 Nov 2022 14:09:49 +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 6CF3033C66 for ; Wed, 2 Nov 2022 14:09:49 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqDQY-0008Vw-IH; Wed, 02 Nov 2022 09:05:06 -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 1oqDQS-0008PN-5A for emacs-orgmode@gnu.org; Wed, 02 Nov 2022 09:05:03 -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 1oqDQL-0004Lz-2n for emacs-orgmode@gnu.org; Wed, 02 Nov 2022 09:04:59 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 18A35240104 for ; Wed, 2 Nov 2022 14:04:50 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1667394291; bh=JXXvFZXn+bbGWJJi/cg/84TVDWSvDP7NZB3ezaGZjVI=; h=From:To:Cc:Subject:Date:From; b=EgePU20pYUNzTq0xU1gi1vLaEZDUe/JtJt5cuTNnMdw28ModDW3soTDhdHMSwu1tO Tg7KSCnPZMdx/4F25Be3d7g3EsR9SHqEcjWR9aV8wLlxzMCCEsA/TCl2svrr5PE796 aEiYQG7GEPVn6w4PVEeZe0OquK92m5OILIiWywD6vaAVbYtPTSK2OXIbCbbW+vnLxy f8GZSf98fFPsd6dE4H/O45RFro/m2bOZHi4WvHG/dKIGGKU7Gmq47zfkG3JxoGT5VQ 2iDRX0YjBh3Y4iDm7pr/aR5wqPqgbaKu764PAZR0cNBzN3Swq7KgpVQHWOx2e5chKj D98a4JuOMsEFw== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4N2Rtj1tTtz9rxG; Wed, 2 Nov 2022 14:04:44 +0100 (CET) From: Ihor Radchenko To: Juan Manuel =?utf-8?Q?Mac=C3=ADas?= Cc: orgmode Subject: Re: Docstrings and literate programming (good practices?) In-Reply-To: <87leot1pyv.fsf@posteo.net> References: <87bkpqbwef.fsf@posteo.net> <87v8nxkewc.fsf@localhost> <87leot1pyv.fsf@posteo.net> Date: Wed, 02 Nov 2022 13:05:18 +0000 Message-ID: <87o7tp8q29.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@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=1667394589; 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=6lmhekjzL5i6i6D3xy8Vs+rz2QbTJl/tBRtgJFWl3Ws=; b=LWCZlWAxGe5CMEZFBUmLU4jqUfGQ2wk3KK73tNkJj+H82yhpgKksODMV2ZF0k0izw7a9v7 ywHfZCMjp/yZaeMmFSXB4DEKR/dMl9cfs7Peiry/CcJkxc2CVHUvsEdMRxR0nkzdlkauco ey9WBD/96+tykjcsOVQG4ci0C/F47dNPx6p5VdkScO25ppHb+oDuXqXlWoICzu+v95k9B5 1K1OwxhnjP6eydajhXJbOFEbJELnQ/0UNReEcyWwfNvCPqrZrHMR4rVuOcZE/XsQ6SFAgl j4Xm41wH9N5zRgJYqwkmM6hEf6Fx6SeRHYIoTEdXGvn8rmxkVmPNjOxFCMY3/g== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667394589; a=rsa-sha256; cv=none; b=rKOtdNUgkWmcAD8cgGKcrhTi+J7GIcxB7SOq/ugUQhS/hqM5KuHzWQU7eeWDv9GHuaXUg4 MDsdCu8MFVwz8/TH8FjAjjzItCM1Pbv4a4EF7Sx5AZehXXniz93DSleumqK18ur34aj56X luQ9I8IGeWK1uXOvMB1QoVA1E6Mc/qWpUSPcsgJ9zZ+OzooRduboFp1iyhQ4r8UDXx1mor j0TyKDnvPr8J99uFSESmIgEsp+ZZfloTocNTmdyJ0xkBALrKdwD34A3E7+V19vwoq+Ml7o iBMzi0tRmc+jrQUYvXlbh41ABk57F+nyioBkHbo+9qq/IqQRhL4TuEet1X9VkA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=EgePU20p; 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: -8.79 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=EgePU20p; 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: 6CF3033C66 X-Spam-Score: -8.79 X-Migadu-Scanner: scn0.migadu.com X-TUID: ZuC3SlsMzbmu Juan Manuel Mac=C3=ADas writes: > Ihor Radchenko writes: > >> Why do you need to strip docstring on export? > > 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 bl= ah. > > [the function code] > --- Can you elaborate about "paragraph is exported as verbatim"? > 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). I'd do something like the following: 1. Use normal Org text for docstring marked with some kind of block container (#+begin_docstring..#+end_docstring) or a dedicated headline. 2. Extend Org with some fancy links specific to docstring. That way, the original document can be read with active links to, say, other functions and variables. (I think Doom is using something like this for its new docs. Timothy is working on this) 3. Those links will be transformed to online documentation links on normal export. 4. For docstrings, on tangle, the links will be processed via `org-export-string-as' with a specialized backend that can escape what is needed for the target language docstring and transform Org links into whatever the docstring format is used for internal docstring references. 5. For docstrings, on export, the noweb will generate something like "[docstring is detailed in the text]", maybe even with a hyperlink to the docstring in text. Hope it makes sense.=20=20=20 --=20 Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at