From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.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 6JDRN57FZWOpOQAAbAwnHQ (envelope-from ) for ; Sat, 05 Nov 2022 03:08:30 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id WJ+UN57FZWMKkgAAauVa8A (envelope-from ) for ; Sat, 05 Nov 2022 03:08:30 +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 78826679E for ; Sat, 5 Nov 2022 03:08:30 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1or8am-0002M4-W1; Fri, 04 Nov 2022 22:07:29 -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 1or8ak-0002Lq-9A for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 22:07:26 -0400 Received: from mail-lj1-x22f.google.com ([2a00:1450:4864:20::22f]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1or8ac-0004Wr-JK for emacs-orgmode@gnu.org; Fri, 04 Nov 2022 22:07:25 -0400 Received: by mail-lj1-x22f.google.com with SMTP id d3so8750238ljl.1 for ; Fri, 04 Nov 2022 19:07:16 -0700 (PDT) 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=GimKEX9dJndFPL++NwGgDcW0H4HKcl71R1nDo/IROsc=; b=nrYss7zi9N6AxQKh/nWqPkH+Q8SYbWr/wkYDscglH0QUhPVbry9jZ8GL1PjF790Gkh 6+cW3650Q6ujPEkG7wwMnsKG8EEiQORsxsP3Jbrx6IYyfCmy2DFGCA3pv0ad0gx9gtsn JIgx5zqMDvQ8Fi0ubvoB5zhKh3jUQ1CxUGBQhylsKWnp1Xs1wjS1KX5Iu7ohp7bLMB/n 73AJ3BoDEfJZlKidghnw06gpuYbQoP78srMzRgKkhGsp4QV7xHM9aquecC+O4gghAgIv hBetPrPIGrfSijVhdGZvXoq39VAVO9il/cfJjc5PYcfQyT775exAIj9Hy+VfCBTiirk8 /ilQ== 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=GimKEX9dJndFPL++NwGgDcW0H4HKcl71R1nDo/IROsc=; b=ylz9VmIwJyWQz8RoEdqUMQ6S62wDyxOoal+Srqp6UFPAStEc4iI8wBWNXewqv+XaYE 4SykVSdhdJ4jD5iEIlUBVLTzljBEYUYAUGVG8VlzHU6MnEuhx5xgorNaeQYhQN2nX0Kb OGLvurv2uejode17xTj/IKEeory0c6JyJXco+jEPyX8WMcd01zjf1FQ10jCsm6tdU5kk omnyAAp2/Bq2r+xb/Z+ncIHzBLPz+lkfjHLXZn1hAOXhs/JR8QejVB+SFYVQDzkxbPJy DYcUSLv7d1B9dYoGrlfqnO/R5BnLW3pIJdhWzykhBqxrwft+WRbbh8J8OTiDU0CT2/6P WIqg== X-Gm-Message-State: ACrzQf1fFRLA1ELXyF2zlDCNwJbgrks3hxknIUFkIgTAtma1CjX2BjRI zvMRUpsOHrYnc4D4lIKPM+RVpDFG9mABVMhu9dU= X-Google-Smtp-Source: AMsMyM6rZwzpLcpN1KkrTuPVuUGvcBgQ3XxNSB+PI9NpG5HUeL0Hpc5paMfJN1L83BnFc9pzTC08AaISOdIfjg6Zm+Y= X-Received: by 2002:a2e:5c89:0:b0:277:5a76:8c86 with SMTP id q131-20020a2e5c89000000b002775a768c86mr10742177ljb.361.1667614034605; Fri, 04 Nov 2022 19:07:14 -0700 (PDT) MIME-Version: 1.0 Received: by 2002:a05:6520:4af1:b0:22a:e96a:7f9b with HTTP; Fri, 4 Nov 2022 19:07:13 -0700 (PDT) In-Reply-To: <87fsezgl4v.fsf@localhost> References: <87bkpqbwef.fsf@posteo.net> <87fsezgl4v.fsf@localhost> From: Samuel Wales Date: Fri, 4 Nov 2022 19:07:13 -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::22f; envelope-from=samologist@gmail.com; helo=mail-lj1-x22f.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, SPF_HELO_NONE=0.001, T_SPF_TEMPERROR=0.01 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=1667614110; 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=GimKEX9dJndFPL++NwGgDcW0H4HKcl71R1nDo/IROsc=; b=T00xgROv9ESlju16ju7vdoqgvOVb910Eogz6GV8x/cumiithmJGliImVWytBs535i7e4vK bhtk0siqBqEA0KCCzaZhaJ1wUYwA6Fa8RPKboZLeeeZ1c+uAg6NG+FoSQbvJLr+9YF3ODv rrZGYxj0uFUcQisYDqlCFsV/VJ1P8laAX+rwJ6M0p+XaPra7m2y9134MKcvQSnJdXFb5It OzqgP+BBm9d3Ocb8hrbeV8Mkek4f0LW6f+SUtwGfvbFFc2V39DcHSLSkJkQeHa7FkGqcrU UgRRxCTx8mDBc+NjEVrBVU9furGXFysRVxQIZ3QaUiF33wt/U/fRUJSN6/xM7w== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1667614110; a=rsa-sha256; cv=none; b=rhi/lB817qVfMdamj859cYWDvYrIVW03VNkl2BNk9ITCJUtDAE42O5KpqdPnGRYbMjQYsC zeJsLP088M5jeiuKpQQ9exvAUkIWSQA/3r0gHKiN+oUK4Y1WBQ4+23q1aWNFJp0OsC1Kff Huzp1mKdbPx8Fns7ixDX4Rimi0ROJ8cBpMNcJwYqDbqxV85pQCaZd6DPKTmFq8BvqtuDRQ G+bn0qCrQ8QvkCxntaxTP0nXzGLy61mIHT85MTw+2mvieoEqLvHAnE4PUdC4l8OrkVYpMz LzErumFZEfd+LNtDwzhnfdJWbc39j9Pn8AnOSdhbTXWQ8HxjhPzcMVhYUwwTYg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=nrYss7zi; 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: -7.80 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=nrYss7zi; 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: 78826679E X-Spam-Score: -7.80 X-Migadu-Scanner: scn0.migadu.com X-TUID: N2Ur80YGhcLI 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