From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.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 UI3xA/3IZGMiywAAbAwnHQ (envelope-from ) for ; Fri, 04 Nov 2022 09:10:37 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id UBsEBP3IZGM4JAAA9RJhRA (envelope-from ) for ; Fri, 04 Nov 2022 09:10:37 +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 C6BF73E0F5 for ; Fri, 4 Nov 2022 09:10:36 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqrl2-0005zT-8Z; Fri, 04 Nov 2022 04:08:56 -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 1oqrl0-0005wL-Cj for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 04:08:54 -0400 Received: from mail.tuxteam.de ([5.199.139.25]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqrky-0008ME-Vx for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 04:08:54 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tuxteam.de; s=mail; h=In-Reply-To:Content-Type:MIME-Version:References:Message-ID:Subject :Cc:To:From:Date:Sender:Reply-To:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=+cSg9m+s8+O3L/2i6bqlwandzXtuACLYc5KJSJ9M8HA=; b=XLjTM6sf3g4++XkTWese9OqgdD UlRR4/rGV13zfsdq44WkuVeGOyKjfrKebDeXrhVqsKuUjLhJx+7K/IuffD+oldHHSogZAZTKByAW9 f6A7NaFj5D9QqSO1OXkJlwlguggqI/3Y1B6w3ckD+DHJxex09K9tUq1/vOnBtgw9xA+/AFK0EuONT rMy8yQXqHYkhgV6PxmHFquAkmNxyLUi2I274HQKviHpuV9Ut528ncmGgsC1/GR1HHyYtgLSzQgHL8 Z2tEQYsnHb87Io04nLMlNvAaB54oadU8mYVquRdMnCb+i8ImbDZCQyzrXHljAXmR0d+E8sc0tsPy4 K6AfUgpg==; Received: from tomas by mail.tuxteam.de with local (Exim 4.94.2) (envelope-from ) id 1oqrks-0003S4-8x; Fri, 04 Nov 2022 09:08:46 +0100 Date: Fri, 4 Nov 2022 09:08:46 +0100 From: tomas@tuxteam.de To: Samuel Wales Cc: Marcin Borkowski , emacs-orgmode@gnu.org Subject: Re: Docstrings and literate programming (good practices?) Message-ID: References: <87bkpqbwef.fsf@posteo.net> <87mt976x6f.fsf@mbork.pl> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="2BIrSZdvpHD3R8A2" Content-Disposition: inline In-Reply-To: Received-SPF: pass client-ip=5.199.139.25; envelope-from=tomas@tuxteam.de; helo=mail.tuxteam.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, 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=1667549436; 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=+cSg9m+s8+O3L/2i6bqlwandzXtuACLYc5KJSJ9M8HA=; b=WD8S07KgYo7Lq8gGUJH0rNnHaUbLHyWQqQr2GGat93VYYXJOtujWYjBQyGzEIJtdbEE50n aKgYlnboARsB0l1onkMfNacv+X5IODzRq9cNn7VprjhOY5op4DSdCvCaDA6c7c4MT7IQoo Ym7CqOEsRNV4cJoBil5+urZHWWqwJItobEaTSCkFJRGrVWpyUn50uczYbHkom1mt+jus8R K+ms/OtS48lSFlx/wroAF6ftBcftovQ1i8fZEQnSTU1y0j+CHbxQZPjhfa8b9QCRbC8HKs vu0Och9De0O7ZI7PgC6AkiYazQTIGMx1U2bmSu6EWzCOdtPiaS6G7xx0+KO3fg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667549436; a=rsa-sha256; cv=none; b=U9pN5GBKGAFbVtLVT+pTr6IoCbd421mGjFh8y57YZcrA/tU+hEpoPSlws445fimkzXgZAt t2pAeFLEtCnQwfUQmFXhpojy9ZSZyN05Kb4mIIW05kAT2OSa1HL9ew1S7V6F4TaZqF0W+8 SlT/0sst4ctizrPyz3IURVUQdq3VjJtoxJxjX3MXZ1fvpmwVJMCf4JaAliFjRfm+yHfygK NpL7f6Ja+bsaSfgcs/zVMvoT+oYwIo0MPuWHnT3mltIfq1WGy2+9yJyKsNgC/NtZAipXrv s2rcdfdA7+VSlnsioZI1CWC1wZvZflK/e1oCe/kz4lxIo9729xA376pgyK47vQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=tuxteam.de header.s=mail header.b=XLjTM6sf; dmarc=none; 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: -1.40 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=tuxteam.de header.s=mail header.b=XLjTM6sf; dmarc=none; 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: C6BF73E0F5 X-Spam-Score: -1.40 X-Migadu-Scanner: scn0.migadu.com X-TUID: Br1qVo8poKJT --2BIrSZdvpHD3R8A2 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Nov 04, 2022 at 12:13:30AM -0700, Samuel Wales wrote: > 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. Absolutely. I can well imagine docstrings going into a reference. > but surely an extractor could look for an interactive spec and things > like htat could subset the functions and text. My complaints were not so much about the extractors themselves as about the kind of docs that tend to be made with them. Cheers --=20 t --2BIrSZdvpHD3R8A2 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iF0EABECAB0WIQRp53liolZD6iXhAoIFyCz1etHaRgUCY2TIjgAKCRAFyCz1etHa Rv9qAJ0Q69RpEO1VZhrySXK8QW4VVAhsBgCcDrvQvhg2T9eYKPUalVqJxZEWRrE= =GSwz -----END PGP SIGNATURE----- --2BIrSZdvpHD3R8A2--