[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Docstrings and literate programming (good practices?)
From: |
Samuel Wales |
Subject: |
Re: Docstrings and literate programming (good practices?) |
Date: |
Mon, 7 Nov 2022 21:10:02 -0700 |
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 <samologist@gmail.com> wrote:
> On 11/4/22, Ihor Radchenko <yantar92@posteo.net> 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 <https://orgmode.org/>.
>> Support Org development at <https://liberapay.com/org-mode>,
>> or support my work at <https://liberapay.com/yantar92>
>>
>
>
> --
> 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