From: "ZHUO QL (KDr2)" <zhuoql@yahoo.com>
To: emacs-orgmode@gnu.org
Subject: Proposal: references from code to text.
Date: Sat, 12 May 2018 13:29:48 +0000 (UTC) [thread overview]
Message-ID: <800808596.465327.1526131788117@mail.yahoo.com> (raw)
In-Reply-To: 800808596.465327.1526131788117.ref@mail.yahoo.com
[-- Attachment #1: Type: text/plain, Size: 5140 bytes --]
Hi all, I just post a proposal for orgmode on my website(generated by orgmode):
http://kdr2.com/tech/emacs/1805-proposal-org-ref-code-to-text.html .
Here is the source of the proposal:
# -*- mode: org; mode: auto-fill; -*-
#+TITLE: Proposal for Orgmode: references from code to text.
#+AUTHOR: KDr2
#+OPTIONS: toc:nil
#+OPTIONS: num:nil
#+BEGIN: inc-file :file "common.inc.org"
#+END:
#+CALL: dynamic-header() :results raw
#+CALL: meta-keywords(kws='("orgmode" "literate programming")) :results raw
# - DATE
<2018-05-12 Sat>
Literate programming is writing out the program logic in a human
language with included (separated by a primitive markup) code snippets
and macros. A preprocessor is used to substitute arbitrary
hierarchies, or rather "interconnected 'webs' of macros", to produce
the compilable source code with one command ("tangle"), and
documentation with another ("weave").
So in a literate programming source file, any chunk is either a block
of code or a block of document in a human language, I'll call them
*code* and *text* below.
In my opinion, code and text should be able to reference each other:
- *Text refers to text* \\
In the exported/woven documentation, these references act as links,
make interconnections between relevant topics.
- *Text refers to code* \\
The links in the exported/woven documentation can also link to a
line of code if the code blocks are also included in the
exported/woven documentation.
- *Code refers to code* \\
That's the most important part of the literate programming. This
kind of references act as placeholders or something like macro in
the C-programming language. With it, literate programming provides
an ability to change the order of the source code from a
machine-imposed sequence to one convenient to the human mind. [[https://en.wikipedia.org/wiki/Literate_programming#Example][Here
is a simple Example depicts this concept]].
- *Code refers to text* \\
So far as I know, no literate programming tool has this kind of
references. However, this kind of references could be very benifical
too. Many programming languages have a mechanism to support
embedding documentation(usually as comments) in the source code, AKA
[[https://en.wikipedia.org/wiki/Docstring][Docstring]]. These embedded documentations are widely and conveniently
used in editor, REPL and IDE. For instance, the docs of any elisp
function that we can read in Emacs are from the elisp source.
But in literate programming we seldom embed comments into the code
blocks, as an impliaction the extracted/tangled code has no docs
embeded. If we can refer to chunks of text in the code blocks, we
will have the chance to include these chunks of text as embeded docs
in the code in the tangling process, which results in
well-documented source code. This is useful especially while the
programmer are authoring reusable source code, like libraries or
frameworks.
Here is the implementation status of these kinds of references of
noweb and Org mode (~->~ means 'has the ability to make reference
to'):
| tool | text -> text | code -> code | text -> code | code -> text |
|----------+--------------+------------------+----------------+--------------|
| noweb | No | Yes | No | No |
| Org mode | Yes, links | Yes, noweb style | Yes, ~(ref:*)~ | No |
As we saw, both noweb and Org mode do not implement the reference from
code to text. Could we provide this feature in Org mode -- the best
and widely used literate programming tool?
As a proposal, in Org mode, we can mimic the labels in
code blocks(i.e. text -> code reference), use something like
~(ref:text:<REF-NAME>)~ as the reference from code to text:
#+BEGIN_SRC org
,#+NAME: DOC-OF-ADD
We use the function add to calculate the sum of two numbers.
,#+BEGIN_SRC elisp
(defun add (x y)
"(ref:text:DOC-OF-ADD)"
(+ x y))
,#+END_SRC
#+END_SRC
The Org file above will produce the code below:
#+BEGIN_SRC elisp
(defun add (x y)
"We use the function add to calculate the sum of two numbers."
(+ x y))
#+END_SRC
- Beside the ~NAME~, we could also support reference via the
~CUSTOM_ID~ property or anything else that can locate a text chunk.
- In the tangling process, we should do some kind of transformation of
the target text, for example, escape the quote mark. A hook may be
needed to let the user customize the transformation too.
What do you think?
* References
- https://en.wikipedia.org/wiki/Literate_programming
- https://en.wikipedia.org/wiki/Noweb
- https://en.wikipedia.org/wiki/Docstring
- http://orgmode.org/manual/Extracting-source-code.html#Extracting-source-code
- http://orgmode.org/manual/Noweb-reference-syntax.html#Noweb-reference-syntax
- http://orgmode.org/manual/Literal-examples.html#Literal-examples
- https://orgmode.org/worg/dev/org-syntax.html
* Discuss and Comment
#+BEGIN: inc-file :file "comment.inc.org"
#+END:
[-- Attachment #2: Type: text/html, Size: 5484 bytes --]
next parent reply other threads:[~2018-05-12 13:29 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <800808596.465327.1526131788117.ref@mail.yahoo.com>
2018-05-12 13:29 ` ZHUO QL (KDr2) [this message]
2018-05-14 5:48 ` Proposal: references from code to text Eric S Fraga
2018-05-14 15:05 ` John Kitchin
2018-05-14 17:06 ` Eric S Fraga
2018-05-14 17:11 ` Eric S Fraga
2018-05-15 4:49 ` ZHUO QL (KDr2)
2018-05-15 10:04 ` Eric S Fraga
2018-05-16 7:04 ` ZHUO QL (KDr2)
2018-05-16 14:25 ` John Kitchin
2018-05-16 19:37 ` Samuel Wales
2018-05-17 2:29 ` John Kitchin
2018-05-17 2:40 ` Samuel Wales
2018-05-17 2:58 ` ZHUO QL (KDr2)
2018-05-17 3:10 ` John Kitchin
2018-05-17 9:33 ` ZHUO QL (KDr2)
2018-06-15 21:44 ` John Kitchin
2018-06-15 18:07 ` Grant Rettke
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=800808596.465327.1526131788117@mail.yahoo.com \
--to=zhuoql@yahoo.com \
--cc=emacs-orgmode@gnu.org \
/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).