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 <samolog...@gmail.com> wrote: > On 11/4/22, Ihor Radchenko <yanta...@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