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 15:20:30 +0000 [thread overview]
Message-ID: <87bkpp1iyp.fsf@posteo.net> (raw)
In-Reply-To: <87o7tp8q29.fsf@localhost> (Ihor Radchenko's message of "Wed, 02 Nov 2022 13:05:18 +0000")
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
next prev parent reply other threads:[~2022-11-02 15:21 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
2022-11-02 15:20 ` Juan Manuel Macías [this message]
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=87bkpp1iyp.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).