From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id yItGH2Yj42DergAAgWs5BA (envelope-from ) for ; Mon, 05 Jul 2021 17:21:10 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id aHURG2Yj42BxUgAA1q6Kng (envelope-from ) for ; Mon, 05 Jul 2021 15:21:10 +0000 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 8933311FBD for ; Mon, 5 Jul 2021 17:21:09 +0200 (CEST) Received: from localhost ([::1]:38526 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1m0QPD-0006Jx-Fo for larch@yhetil.org; Mon, 05 Jul 2021 11:21:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:52984) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m0QOb-0006JY-8T for emacs-orgmode@gnu.org; Mon, 05 Jul 2021 11:20:29 -0400 Received: from mailbackend.panix.com ([166.84.1.89]:16998) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1m0QOZ-0003KB-AY for emacs-orgmode@gnu.org; Mon, 05 Jul 2021 11:20:29 -0400 Received: from panix1.panix.com (panix1.panix.com [166.84.1.1]) by mailbackend.panix.com (Postfix) with ESMTP id 4GJTs43LFZz2sBt; Mon, 5 Jul 2021 11:20:24 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=panix.com; s=panix; t=1625498424; bh=RiD/sP2UA406hLDbRF6n93upR7GZgUO0OsBmwXnP81o=; h=Date:From:To:Subject:In-Reply-To:References; b=CRL4IiZ/dGtUoh6xsxmP1jh+ka4hZFCI3OZ+gTmX1S+cMivlOq+fe264ZxFLPTAuK 30oQEm0nQjFh1gdnM3dzXd88ZacudmU9spNErong+LCujPUB/zbXL6ZBHgt+LwoCX0 +++D3lTwe4zKI6/q/5BfIY3jvQumYrW2QgCtkUUQ= Received: by panix1.panix.com (Postfix, from userid 20712) id 4GJTs42FRczcbc; Mon, 5 Jul 2021 11:20:24 -0400 (EDT) Received: from localhost (localhost [127.0.0.1]) by panix1.panix.com (Postfix) with ESMTP id 4GJTs41jYbzcbP; Mon, 5 Jul 2021 11:20:24 -0400 (EDT) Date: Mon, 5 Jul 2021 11:20:24 -0400 From: Jude DaShiell To: Tim Visher , Org Mode List Subject: Re: how to document/comment a complex org table formula In-Reply-To: Message-ID: References: <87h7h9c2nw.fsf@mat.ucm.es> <87zgv0alwt.fsf@ucl.ac.uk> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Received-SPF: pass client-ip=166.84.1.89; envelope-from=jdashiel@panix.com; helo=mailbackend.panix.com 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_H3=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.23 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" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1625498469; 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:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=wdz7Bt5OzqMHBsXu6DoK0ZFoZVfKAObgS4E4lJcrYyM=; b=tmKVhtr4ZxKdHa9SKsd3WyafLvARsFS7+J9MNbf92NfotMGsjDJ9fb3gK3K9Nd7DgdDnCW HEKX4swtFXQe6xo90UrKgiMvPJLP7Vh/yfQ1ki+U2gcMh/64JxK0kucZ39b0Zs2X5W1zZ1 ZMk3cWC0TpnkDC9CUgfdRo+wRatabwmMGcIElQQ+6/3JuQHH9HDo/BvS2KwWGPpgeEg4QA XVYWmthgGMEEDA2DxyLFYXb4HqlMt2oELxO61UIqjvW4KYk4oZFpqBrhxv5FD6uWtINIYg DxCxnUmYpJ8ErCI+CEmr8Kp//t+LrMAqkRe4e83lM3JwR1yTZhzG/8tYWBh7PA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1625498469; a=rsa-sha256; cv=none; b=aW9OWcJoXaW2UYFlBMZdwpY5sls3Qfh86AividlolDqbGRG+NIYvYikAsU3iifCp/qHtDZ Em1KjayTCDBWFyOOIrR+3Tm1MZ3U6lAJP8zZY7PQ3XlaVZTTzetAXOzk4GyadIRXQMYiKW RF8WBbT5IXeZWEdFySP6nsPUJoSltGJ6GNg66dEGO3WxW34AT6CNi7F7Rar2EwJ4CKAdYs zSMj+6Y8cyZY1EcXXmeX4AYYtMdD1+mbDkx6xaDCag1NmBscINZIk5GM4UAZfoJGDmTQGo hrxCL8kfbJZpvAJ496LNYS8CYqi7U5qbT0eiR361yxd6vF0BVREgiBAtMQl5SQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=panix.com header.s=panix header.b="CRL4IiZ/"; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Spam-Score: -1.41 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=panix.com header.s=panix header.b="CRL4IiZ/"; dmarc=none; spf=pass (aspmx1.migadu.com: domain of emacs-orgmode-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=emacs-orgmode-bounces@gnu.org X-Migadu-Queue-Id: 8933311FBD X-Spam-Score: -1.41 X-Migadu-Scanner: scn1.migadu.com X-TUID: nl7JxQAk8vy8 Why not use functional narrative form to document complex formulas? formula name: formula function: formula uses: formula returns: usually one line of text for each of those. I know, this comes from structured programming where no block of actual code is supposed to go above 50 lines and that for many people cramps their styles. It makes maintenance a little easier though. On Mon, 5 Jul 2021, Tim Visher wrote: > On Mon, Jul 5, 2021 at 10:14 AM Eric S Fraga wrote: > > > Sorry; I cannot help you directly. > > > > My rule of thumb is that if formulas are getting too complex to > > understand/recall clearly, it's time to use a proper programming > > language instead. The nice thing about org is you can have tables as > > inputs to and outputs of src blocks... > > > > My papers often have awk source blocks that process tables to generate > > statistics for some (numerical) experiments. > > > > Spreadsheets, org tables being an example of such, are brilliant tools > > for simple calculations but are pretty much "write only programming > > languages". > > > > I had never heard of using an org table as input into a source block. > That's really interesting. > > The OP also poses an interesting idea that I have occasionally wanted. I > have generally accomplished this by simply including the documentation > above or below the table. In other words just having human text around it > that says 'This =formula= bit is because of X'. > > But the idea of a multiline TBLFM syntax seems to be already be almost > supported. I was mildly shocked to find that this mostly works > > ``` > |---+---| > | a | 1 | > | b | 3 | > |---+---| > | | 4 | > #+TBLFM: @2$2=@-1*3 > #+TBLFM: @3$2=vsum(@I..II) > ``` > > Note that I don't need the usual `::` separation between formulas. Where it > breaks down is that I can't seem to reevaluate the whole table's formula by > whacking `C-u C-c C-c` anymore and, obviously, there's no syntax for adding > comments. Also I doubt that I'd be able to use any of org's keys for > editing formulas. I wonder how hard it would be to extend org's > understanding of the TBLFM to allow for this kind of syntax. > > Once you had it then adding a comment character to it should be very simple. > > -- > > In Christ, > > Timmy V. > > https://blog.twonegatives.com > http://five.sentenc.es >