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 mNM7Jv+KYmMFbgEAbAwnHQ (envelope-from ) for ; Wed, 02 Nov 2022 16:21:35 +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 4EwXJf+KYmOPHwAAG6o9tA (envelope-from ) for ; Wed, 02 Nov 2022 16:21:35 +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 423B23A788 for ; Wed, 2 Nov 2022 16:21:35 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqFXk-0007kI-Gj; Wed, 02 Nov 2022 11:20:40 -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 1oqFXi-0007jU-WB for emacs-orgmode@gnu.org; Wed, 02 Nov 2022 11:20:39 -0400 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqFXe-0005Qs-Hb for emacs-orgmode@gnu.org; Wed, 02 Nov 2022 11:20:38 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 34E08240029 for ; Wed, 2 Nov 2022 16:20:33 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1667402433; bh=pViWq2BQvz+jq74D00FCoIDXTTvLqkn7CBRY918pS04=; h=From:To:Cc:Subject:Date:From; b=HxiXIz1PXktNqNRNekJQQMIlhAq8/EcF+lnx7QmNQD+1sgGPbGn111+nTbd/RaDvT 1bxH3VyV+HTh0yvPT011J19u1nFzjb4K3U2jBT2c3esNruFZzP5hg96mzIju9uBtK3 c85yPQ2dcbVck1xoR0+IkvbyLafU5pC4eiEWGr4vwQCs+icJjtFrFEskL72TpxLt1k 96cMg00wPpglH6Fhv/Fo16eaFU/UjVN/x0jIAn4sZfgdd2m/lZ09SxlDLt9someUEp rhVA9EUhU0HWLBDtX5FkJEWKcu8l+zQ6OborlVymXkW1sG44Iqd8zyqq1JvFnEzuK7 QTQCBtUFv2HmQ== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4N2VvN53fFz9rxD; Wed, 2 Nov 2022 16:20:32 +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> <87leot1pyv.fsf@posteo.net> <87o7tp8q29.fsf@localhost> Date: Wed, 02 Nov 2022 15:20:30 +0000 In-Reply-To: <87o7tp8q29.fsf@localhost> (Ihor Radchenko's message of "Wed, 02 Nov 2022 13:05:18 +0000") Message-ID: <87bkpp1iyp.fsf@posteo.net> MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=185.67.36.65; envelope-from=maciaschain@posteo.net; helo=mout01.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, 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=1667402495; 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=9UGrbqwFqW3GSspbJYTnclVoQfleSuoEShogcOAw6Rs=; b=Y1aPZIob3BK5VmgnLF2KMwTwg4KIs3QXOKWTxki6V+aHhtT/QMsUBAHW4uyQMvaKuKzWAz w9C5WyXIIpEKQNHx1elRDinLkcGTJJk9w7B14IcCLagIMQaUzjrLs9x7TwzOspM/8sx/x8 Ro19aJyTm8voBIrZoqR3HEN3G8meKRS59vIPoEWdkHoRcoc+WaY2HAGA6ttpdQMVy0CVqL fcOjc9WWVtkfcYjsoOGe+nTtrFvGyBW05vfG+wcJWCPpCaEbHpWvhv5NGkA2gW2y3M+RWX fbHJG7jqJjO/TfkHKyEnCqz9TlTI3mGG5CYpdL26W7tnvNH6WR9hBFj3/hNKMg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667402495; a=rsa-sha256; cv=none; b=Isbi8QWXOvIJY8AMloTu95C2/MKdUJxa1wH8My4CHmExJkymiMpmjRL7OtYvoZyB5cxyHW 9mhNdUNw61fXbkm/BZSthbwVQsHOk2+TH5hlx4W9jdgj/8PS28O32jaj6V3r6+fASovbT1 3CfSuW4x6ELVrga16bb5UfJZgcNHZbKODgOMyME8togt9vH+t2amb8ClnpT4FePBoUnshK or/XvS+eWJJ0bOzKU8vl/abE3y0OQ0hSPLzq41LmfSu3d4S6OmNLcSPLZ2d8OvA8zth7xc 0Kmpv6ILZSdk3JWfB5BjPGt/xBV0Din4oHuvsEdAXFoJWcvz6sKBTodvYjDYBA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=HxiXIz1P; 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: -3.99 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=HxiXIz1P; 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: 423B23A788 X-Spam-Score: -3.99 X-Migadu-Scanner: scn0.migadu.com X-TUID: NV/Y3F1ZXpRO Ihor Radchenko writes: > Can you elaborate about "paragraph is exported as verbatim"? Sorry for the conciseness in my previous explanation. I meant something like this: : foo is exported to LaTeX as \begin{verbatim} foo \end{verbatim} (and what i want is for it to be exported as 'normal text'). >> 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. I like the idea, because of the possibility of being able to use links. That would also be respectful of the docstring as a legitimate part of the code (in my approach, removing the docstring during export leaves an empty line in the code, which is weird). Anyway, I think that with my approach using org blocks and noweb references, links can also be used, although more at a user/home-made level, with some export filter, I suppose, that would convert the noweb reference into a normal link. By the way, thinking about it, I don't know if a hypothetical header arg called :docstring would be ok, something like: #+NAME: foo #+begin_ blah #+end_ #+begin_src emacs-lisp :docstring foo (defun foo () (message "hello world")) #+end_src And the docstring would be formatted and placed depending on the language and the code (https://en.wikipedia.org/wiki/Docstring). I don't know if something like this would make sense; although, thinking about it, I like your idea of using special links better because it is more versatile and (I guess) simpler to implement. Best regards, Juan Manuel