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 iKg3C9ezZGOIFgEAbAwnHQ (envelope-from ) for ; Fri, 04 Nov 2022 07:40:23 +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 GBo2C9ezZGNWPwEAauVa8A (envelope-from ) for ; Fri, 04 Nov 2022 07:40:23 +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 E2A281937B for ; Fri, 4 Nov 2022 07:40:22 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqqMU-0001hV-IJ; Fri, 04 Nov 2022 02:39:31 -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 1oqqMO-0001h6-1j for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 02:39:25 -0400 Received: from mail.mojserwer.eu ([195.110.48.8]) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqqMK-0005BK-60 for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 02:39:23 -0400 Received: from localhost (localhost [127.0.0.1]) by mail.mojserwer.eu (Postfix) with ESMTP id B047C2271592; Fri, 4 Nov 2022 07:39:10 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at mail.mojserwer.eu Received: from mail.mojserwer.eu ([127.0.0.1]) by localhost (mail.mojserwer.eu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 2Lb6iLJNcS7M; Fri, 4 Nov 2022 07:39:07 +0100 (CET) Received: from localhost (178235147026.dynamic-3-poz-k-0-1-0.vectranet.pl [178.235.147.26]) by mail.mojserwer.eu (Postfix) with ESMTPSA id ADFCF2271587; Fri, 4 Nov 2022 07:39:07 +0100 (CET) References: <87bkpqbwef.fsf@posteo.net> User-agent: mu4e 1.1.0; emacs 29.0.50 From: Marcin Borkowski To: tomas@tuxteam.de Cc: emacs-orgmode@gnu.org Subject: Re: Docstrings and literate programming (good practices?) In-reply-to: Date: Fri, 04 Nov 2022 07:39:04 +0100 Message-ID: <87mt976x6f.fsf@mbork.pl> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=195.110.48.8; envelope-from=mbork@mbork.pl; helo=mail.mojserwer.eu X-Spam_score_int: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H3=0.001, RCVD_IN_MSPIKE_WL=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=1667544022; 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; bh=0SruleDBUgvDFR/xt0PNeCIfEa5snzfX9mZMNeBPlPY=; b=TvXa933XCs86RLlWRlhovZ82nzkdBevncBqtglFNiiFxI+yxdQqmN6iIkaerUS/yZKFZVv LQ4W01LqYFKQ4KibDe5mvtHvJfVxBKxAijmJLBC+OvYRgGWeUXRwvHlpgoPJnvndvHgWZk KF+34QXnFGYxFz0EwqTy5BneyAEQdbsPojZ/zfeovy6XnX+nyuioXdmhdp59UDjZY+SZ2N llQeUIpB4x/aEhGikJgfTBTjo8BoCXuQo+zHv1I/BO85OX8HLcuveYSDdtHkByTQ3JDngy Lfs1yIiAJIwScO2FMkia7Fj8eI626Nuo9DpSjXsakSB4+55OnJpTfq5D/zMlcQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667544022; a=rsa-sha256; cv=none; b=OHZX311MSpKLs/Ih8awFej9uYAa+1r9U64CZeAQQ5rbw5mTLXism3ARuUqPXnJX7BOk2pb 8CgPaQNZf1npnE/Xj7IwphlWTp0/wvNkISsJ1yH8rtMnon3QdTUlD3th4CrleTyIt/Eocx WA9YWBiBVbKN5Ok5yKZNkWWda0mA8pWGVDh2PzfqEkBHf5hEPlwYSKmhocEx2l69OpJ1Ut /qaTkWo8ZHnlHPG54wiT3vHirpgofquaF/OZHXOSylVttObm6/vVX6R1NWfWFNdpbh0Nv1 4EdoepAlAkU0n8Z37Nzw8X/OZwTGItCDV2Z0hmsFuAllpYZFYobXsoIWqBTMxA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; 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: -3.80 Authentication-Results: aspmx1.migadu.com; dkim=none; 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: E2A281937B X-Spam-Score: -3.80 X-Migadu-Scanner: scn0.migadu.com X-TUID: qJyf1jtnvkdu On 2022-11-04, at 06:45, tomas@tuxteam.de wrote: > On Thu, Nov 03, 2022 at 08:03:05PM -0700, Samuel Wales wrote: >> i wonder if emacs or org has what you might call semi-literate or >> etaretil docstring functions? >>=20 >> 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. >>=20 >> why not include the docstrings of all commands in some nice format in >> the .org manual via some mechanism? > > Ah. Javadoc and their descendants. I tend to call that "illiterate > programming"... I spat my tea. :-) Thanks, that's a nice one! Though this _may_ work in some cases. For example, imagine you divide your package into two files =E2=80=93 one with user-facing commands and ano= ther one with internal functions. If you order the former one carefully, the "extract docstrings" might actually work as a documentation. Still, a "normal" documentation seems a better (even if more time-consuming) options. Also, such docstring-based documentation is still better than none. Best, --=20 Marcin Borkowski http://mbork.pl