Re: Docstrings and literate programming (good practices?)

[Ihor Radchenko <yantar92@posteo.net>]

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>