Re: Docstrings and literate programming (good practices?)

[Samuel Wales]

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