From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id yL5RO8zWaWNh5AAAbAwnHQ (envelope-from ) for ; Tue, 08 Nov 2022 05:10:53 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id KM1SOszWaWOhDwAAG6o9tA (envelope-from ) for ; Tue, 08 Nov 2022 05:10:52 +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 991147C74 for ; Tue, 8 Nov 2022 05:10:52 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1osFwD-0006Re-5d; Mon, 07 Nov 2022 23:10:13 -0500 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 1osFwB-0006Nb-4H for emacs-orgmode@gnu.org; Mon, 07 Nov 2022 23:10:11 -0500 Received: from mail-lj1-x231.google.com ([2a00:1450:4864:20::231]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1osFw8-0000sE-I7 for emacs-orgmode@gnu.org; Mon, 07 Nov 2022 23:10:10 -0500 Received: by mail-lj1-x231.google.com with SMTP id d20so19268935ljc.12 for ; Mon, 07 Nov 2022 20:10:07 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:from:references:in-reply-to :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=Yl/Y1Uvo87E/VK8CbpEjgaisVScKBXe8Eorm+r2YrXM=; b=eWQa3eP5gWGaptD4AVEeibNmZ4zayZPWs8dYlU1YBogLBpMYnw0m7pmArsaGb61Fk+ uuhnmOuIFt7ekMO5KMlxkyN/qLu9PsYiBwXRIgX5HoL8EiT6QLS/MDgMpPiBxx3Ods4X iQHeBWcsRXhCb4Hhs2xWIr7mnNFEQP2f1odxvwNHjqpKOaPg6m32KX67VSn7+bd8SUzT V8Z/0Ko8NXs0ytaCYPhe5z3ZDqmgVLOC/x/LLJvSH5juHxD6itd6hKazp24v9lvHtdtG vCZyZpYXYbWFveRN8MGsrjHH3yxNG5gUxzOJ1YFUZUiU4iSyuVMpJPX0wGs96koo0hmR G0Rg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:references:in-reply-to :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Yl/Y1Uvo87E/VK8CbpEjgaisVScKBXe8Eorm+r2YrXM=; b=qlar+yxNmMbAX73CXefy4ZLMtfcKjTMEF4X4K0lvfJSg8ves3VmjTBlmZB3w1WJY5Q YduGzDUNewuzSnnduaNjO/4fv4Gkw3TssqXaCnXP4Z/Iw9qWwW9LU8tFOFjzAIJUa8xf 0w7/1AI69ge3DHpzRvirKCriRFQlVikWizNQUiACK3PH+sQFeu/LNHNnmOUo2pVzSEfM N+TCOwCl913sihqb3refnkyge6nSxFJJhR/3jo1Xl43I5PzghQKabxoH+5w0+yGFT0Ea RnplSwd+jBgxQuFeiGIwNaMPTtZNurmYwhJxS6Db7rLkHBgoLRfIvmq8Fy4J+5BCS4wT V+MQ== X-Gm-Message-State: ACrzQf0vpdpEEEsqNFPlS7+uhit3dWxGvW21BpernIF9xqlWzc5yMnnD euGAr+q0Lz1oy2hXlFbzhDirL0VB9W+UnKV0dUI= X-Google-Smtp-Source: AMsMyM797niYqtD6/uXLbpo2klwUqOYWf5CmWNpS3oNmQSnSs/plzDPa+aHfbu9g7xFqazREGiOF7AUTb773b3zK3is= X-Received: by 2002:a05:651c:2226:b0:277:4818:a1ca with SMTP id y38-20020a05651c222600b002774818a1camr6362672ljq.361.1667880603825; Mon, 07 Nov 2022 20:10:03 -0800 (PST) MIME-Version: 1.0 Received: by 2002:a05:6520:4af1:b0:22a:e96a:7f9b with HTTP; Mon, 7 Nov 2022 20:10:02 -0800 (PST) In-Reply-To: References: <87bkpqbwef.fsf@posteo.net> <87fsezgl4v.fsf@localhost> From: Samuel Wales Date: Mon, 7 Nov 2022 21:10:02 -0700 Message-ID: Subject: Re: Docstrings and literate programming (good practices?) To: Ihor Radchenko Cc: =?UTF-8?Q?Rudolf_Adamkovi=C4=8D?= , =?UTF-8?Q?Juan_Manuel_Mac=C3=ADas?= , orgmode Content-Type: text/plain; charset="UTF-8" Received-SPF: pass client-ip=2a00:1450:4864:20::231; envelope-from=samologist@gmail.com; helo=mail-lj1-x231.google.com 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, FREEMAIL_FROM=0.001, 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: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: 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=1667880652; 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=Yl/Y1Uvo87E/VK8CbpEjgaisVScKBXe8Eorm+r2YrXM=; b=pugUCtLeYQ1ik8h2X6/kFjPQucTXRXwiRWep/oHNiCw9JiG5WFpUrkPZggVsOewQAB4XQ3 yuH9jhI+xH0LuXgKkHoa1XMqllPiSk2QAwfGDAKVXXQR9dnmZiBzOb6u80dOrOUFLpp4Tj 0WEpeh09q9P9X+1MoryvOZp9iITHVdrocXLA0ddefL6nsObcjNmBNG7yPB/jUfKGagk+lT RU5PqVaODAWr3feEUdLIjpTGevvsyT5u8EVKgyuBUsAa59kU8p+E6qeBzejNrwki98t8tt ndWzxOi/Jhz/ishXIEtYq6/nEbj2QSTsC5ANrO39vq+HKukE8tdGnFgXw72fRg== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667880652; a=rsa-sha256; cv=none; b=CU9+V+dk34gaHbDgriEq+7hEshRZKzuqmpO6pnFaZ3Usw91mFaWIjcaZbbeuchfsvLxBlg skVfEP+uCKvGhcZhyiFQOkkRaWype3I8mK2s+qP+qVLiqJCCXUCHdqQNpZMTFvOsCqQWFR W7p9CmThtCLHU6R4dR5tNVpoQ0lVSBR45jsbdMZSPyvzFzuFG0thYc7znMcEwJ1ryCMRzG Y9cu4oNDR9PPZDPa3i73rBMJvy/nw7zw2NpTxMwMtXndjb0lSPzL+5Vmkq3cWM2aor+rpm cBiMRW//CqkxIdGzu63hc4vI/DMFa7D7FiggdCQmDTH2hL2/Me0W+RN4FJ8FJQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=eWQa3eP5; dmarc=pass (policy=none) header.from=gmail.com; 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: -5.51 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=eWQa3eP5; dmarc=pass (policy=none) header.from=gmail.com; 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: 991147C74 X-Spam-Score: -5.51 X-Migadu-Scanner: scn0.migadu.com X-TUID: Zr0rWwG+MqQy another option that might work for many users [at least would work for myself buyt needs are modest here] is unbreakable multi-directinal links such that you can link from a docstring to the manual or from the manual to the docstring. by multidirectional i mean you can have the same link, which also acts as an anchor, in multiple places. clicking would take you to the ohter if it is bidirectional, or show you a list of places or cycle if it is multidirectional. id markers. On 11/4/22, Samuel Wales wrote: > On 11/4/22, Ihor Radchenko wrote: >> 1. We need to convert from Elisp docstring format to Org markup > > not sure what is needed here as it is just a brainstorm. but i have a > manual i am loath to copy docstrings into when they are already in the > code. i could adumbrate a bit i the manual but i alreadyu do that > initially in the docstrings. > > first line is a good schelling point for this. b ut you are right > there is no standard i am awre of for anything more thn that. > >> 2. More importantly, User manual is something to be written as a >> coherent text; not an agglomeration of docstring. (Yes, I am aware of >> the fact that it is not always the case in practice; But we should >> not encourage the current situation) > > agreed, it is for a oherent text. the docstrings wuold be in a > section like "Commands you might like to run in this mode". Or so. > and have key bidings. > > they are not the whole manual. > >> >> -- >> Ihor Radchenko // yantar92, >> Org mode contributor, >> Learn more about Org mode at . >> Support Org development at , >> or support my work at >> > > > -- > The Kafka Pandemic > > A blog about science, health, human rights, and misopathy: > https://thekafkapandemic.blogspot.com > -- The Kafka Pandemic A blog about science, health, human rights, and misopathy: https://thekafkapandemic.blogspot.com