Re: Docstrings and literate programming (good practices?)

[Samuel Wales]

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