From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:303:5f26::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id aM3dMQ2wiWX8/gAAkFu2QA (envelope-from ) for ; Mon, 25 Dec 2023 17:38:37 +0100 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id 8PjUKA2wiWXJrgAAqHPOHw (envelope-from ) for ; Mon, 25 Dec 2023 17:38:37 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1703522317; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=v9Zlp+nE1NtOdhqHboOHQ9NOr2eTxP70WxsbgQO1PWE=; b=VtxV2s7Uzd8Yxfo/UFBLKUtinhOicSfJkURUtjI5yo+WLgxH4mUsjijmtdXNBO298uMZ59 U/Ujfw2VgUMsBaOvC5gkGpW0a1/SrgxNaukqRIxOEYq6kg1ZY+YOl6C1bc7Ik/WudgBk1f cQ94J2wmQoqampYVq2JaWoq0/jxsysiMZu3zba5tfpyLhjA3rpz3DMycCRbESMyPO23sK0 iJ8b9cKLparQADm9MerCJCpP/LGj0yPmpc4HE79u9FIN7qmInADTHJkdhVYNGcsQASFJZY zZ2Rvo0kuUfRHZyZf2L9JCfaYmrekuJMgsTttyQNXIDLDggzbj/CToUFkRSuYQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1703522317; a=rsa-sha256; cv=none; b=Wr7JSrUG+RLLBagWRVWAtGZLDrmMR7vJzKLW+vkTpXOxMsvc5dmOYpsTBV+utW0uvbwy2w D+A0Uinh1shVyDTKQi+1FZeCnLbQkE7DipTXB1PjFObDbwM5+FEhktuP8eB237AXfptrvP dHFakwSXhauq6mG0JkFk117Blk/3olIeTzPk5vN8B3rZiQyTGd3zk2AR9kfjpx2WvnVxYR B+VzouT8HCt2s20zfaC1CIEtWGWm0yF9o0XWRMemWb5cA10Qc0VnIkELnvXpQTHz0pvlxs j0M+E5FBxOhNJHp1PYqSNSv4Vw5Yz9uaFKlBJXFbCgJ+REsNXpxgT+o1Cvj+MQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org"; dmarc=none Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 61AFC1415B for ; Mon, 25 Dec 2023 17:38:37 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rHnxd-0005Ct-Qo; Mon, 25 Dec 2023 11:37:49 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rHnxc-0005CW-7S for emacs-orgmode@gnu.org; Mon, 25 Dec 2023 11:37:48 -0500 Received: from gavdos.tim-landscheidt.de ([2a01:4f8:1c0c:4bd6::1]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rHnxa-00013e-9a for emacs-orgmode@gnu.org; Mon, 25 Dec 2023 11:37:47 -0500 Received: from port-62-145-29-194.static.as20676.net ([62.145.29.194]:51780 helo=vagabond) by gavdos.tim-landscheidt.de with esmtpsa (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96) (envelope-from ) id 1rHnxW-008Ydw-1S for emacs-orgmode@gnu.org; Mon, 25 Dec 2023 16:37:42 +0000 From: Tim Landscheidt To: emacs-orgmode@gnu.org Subject: Documentation of hline symbol in source blocks results Organization: https://www.tim-landscheidt.de/ Date: Mon, 25 Dec 2023 16:37:41 +0000 Message-ID: <87o7ee5jca.fsf@vagabond.tim-landscheidt.de> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2a01:4f8:1c0c:4bd6::1; envelope-from=tim@tim-landscheidt.de; helo=gavdos.tim-landscheidt.de X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -6.24 X-Spam-Score: -6.24 X-Migadu-Queue-Id: 61AFC1415B X-Migadu-Scanner: mx12.migadu.com X-TUID: aJe8wob/cJeg 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 =E2=80=98hline=E2=80=99. The second argument is the proper= ty list ^^^^^^^^^^^^^^^^^^^^^ | consisting of parameters specified in the =E2=80=98#+ORGTBL: SEND=E2=80= =99 line. Please | share your translator functions by posting them to the Org users mailing | list, at . 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 =E2=80=98:resu= lts | value=E2=80=99, code should execute like a function and return a val= ue. | For languages like Python, an explicit =E2=80=98return=E2=80=99 stat= ement is | mandatory when using =E2=80=98:results value=E2=80=99. Result is th= e 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=E2=80=99s last statement output. Org ha= s to | use language-specific methods to obtain the value. For example, | from the variable =E2=80=98_=E2=80=99 in Ruby, and the value of =E2= =80=98.Last.value=E2=80=99 in R. Wrapping the code? "Code /should/"? "Like a function"? Why is the Python requirement stated here? Why "using =E2=80=98:results value=E2=80=99" 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