From: Ihor Radchenko <yantar92@posteo.net>
To: Tim Landscheidt <tim@tim-landscheidt.de>
Cc: emacs-orgmode@gnu.org
Subject: Re: Documentation of hline symbol in source blocks results
Date: Mon, 25 Dec 2023 17:09:01 +0000 [thread overview]
Message-ID: <87wmt2mcpe.fsf@localhost> (raw)
In-Reply-To: <87o7ee5jca.fsf@vagabond.tim-landscheidt.de>
Tim Landscheidt <tim@tim-landscheidt.de> writes:
> this is just a data point for anyone looking at restructur-
> ing the Org documentation.
>
> I wanted an Emacs Lisp source block to produce a table with
> a column name and a horizontal line separating the column
> name and the data cells. The data-only source block:
> ...
> I wanted to get the result:
>
> | #+RESULTS:
> | | Number |
> | |--------|
> | | 1 |
> | | 2 |
> | | 3 |
>
> It took me quite a while to figure out that the first row
> returned from the source block can be viewed as the column
> name, and a horizontal line can be achieved by returning the
> symbol 'hline:
AFAIK, producing tables with column names in
emacs-lisp code blocks is not officially supported.
The `hline' is not documented.
> The only reference to this behaviour I could find, is liter-
> ally the last (!, :-)) paragraph in the info file:
>
> | For complicated translations the generic translator function could be
> | replaced by a custom translator function. Such a custom function must
> | take two arguments and return a single string containing the formatted
> | table. The first argument is the table whose lines are a list of fields
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> | or the symbol ‘hline’.
This happens to be the machinery Org babel uses to convert tables from
Elisp format to Org mode format. We do not give you any guarantee that
we are going to keep using `orgtbl-to-generic' in future the same way.
> Just for further inspiration how the documentation could be
> rewritten, consider the current wording of "Results of Eval-
> uation/Collection/value":
>
> | Default for most Babel libraries(1). Functional mode. Org gets
> | the value by wrapping the code in a function definition in the
> | language of the source block. That is why when using ‘:results
> | value’, code should execute like a function and return a value.
> | For languages like Python, an explicit ‘return’ statement is
> | mandatory when using ‘:results value’. Result is the value
> | returned by the last statement in the code block.
>
> | When evaluating the code block in a session (see *note Environment
> | of a Code Block::), Org passes the code to an interpreter running
> | as an interactive Emacs inferior process. Org gets the value from
> | the source code interpreter’s last statement output. Org has to
> | use language-specific methods to obtain the value. For example,
> | from the variable ‘_’ in Ruby, and the value of ‘.Last.value’ in R.
>
> Wrapping the code? "Code /should/"? "Like a function"?
> Why is the Python requirement stated here?
I am sorry, but I do not fully understand the problem.
What we are saying is that the code block should return a value.
And give an example that python blocks, in order to return a value,
should have `return' statement.
> ... Why "using
> ‘:results value’" when the paragraph should (only) document
> this?
Emm.. But we are documenting :results value is this paragraph.
Mentioning it again is a bit redundant, but not the end of the world.
Improvements welcome, of course.
> ... "Result is the value"? What kind of value? Why are
> there references to Ruby and R here? All this confuses me
> and does not provide the information I searched for (empha-
> sis on me).
Ruby and R have their own syntax to return value, just like "return" in
python.
I hope it is clear now for you.
> I would probably prefer a clean-slate approach that starts
> with something along the lines of: "Source blocks produce
> results that can be integrated into an Org document and used
> as input for other source blocks. The abstract specifica-
> tion for source blocks looks like this ("structured table
> data" vs. "text dump", header arguments, export, etc.).
> Emacs Lisp source blocks produce these values in this way.
> Python that way. Shell scripts return tables in this way."
>
> Org is extremely powerful, but (I think I wrote it somewhere
> before) the documentation reads like users having had an is-
> sue ("my Python code does not produce (correct) results")
> and then someone feeling the need to document the solution
> right then and there. IMNSHO this leads to documentation
> that is not very usable for the general audience.
AFAIK, the particular paragraph you pointed out does not mention Python
just to address someone issue. Python/R/Ruby are just examples used.
Though I do agree that this (and many other) sections of the manual can
be improved. Patches welcome!
--
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:[~2023-12-25 17:06 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-25 16:37 Documentation of hline symbol in source blocks results Tim Landscheidt
2023-12-25 17:09 ` Ihor Radchenko [this message]
2023-12-26 10:50 ` Documentation Results of Evaluation (was Re: Documentation of hline symbol in source blocks results) Matt
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=87wmt2mcpe.fsf@localhost \
--to=yantar92@posteo.net \
--cc=emacs-orgmode@gnu.org \
--cc=tim@tim-landscheidt.de \
/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).