From: "Juan Manuel Macías" <maciaschain@posteo.net>
To: Ihor Radchenko <yantar92@posteo.net>
Cc: orgmode <emacs-orgmode@gnu.org>
Subject: Re: Docstrings and literate programming (good practices?)
Date: Wed, 02 Nov 2022 12:49:12 +0000 [thread overview]
Message-ID: <87leot1pyv.fsf@posteo.net> (raw)
In-Reply-To: <87v8nxkewc.fsf@localhost> (Ihor Radchenko's message of "Wed, 02 Nov 2022 07:13:23 +0000")
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
next prev parent reply other threads:[~2022-11-02 13:07 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 [this message]
2022-11-02 13:05 ` Ihor Radchenko
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=87leot1pyv.fsf@posteo.net \
--to=maciaschain@posteo.net \
--cc=emacs-orgmode@gnu.org \
--cc=yantar92@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).