From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:1008:1e59::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id kOOQI6q2iWViYwEAkFu2QA (envelope-from ) for ; Mon, 25 Dec 2023 18:06:50 +0100 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id sHXxH6q2iWViRAEA62LTzQ (envelope-from ) for ; Mon, 25 Dec 2023 18:06:50 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=enkQ7s72; 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=pass (policy=none) header.from=posteo.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1703524010; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=ID+YUQx/GLMW0B4EbZTH3RwCaUTiyKodW3T1m2DUwPc=; b=JJ6wtPvsaniwW+n/laG6nkclvoQH+IEL/kukYKNB86ZLVbq45aj8xLXMtC+FBrBTtZOu5p nC0gRZQvhmhJpXR2W/dsxiV5ZjEiytoKPvqiGpNGXmS2uXYLrdGbYRP1F1+XroQIqqtitJ jpNqb+q6AEWK6ZBuNikbimBvVrp64C30x54OAgbCx5YXTunA2Avw/8QYRUOMG1xCyVzPz7 R/7Bm26E798h6qY0juUtuh7HnfqvweyPIQi+NkUMxTEsv0YLrCtuGhXkYptqmRevIpLBfw Dp1X1By/a4efTBrybfiDj+tY4K28pkscU2bLdx0VwXbxUmqPTJUn8Q9j6TJcYQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1703524010; a=rsa-sha256; cv=none; b=bbEk6TD03xPwgSOkiUatIkpXKYawM1ORdiW23R+pRlgi8YPOPhAchR3/y95LRPh/I8rMxd CvSKrPJyIn7FT7HUdJv/x08Fdil4ec59h6VJkkcxBCgbxx+LsCEu9Gyb2/i8t7HIWBIVsj 0fqrWveLKhC9lBt1w6eAYT3zGQCjPPpaG+gnVDCULj7sQQ9kXE0qTlF7jwv9wTFWbRdPYv yP0kR8DrtlFskT+hsuXG+B8xIWy7OgaACUMPd+BZvr9UMu7ipAxXImKd3PiSIrf7Uep7iD J+kb9qVpNJkJe41m4oJNeDRApVdqJgEP+i/xgelHV47779itNp6ex7J0hcaF4A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=enkQ7s72; 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=pass (policy=none) header.from=posteo.net 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 DCE4E148F9 for ; Mon, 25 Dec 2023 18:06:49 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rHoOr-0006gt-9D; Mon, 25 Dec 2023 12:05:57 -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 1rHoOp-0006gA-0p for emacs-orgmode@gnu.org; Mon, 25 Dec 2023 12:05:55 -0500 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rHoOm-0005Ke-34 for emacs-orgmode@gnu.org; Mon, 25 Dec 2023 12:05:54 -0500 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id B5FDB240028 for ; Mon, 25 Dec 2023 18:05:49 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1703523949; bh=sgVP9YObQ7GPsE/w8/NCBox4LppPIaC/2bT9NPx3rM8=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version: Content-Transfer-Encoding:From; b=enkQ7s72G56CmzZk1HLjjxUUl2pHtptg6bPD7GwfQTSzYoPSXflhfwq+YYpO5ulYQ ok9myMJioO0GGz39q2Nd2D+AximURHjqd+cFf22qg3AubcSB4OYmoWE5WlisIyuRjY KugEcMI7prcS7bny7WfO/LjyFYVUWvZP/HjENGGwMLXZeQ/tbi45HDjCe5CiDJCBRm mrYy3nqRqK/k/vathgBozjgz4cuyLvC7qNOtcEdivkPZ27BSvEE6ODG0vFGrYYlShq KUFQCony7bTTgoXkRs2PiV7/nTMBVGTAm1UMamPLdob8O/ceRsPWNZT1V0/+/LoT4Q OXX7q6cwiZ4rg== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4SzPRx2YKjz9rxB; Mon, 25 Dec 2023 18:05:49 +0100 (CET) From: Ihor Radchenko To: Tim Landscheidt Cc: emacs-orgmode@gnu.org Subject: Re: Documentation of hline symbol in source blocks results In-Reply-To: <87o7ee5jca.fsf@vagabond.tim-landscheidt.de> References: <87o7ee5jca.fsf@vagabond.tim-landscheidt.de> Date: Mon, 25 Dec 2023 17:09:01 +0000 Message-ID: <87wmt2mcpe.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, 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: -9.45 X-Spam-Score: -9.45 X-Migadu-Queue-Id: DCE4E148F9 X-Migadu-Scanner: mx12.migadu.com X-TUID: cV+AvkARxWSm Tim Landscheidt 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 =E2=80=98hline=E2=80=99. 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 =E2=80=98:re= sults > | value=E2=80=99, code should execute like a function and return a v= alue. > | For languages like Python, an explicit =E2=80=98return=E2=80=99 st= atement is > | mandatory when using =E2=80=98:results value=E2=80=99. 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=E2=80=99s last statement output. Org = has 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? 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 > =E2=80=98:results value=E2=80=99" when the paragraph should (only) docume= nt > 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. =20 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! --=20 Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at