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