Documentation of hline symbol in source blocks results

[Tim Landscheidt <tim@tim-landscheidt.de>]

Hi,

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:

| #+BEGIN_SRC emacs-lisp
|   '((1)
|     (2)
|     (3))
| #+END_SRC

produces the result:

| #+RESULTS:
| | 1 |
| | 2 |
| | 3 |

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:

| #+BEGIN_SRC emacs-lisp
|   '(("Number")
|     hline
|     (1)
|     (2)
|     (3))
| #+END_SRC

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’.  The second argument is the property list
  ^^^^^^^^^^^^^^^^^^^^^
| consisting of parameters specified in the ‘#+ORGTBL: SEND’ line.  Please
| share your translator functions by posting them to the Org users mailing
| list, at <emacs-orgmode@gnu.org>.

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?  Why "using
‘:results value’" when the paragraph should (only) document
this?  "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).

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.

Tim