From: Ihor Radchenko <yantar92@posteo.net>
To: "Juan Manuel Macías" <maciaschain@posteo.net>
Cc: orgmode <emacs-orgmode@gnu.org>
Subject: Re: Docstrings and literate programming (good practices?)
Date: Wed, 02 Nov 2022 13:05:18 +0000 [thread overview]
Message-ID: <87o7tp8q29.fsf@localhost> (raw)
In-Reply-To: <87leot1pyv.fsf@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>
next prev parent reply other threads:[~2022-11-02 13:09 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-01 14:07 Docstrings and literate programming (good practices?) Juan Manuel Macías
2022-11-02 7:13 ` Ihor Radchenko
2022-11-02 7:53 ` Dr. Arne Babenhauserheide
2022-11-02 10:43 ` Ihor Radchenko
2022-11-02 12:49 ` Juan Manuel Macías
2022-11-02 13:05 ` Ihor Radchenko [this message]
2022-11-02 15:20 ` Juan Manuel Macías
2022-11-03 7:38 ` Ihor Radchenko
2022-11-03 20:54 ` Rudolf Adamkovič
2022-11-04 3:03 ` Samuel Wales
2022-11-04 5:45 ` tomas
2022-11-04 6:39 ` Marcin Borkowski
2022-11-04 7:13 ` Samuel Wales
2022-11-04 8:08 ` tomas
2022-11-04 8:06 ` tomas
2022-11-04 8:49 ` Ihor Radchenko
2022-11-05 2:07 ` Samuel Wales
2022-11-08 4:10 ` Samuel Wales
2022-11-04 11:45 ` Max Nikulin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87o7tp8q29.fsf@localhost \
--to=yantar92@posteo.net \
--cc=emacs-orgmode@gnu.org \
--cc=maciaschain@posteo.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).