Docstrings and literate programming (good practices?)

Docstrings and literate programming (good practices?)

[Juan Manuel Macías]

Hi all,

I find docstrings very useful. One can learn a great deal about Elisp
just from describe-function and describe-variable. But I don't find the
best way for docstrings to fit into the "precepts" of literate
programming. I try to explain myself: today I am reviewing my Emacs
init, written in Org. I like to document the code neatly, so that my
future self knows what my present self was trying to do. But I realize
that many of those global explanations before a function or a variable
can also be in a docstring. I can duplicate the text, but it seems to be
a bit redundant, right? So what is the best way to proceed when doing
literate programming with any language that supports docstrings?
Apologies in advance if the question is a bit silly, but I'm not a
professional programmer and don't have an academic background in it,
so I don't know if there is any good practice on these things :-)

On the other hand, the following procedure has occurred to me: put the
relevant information in an Org src block. When exporting to a human
readable format (PDF, HTML, etc.), the content is exported as part of
the text. When tangling, the block content is exported as a docstring.

First, I defined this function:

  (defun my-org-format-docstring (cont)
    (with-temp-buffer
      (insert cont)
      (save-excursion
	(goto-char (point-min))
	(while (re-search-forward org-emph-re nil t)
	  (replace-match (concat " " (match-string 4) " ") t nil)))
      (setq cont
	    (string-trim
	     (replace-regexp-in-string
	      "\\(\"\\)"
	      "\\\\\\1"
	      (org-export-string-as (buffer-string) 'ascii t)))))
    (format "\"%s\"" cont))


And an example of use:

#+NAME: format-docstring
#+begin_src emacs-lisp :exports none :var x="" :tangle no
  (if (not org-export-current-backend)
      (my-org-format-docstring x)
    x)
#+end_src

#+NAME: docstring1
#+begin_src org :post format-docstring(*this*) :results replace :exports results :tangle no
  Lorem ipsum dolor sit amet.

  Consectetuer adipiscing elit. "Donec hendrerit tempor tellus". Donec pretium posuere
  tellus. Proin quam nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis
  natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. 
#+end_src

#+begin_src emacs-lisp :noweb strip-export :exports code
  (defun foo ()
   <<docstring1()>>
    (message "hello world"))
#+end_src

The only drawback is that with :noweb strip-export an empty line is
left.

Best regards,

Juan Manuel 

Re: Docstrings and literate programming (good practices?)

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> #+NAME: docstring1
> #+begin_src org :post format-docstring(*this*) :results replace :exports results :tangle no
>   Lorem ipsum dolor sit amet.
>
>   Consectetuer adipiscing elit. "Donec hendrerit tempor tellus". Donec pretium posuere
>   tellus. Proin quam nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis
>   natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. 
> #+end_src

You can also have

#+name: docstring1
:   Lorem ipsum dolor sit amet.
:
:   Consectetuer adipiscing elit. "Donec hendrerit tempor tellus". Donec pretium posuere
:   tellus. Proin quam nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis
:   natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. 

> #+begin_src emacs-lisp :noweb strip-export :exports code
>   (defun foo ()
>    <<docstring1()>>
>     (message "hello world"))
> #+end_src
>
> The only drawback is that with :noweb strip-export an empty line is
> left.

Why do you need to strip docstring on export?

-- 
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>

Re: Docstrings and literate programming (good practices?)

[Dr. Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1396 bytes --]


Ihor Radchenko <yantar92@posteo.net> writes:

> Juan Manuel Macías <maciaschain@posteo.net> writes:
>
>> #+NAME: docstring1
>> #+begin_src org :post format-docstring(*this*) :results replace :exports results :tangle no
>>   Lorem ipsum dolor sit amet.
>>
>>   Consectetuer adipiscing elit. "Donec hendrerit tempor tellus". Donec pretium posuere
>>   tellus. Proin quam nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis
>>   natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. 
>> #+end_src
>
> You can also have
>
> #+name: docstring1
> :   Lorem ipsum dolor sit amet.
>
> :
> :   Consectetuer adipiscing elit. "Donec hendrerit tempor tellus". Donec pretium posuere
> :   tellus. Proin quam nisl, tincidunt et, mattis eget, convallis nec, purus. Cum sociis
> :   natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. 
>
>> #+begin_src emacs-lisp :noweb strip-export :exports code
>>   (defun foo ()
>>    <<docstring1()>>
>>     (message "hello world"))
>> #+end_src

Both of these options look awesome! Thank you for sharing!

The first (org-block) for long-form text (like official javadoc), the
second (just verbatim) for shorter docstrings.

They finally solve a long-standing problem for me.

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: Docstrings and literate programming (good practices?)

[Ihor Radchenko]

"Dr. Arne Babenhauserheide" <arne_bab@web.de> writes:

> The first (org-block) for long-form text (like official javadoc), the
> second (just verbatim) for shorter docstrings.

For even shorter docstrings, you can just #+name a paragraph.

-- 
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>

Re: Docstrings and literate programming (good practices?)

[Juan Manuel Macías]

Ihor Radchenko writes:

> Why do you need to strip docstring on export?

Hi Ihor,

Thanks for the suggestion. The problem with doing it this way is that
the paragraph is exported as verbatim, and I want it to be exported as a
normal part of the text. For example, in a PDF or HTML it would say
something like:

---
This awesome function is for blah blah, and makes blah blah, when blah blah.

[the function code]
---

But in the source file, that text would be a docstring, inside the
function code.

Actually I don't know if it's good practice to do it like this, hence my
doubts about how to 'marry' the literate programming concept with
languages that support docstring, which, somehow, are largely
self-documenting (thanks to the existence of the docstring itself) . The
scenario would rather be in long, multi-paragraph docstrings. Then this
dilemma comes to me: if I am doing literate programming and I want to
explain in detail what the function x does, I write it in the main text
as part of the documentation. But also that explanation should be a
docstring, in the source file. I understand that the docstring would not
appear in the PDF (to avoid redundancy), but I don't know if it would be
a good practice either, since the docstring belongs to the code...

In short, my dilemma is: how to do good literate programming with a
language like Elisp, which is almost self-documenting in its code? (So
one can learn a lot about Elisp just by reading the code in the *.el
files, without going to the documentation (which is a great strength of
Elisp, by the way).

Best regards,

Juan Manuel 

Re: Docstrings and literate programming (good practices?)

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> Ihor Radchenko writes:
>
>> Why do you need to strip docstring on export?
>
> Thanks for the suggestion. The problem with doing it this way is that
> the paragraph is exported as verbatim, and I want it to be exported as a
> normal part of the text. For example, in a PDF or HTML it would say
> something like:
>
> ---
> This awesome function is for blah blah, and makes blah blah, when blah blah.
>
> [the function code]
> ---

Can you elaborate about "paragraph is exported as verbatim"?

> Actually I don't know if it's good practice to do it like this, hence my
> doubts about how to 'marry' the literate programming concept with
> languages that support docstring, which, somehow, are largely
> self-documenting (thanks to the existence of the docstring itself) . The
> scenario would rather be in long, multi-paragraph docstrings. Then this
> dilemma comes to me: if I am doing literate programming and I want to
> explain in detail what the function x does, I write it in the main text
> as part of the documentation. But also that explanation should be a
> docstring, in the source file. I understand that the docstring would not
> appear in the PDF (to avoid redundancy), but I don't know if it would be
> a good practice either, since the docstring belongs to the code...
>
> In short, my dilemma is: how to do good literate programming with a
> language like Elisp, which is almost self-documenting in its code? (So
> one can learn a lot about Elisp just by reading the code in the *.el
> files, without going to the documentation (which is a great strength of
> Elisp, by the way).

I'd do something like the following:
1. Use normal Org text for docstring marked with some kind of block
   container (#+begin_docstring..#+end_docstring) or a dedicated
   headline.
2. Extend Org with some fancy links specific to docstring. That way, the
   original document can be read with active links to, say, other
   functions and variables. (I think Doom is using something like this
   for its new docs. Timothy is working on this)
3. Those links will be transformed to online documentation links on
   normal export.
4. For docstrings, on tangle, the links will be processed via
   `org-export-string-as' with a specialized backend that can escape
   what is needed for the target language docstring and transform Org
   links into whatever the docstring format is used for internal
   docstring references.
5. For docstrings, on export, the noweb will generate something like
   "[docstring is detailed in the text]", maybe even with a hyperlink to
   the docstring in text.

Hope it makes sense.   

-- 
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>

Re: Docstrings and literate programming (good practices?)

[Juan Manuel Macías]

Ihor Radchenko writes:

> Can you elaborate about "paragraph is exported as verbatim"?

Sorry for the conciseness in my previous explanation. I meant something
like this:

: foo

is exported to LaTeX as

\begin{verbatim}
foo
\end{verbatim}

(and what i want is for it to be exported as 'normal text').

>> Actually I don't know if it's good practice to do it like this, hence my
>> doubts about how to 'marry' the literate programming concept with
>> languages that support docstring, which, somehow, are largely
>> self-documenting (thanks to the existence of the docstring itself) . The
>> scenario would rather be in long, multi-paragraph docstrings. Then this
>> dilemma comes to me: if I am doing literate programming and I want to
>> explain in detail what the function x does, I write it in the main text
>> as part of the documentation. But also that explanation should be a
>> docstring, in the source file. I understand that the docstring would not
>> appear in the PDF (to avoid redundancy), but I don't know if it would be
>> a good practice either, since the docstring belongs to the code...
>>
>> In short, my dilemma is: how to do good literate programming with a
>> language like Elisp, which is almost self-documenting in its code? (So
>> one can learn a lot about Elisp just by reading the code in the *.el
>> files, without going to the documentation (which is a great strength of
>> Elisp, by the way).
>
> I'd do something like the following:
> 1. Use normal Org text for docstring marked with some kind of block
>    container (#+begin_docstring..#+end_docstring) or a dedicated
>    headline.
> 2. Extend Org with some fancy links specific to docstring. That way, the
>    original document can be read with active links to, say, other
>    functions and variables. (I think Doom is using something like this
>    for its new docs. Timothy is working on this)
> 3. Those links will be transformed to online documentation links on
>    normal export.
> 4. For docstrings, on tangle, the links will be processed via
>    `org-export-string-as' with a specialized backend that can escape
>    what is needed for the target language docstring and transform Org
>    links into whatever the docstring format is used for internal
>    docstring references.
> 5. For docstrings, on export, the noweb will generate something like
>    "[docstring is detailed in the text]", maybe even with a hyperlink to
>    the docstring in text.
>
> Hope it makes sense.   

I like the idea, because of the possibility of being able to use links.
That would also be respectful of the docstring as a legitimate part of
the code (in my approach, removing the docstring during export leaves an
empty line in the code, which is weird). Anyway, I think that with my
approach using org blocks and noweb references, links can also be used,
although more at a user/home-made level, with some export filter, I
suppose, that would convert the noweb reference into a normal link.

By the way, thinking about it, I don't know if a hypothetical header arg
called :docstring would be ok, something like:

#+NAME: foo
#+begin_<SPECIAL BLOCK NAME>
blah
#+end_<SPECIAL BLOCK NAME>

#+begin_src emacs-lisp :docstring foo
(defun foo ()
(message "hello world"))
#+end_src

And the docstring would be formatted and placed depending on the
language and the code (https://en.wikipedia.org/wiki/Docstring).

I don't know if something like this would make sense; although, thinking
about it, I like your idea of using special links better because it is
more versatile and (I guess) simpler to implement.

Best regards,

Juan Manuel 

Re: Docstrings and literate programming (good practices?)

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

>> Can you elaborate about "paragraph is exported as verbatim"?
>
> Sorry for the conciseness in my previous explanation. I meant something
> like this:
>
> : foo
>
> is exported to LaTeX as
>
> \begin{verbatim}
> foo
> \end{verbatim}
>
> (and what i want is for it to be exported as 'normal text').

You can just

#+name: foo
foo

that will be exported with all the markup.

> By the way, thinking about it, I don't know if a hypothetical header arg
> called :docstring would be ok, something like:
>
> #+NAME: foo
> #+begin_<SPECIAL BLOCK NAME>
> blah
> #+end_<SPECIAL BLOCK NAME>
>
> #+begin_src emacs-lisp :docstring foo
> (defun foo ()
> (message "hello world"))
> #+end_src
>
> And the docstring would be formatted and placed depending on the
> language and the code (https://en.wikipedia.org/wiki/Docstring).

That's asking for too much. Supporting :docstring header argument in
such form will require babel backends to parse the code, which may not
be trivial. Or consider odd cases with polymorphic functions with the
same name.

However, note one past feature request about escaping text in noweb
references:
 https://orgmode.org/list/82897e7d-f987-11f4-f7f5-fa1b8e462c0c@posteo.eu

Sébastien Miquel <sebastien.miquel@posteo.eu> (2021-05-03) (2021 emacs-orgmode.gnu.org maillist nolist)
Subject: [Feature request] String escaped noweb expansion

-- 
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>

Re: Docstrings and literate programming (good practices?)

[Rudolf Adamkovič]

Juan Manuel Macías <maciaschain@posteo.net> writes:

Hello Juan!

> I can duplicate the text, but it seems to be a bit redundant, right?
> So what is the best way to proceed when doing literate programming
> with any language that supports docstrings?  Apologies in advance if
> the question is a bit silly, but I'm not a professional programmer and
> don't have an academic background in it, so I don't know if there is
> any good practice on these things :-)

A "bit silly" question?  I find your question rather profound.  Thank
you for bringing it up!

Personally, I recommend to use both docstrings and literate programming
idiomatically, not mixing them.

Literate programming exposes thinking and exploration.

For example, the literate portion can show different approaches you
tried but abandoned, something that does not belong to the function
itself, nor in its docstring.  Or, it can include examples, piece-wise
performance analysis, computer science background, mathematical model,
citations of prior work, and so on.  Add some assertions and you will
have literate tests as well.

A docstring describes the function from the outside, as a black box, and
if you did a good job with it, it makes it simpler for the consumer to
use your function.

Literate programming, on the other hand, goes deeper.  It describes the
thinking that went into the function, comfortably exposing its insides
and opening the black box of its abstraction.

Rudy
-- 
"Strange as it may sound, the power of mathematics rests on its evasion
of all unnecessary thought and on its wonderful saving of mental
operations."
-- Ernst Mach, 1838-1916

Rudolf Adamkovič <salutis@me.com> [he/him]
Studenohorská 25
84103 Bratislava
Slovakia

Re: Docstrings and literate programming (good practices?)

[Samuel Wales]

i wonder if emacs or org has what you might call semi-literate or
etaretil docstring functions?

for example, you have a body of non-literate elisp code, and you have
a manual.  it could be redundant to describe commands and what they do
and their options, if the docstrings are good.

why not include the docstrings of all commands in some nice format in
the .org manual via some mechanism?

would that be a good practice?  seems useful abstractly.


On 11/3/22, Rudolf Adamkovič <salutis@me.com> wrote:
> Juan Manuel Macías <maciaschain@posteo.net> writes:
>
> Hello Juan!
>
>> I can duplicate the text, but it seems to be a bit redundant, right?
>> So what is the best way to proceed when doing literate programming
>> with any language that supports docstrings?  Apologies in advance if
>> the question is a bit silly, but I'm not a professional programmer and
>> don't have an academic background in it, so I don't know if there is
>> any good practice on these things :-)
>
> A "bit silly" question?  I find your question rather profound.  Thank
> you for bringing it up!
>
> Personally, I recommend to use both docstrings and literate programming
> idiomatically, not mixing them.
>
> Literate programming exposes thinking and exploration.
>
> For example, the literate portion can show different approaches you
> tried but abandoned, something that does not belong to the function
> itself, nor in its docstring.  Or, it can include examples, piece-wise
> performance analysis, computer science background, mathematical model,
> citations of prior work, and so on.  Add some assertions and you will
> have literate tests as well.
>
> A docstring describes the function from the outside, as a black box, and
> if you did a good job with it, it makes it simpler for the consumer to
> use your function.
>
> Literate programming, on the other hand, goes deeper.  It describes the
> thinking that went into the function, comfortably exposing its insides
> and opening the black box of its abstraction.
>
> Rudy
> --
> "Strange as it may sound, the power of mathematics rests on its evasion
> of all unnecessary thought and on its wonderful saving of mental
> operations."
> -- Ernst Mach, 1838-1916
>
> Rudolf Adamkovič <salutis@me.com> [he/him]
> Studenohorská 25
> 84103 Bratislava
> Slovakia
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: Docstrings and literate programming (good practices?)

[tomas]

[-- Attachment #1: Type: text/plain, Size: 782 bytes --]

On Thu, Nov 03, 2022 at 08:03:05PM -0700, Samuel Wales wrote:
> i wonder if emacs or org has what you might call semi-literate or
> etaretil docstring functions?
> 
> for example, you have a body of non-literate elisp code, and you have
> a manual.  it could be redundant to describe commands and what they do
> and their options, if the docstrings are good.
> 
> why not include the docstrings of all commands in some nice format in
> the .org manual via some mechanism?

Ah. Javadoc and their descendants. I tend to call that "illiterate
programming"...

> would that be a good practice?  seems useful abstractly.

... but I might be biased. I tend to detest its results. Especially
composed with languages having compulsive type declarations.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Docstrings and literate programming (good practices?)

[Marcin Borkowski]

On 2022-11-04, at 06:45, tomas@tuxteam.de wrote:

> On Thu, Nov 03, 2022 at 08:03:05PM -0700, Samuel Wales wrote:
>> i wonder if emacs or org has what you might call semi-literate or
>> etaretil docstring functions?
>> 
>> for example, you have a body of non-literate elisp code, and you have
>> a manual.  it could be redundant to describe commands and what they do
>> and their options, if the docstrings are good.
>> 
>> why not include the docstrings of all commands in some nice format in
>> the .org manual via some mechanism?
>
> Ah. Javadoc and their descendants. I tend to call that "illiterate
> programming"...

I spat my tea. :-)  Thanks, that's a nice one!

Though this _may_ work in some cases.  For example, imagine you divide
your package into two files – one with user-facing commands and another
one with internal functions.  If you order the former one carefully, the
"extract docstrings" might actually work as a documentation.

Still, a "normal" documentation seems a better (even if more
time-consuming) options.

Also, such docstring-based documentation is still better than none.

Best,

-- 
Marcin Borkowski
http://mbork.pl

Re: Docstrings and literate programming (good practices?)

[Samuel Wales]

my dry sensibilities say don't write ht same thing in the manual that
is well written in the docstring.  idk the issues however, other than
that once you do it in two places murphy's law says they will get out
of sync.

but surely an extractor could look for an interactive spec and things
like htat could subset the functions and text.

On 11/3/22, Marcin Borkowski <mbork@mbork.pl> wrote:
>
> On 2022-11-04, at 06:45, tomas@tuxteam.de wrote:
>
>> On Thu, Nov 03, 2022 at 08:03:05PM -0700, Samuel Wales wrote:
>>> i wonder if emacs or org has what you might call semi-literate or
>>> etaretil docstring functions?
>>>
>>> for example, you have a body of non-literate elisp code, and you have
>>> a manual.  it could be redundant to describe commands and what they do
>>> and their options, if the docstrings are good.
>>>
>>> why not include the docstrings of all commands in some nice format in
>>> the .org manual via some mechanism?
>>
>> Ah. Javadoc and their descendants. I tend to call that "illiterate
>> programming"...
>
> I spat my tea. :-)  Thanks, that's a nice one!
>
> Though this _may_ work in some cases.  For example, imagine you divide
> your package into two files – one with user-facing commands and another
> one with internal functions.  If you order the former one carefully, the
> "extract docstrings" might actually work as a documentation.
>
> Still, a "normal" documentation seems a better (even if more
> time-consuming) options.
>
> Also, such docstring-based documentation is still better than none.
>
> Best,
>
> --
> Marcin Borkowski
> http://mbork.pl
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: Docstrings and literate programming (good practices?)

[tomas]

[-- Attachment #1: Type: text/plain, Size: 1628 bytes --]

On Fri, Nov 04, 2022 at 07:39:04AM +0100, Marcin Borkowski wrote:
> 
> On 2022-11-04, at 06:45, tomas@tuxteam.de wrote:

[...]

> > Ah. Javadoc and their descendants. I tend to call that "illiterate
> > programming"...
> 
> I spat my tea. :-)  Thanks, that's a nice one!

Sorry to hear that ;-P

> Though this _may_ work in some cases.  For example, imagine you divide
> your package into two files – one with user-facing commands and another
> one with internal functions.  If you order the former one carefully, the
> "extract docstrings" might actually work as a documentation.

Yes, of course it's just a tool; but that kind of tool all too often
seduces people to switch to auto-pilot.

How many Doxygen docs have I had which tell me that function so-and-
so takes an int as third argument? I can see that by inspecting the
source! As a bonus, I don't get that much optical fluff and don't
have to go to the browser to look at it.

> Still, a "normal" documentation seems a better (even if more
> time-consuming) options.

Yes, it takes work.

> Also, such docstring-based documentation is still better than none.

That depends on how much work goes into the docstring. This:

  /* add 2 to x */
  x += 2;

is the typical quality you get when you're writing the docs while
waist-deep in the code. If you want good docs, you have to take a
step back and try to put yourself into the mind of someone else
(i.e. "forget" for a moment all the implicit knowledge you have
about that code you've been intimate with for weeks, perhaps for
years). That's not easy :)

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Docstrings and literate programming (good practices?)

[tomas]

[-- Attachment #1: Type: text/plain, Size: 631 bytes --]

On Fri, Nov 04, 2022 at 12:13:30AM -0700, Samuel Wales wrote:
> my dry sensibilities say don't write ht same thing in the manual that
> is well written in the docstring.  idk the issues however, other than
> that once you do it in two places murphy's law says they will get out
> of sync.

Absolutely. I can well imagine docstrings going into a reference.

> but surely an extractor could look for an interactive spec and things
> like htat could subset the functions and text.

My complaints were not so much about the extractors themselves as
about the kind of docs that tend to be made with them.

Cheers
-- 
t

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: Docstrings and literate programming (good practices?)

[Ihor Radchenko]

Samuel Wales <samologist@gmail.com> writes:

> why not include the docstrings of all commands in some nice format in
> the .org manual via some mechanism?
>
> would that be a good practice?  seems useful abstractly.

There are two problems:
1. We need to convert from Elisp docstring format to Org markup
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)

-- 
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>

Re: Docstrings and literate programming (good practices?)

[Max Nikulin]

On 04/11/2022 10:03, Samuel Wales wrote:
> 
> for example, you have a body of non-literate elisp code, and you have
> a manual.  it could be redundant to describe commands and what they do
> and their options, if the docstrings are good.

There is Sphinx in Python world that allows to combine guide pages with 
API docs extracted from source files: classes, functions, variables, 
modules (files). Some introduction and API reference may work well. I 
tried it, but without going deeper I did not manage to achieve the same 
quality as I saw for some packages at readthedocs.
https://www.sphinx-doc.org/en/master/

What I miss in texinfo is a feature similar to Intersphinx
https://www.sphinx-doc.org/en/master/usage/quickstart.html#intersphinx
To generate external references in HTML pages, an index file may be 
downloaded. As a result anchors in docs or function names are linked to 
proper files, anchors are formatted with section names as their description.

https://docs.python.org likely uses another tool, but the approach is 
often the same: general description and docstrings.

I think, Org manual published on the web site would benefit from links 
to HTML API reference generated from docstrings.

P.S. Pages generated by doxygen may be convenient as well. It is nice to 
have details related to functions and classes linked from overview, 
design description, a guide how this API should be used. Of course, it 
works only if such pages are written and added to doxygen config.

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

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