From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:700:3204::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id grluAHAri2XFsQAAkFu2QA (envelope-from ) for ; Tue, 26 Dec 2023 20:37:20 +0100 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id CJYKNG8ri2WtrwAAe85BDQ (envelope-from ) for ; Tue, 26 Dec 2023 20:37:19 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=tsdye.online header.s=default header.b="QK7/iJZP"; 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=1703619439; 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:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=OtSWm7+Ewwd7Zfn0eZ9+qtdmD4FM6Oo5VwgFhkLQk08=; b=iaq4wJ5EvGNtxXXuTz64qNYw4V/8VbTFqPEIu/FFtgySu3H/WOWAZ/n7bHQkhxOnuLARYD g/X/OhfquZws0B6Lb1JwyRXvTpKcpwKAUQ+Dli+GdZUfndChQCQ4u5fK1oTmqzmDygHOmy yU6RzEXl5czV/dj5AsUlH7gZzkOnvbmEv1LzTT6LHgSULT4lwKehuOunSQLonROfyfkhLD C03pxamqB/LJY8gqyO2SPRsdvwjfwrK/Nf75K4RlCnPzbJ36fXVSGAU4RK4i/JgyNLlnB1 +3E/ZjHGco+t6rGXnl8bPYGoeYGwI3pquAQP0cALn+ZXKwt2gQPdBtUdoE+6aw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1703619439; a=rsa-sha256; cv=none; b=BtcvTNFwoOD3ZE0lneyml/hfkfoDuh4YOXl7UiAWI0WX01vSJP25FQ308GQ6OBTt8cRlI9 qPny8Sa520x1ybEZmRK52eRnfJ4NCN9yiCpKxB2LdLqTALmoTwuZlHJFnE8L7ME7XB8lsa c7hTQEPAKNitJOJw2jMYiDgxFewsB9qb+Iq1Jhob6My2eNZcCFKtoB3typWrJEGqgZu0lt osWzii5tnYuBoMp6f1xRxxv8iV96p/jerDmYYLC+a3qVboamPtHzfdcRlupIye4RJ+VFRx +5aGmdd7CHEFg04vDR+eLkiPNGLIMWEw8f8rPOuWLEgoqlB/It7+OK6Y0RB3dw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=tsdye.online header.s=default header.b="QK7/iJZP"; 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 253AC173C2 for ; Tue, 26 Dec 2023 20:37:19 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rIDE6-0001Hw-VN; Tue, 26 Dec 2023 14:36:30 -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 1rIDE5-0001Hn-Ea for emacs-orgmode@gnu.org; Tue, 26 Dec 2023 14:36:29 -0500 Received: from omta36.uswest2.a.cloudfilter.net ([35.89.44.35]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rIDE3-0008Gy-Df for emacs-orgmode@gnu.org; Tue, 26 Dec 2023 14:36:29 -0500 Received: from eig-obgw-5007a.ext.cloudfilter.net ([10.0.29.141]) by cmsmtp with ESMTPS id IBimrQucIhqFdIDDprbvMk; Tue, 26 Dec 2023 19:36:13 +0000 Received: from box2035.bluehost.com ([74.220.219.237]) by cmsmtp with ESMTPS id IDDorwv6ZqkaTIDDorlOIL; Tue, 26 Dec 2023 19:36:13 +0000 X-Authority-Analysis: v=2.4 cv=bY547cDB c=1 sm=1 tr=0 ts=658b2b2d a=VozZY++RX3oc2UgfNhVfaA==:117 a=VozZY++RX3oc2UgfNhVfaA==:17 a=OWjo9vPv0XrRhIrVQ50Ab3nP57M=:19 a=dLZJa+xiwSxG16/P+YVxDGlgEgI=:19 a=MKtGQD3n3ToA:10 a=1oJP67jkp3AA:10 a=e2cXIFwxEfEA:10 a=DPR-AOO6AYYA:10 a=A2tt7buDTgEA:10 a=uChsZFC9AAAA:8 a=o9zw6IYYAAAA:8 a=0RNCaYOsLz2003ut-VUA:9 a=-FEs8UIgK8oA:10 a=ULtXvzFHYWHLyBAuiDia:22 a=BtxB1_lq3pBo68oZtZ_9:22 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tsdye.online; s=default; h=Content-Type:MIME-Version:Message-ID:In-reply-to :Date:Subject:Cc:To:From:References:Sender:Reply-To:Content-Transfer-Encoding :Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=OtSWm7+Ewwd7Zfn0eZ9+qtdmD4FM6Oo5VwgFhkLQk08=; b=QK7/iJZPG6cUyaE/v4zjl8ht+k DjRnkce3lVGnvEEmgKVngAR0st3B9lxN8JApw9TRUxtjrmM1oiE7X8gQxh+UIrvKhuJUqBETjM2lS Xbh2phIdqieZryb1efvO48VObs+ziqKEZttyndZH7n6TnXO2Ro9/tU0cukLpykXZ47CWcCfh3xhaX hqRqkEBcKrbiACRCxU3SjwJpaPKFLK4SGaB4iEIZylIaY6rveXbUUE6zAG+rNvyRan6P1cWoEbWeh 15R61q+uhK4h26EsNawDhmXNhnQ0utHRCOls8rrBeBCvfzlupzIJVM5JYg4Fm7xS5BPGCu3I6z4kl mPH8hdDw==; Received: from 050-113-033-148.res.spectrum.com ([50.113.33.148]:40492 helo=poto-foou.tsdye.online) by box2035.bluehost.com with esmtpsa (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.96.2) (envelope-from ) id 1rIDDo-001RjJ-0G; Tue, 26 Dec 2023 12:36:12 -0700 References: <87wmt1dp1c.fsf@localhost> User-agent: mu4e 1.6.10; emacs 27.1 From: "Thomas S. Dye" To: Ihor Radchenko Cc: emacs-orgmode@gnu.org Subject: Re: [PATCH] org-manual: Describe export process flow Date: Tue, 26 Dec 2023 09:19:53 -1000 In-reply-to: <87wmt1dp1c.fsf@localhost> Message-ID: <877cl069jp.fsf@tsdye.online> MIME-Version: 1.0 Content-Type: text/plain; format=flowed X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - box2035.bluehost.com X-AntiAbuse: Original Domain - gnu.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - tsdye.online X-BWhitelist: no X-Source-IP: 50.113.33.148 X-Source-L: No X-Exim-ID: 1rIDDo-001RjJ-0G X-Source: X-Source-Args: X-Source-Dir: X-Source-Sender: 050-113-033-148.res.spectrum.com (poto-foou.tsdye.online) [50.113.33.148]:40492 X-Source-Auth: tsd@tsdye.online X-Email-Count: 2 X-Org: HG=bhshared;ORG=bluehost; X-Source-Cap: dHNkeWVvbmw7dHNkeWVvbmw7Ym94MjAzNS5ibHVlaG9zdC5jb20= X-Local-Domain: yes X-CMAE-Envelope: MS4xfM4tRoXKgl4bnrKfg+itDjkdVrw9tvo8UFZOm+VQuPT9pjNjic8SlcTsyFjINzb5zPmM9QkWqHC0Bg5I4pgtZ7MUyTDKtQaPeLGqyp6wBI6ZZRrlzAlS vV3p+KFGd2HaHDb9YTwYdqI4WFf0yWjqDO/OO8wREzPmJbw/FZhn9nOkmsYkYFuRxxWiAFhqIJQzuIolvn2NXQhoAn149M19qB4= Received-SPF: pass client-ip=35.89.44.35; envelope-from=tsd@tsdye.online; helo=omta36.uswest2.a.cloudfilter.net X-Spam_score_int: -15 X-Spam_score: -1.6 X-Spam_bar: - X-Spam_report: (-1.6 / 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, FROM_SUSPICIOUS_NTLD=0.498, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_PDS_OTHER_BAD_TLD=0.01, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no 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: -5.25 X-Spam-Score: -5.25 X-Migadu-Queue-Id: 253AC173C2 X-Migadu-Scanner: mx12.migadu.com X-TUID: kFmnQRwQSOPW Aloha Ihor, Ihor Radchenko writes: > Hi, > > I'd like to add a new section to Org mode manual. > The new section will describe all the steps performed by Org > export > process. This should hopefully create a more clear picture on > how > various export hooks and filters are used. > > The patch is attached. > I'd appreciate feedback from people not familiar with ox.el. I'm not too familiar with ox.el. I edited mostly to use an active voice. I put author queries in parentheses. I haven't paid attention to manual formatting conventions. IMO, more links would likely be helpful. * Suggested revision Org mode export is a multi-step process that works on a temporary copy of the buffer as follows: 1. Execute ~org-export-before-processing-hook~ (see [[*Hooks]]); 2. Expand =#+include= keywords; 3. Remove commented headings; (author: clarify whether the body is also removed?) 4. Replace macros; 5. Export source code blocks, conditional on ~org-export-use-babel~ and, if necessary, the individual ~exports~ header arguments (see [[*Exporting Code Blocks]]); 6. Evaluate source code blocks (see [[*Evaluating Code Blocks]]); 7. Execute ~org-export-before-parsing-hook~ (see [[*Hooks]]); 8. Calculate export option values according to in-buffer keywords, =#+BIND= keywords, and buffer-local and global customizations; 9. Calculate (author: Determine instead of Calculate?) bibliography file paths; 10. Execute ~org-export-filter-options-functions~; 11. Parse the temporary (author: is this correct?) buffer to generate an abstract syntax tree (AST); 12. Remove elements that will not be exported from the AST: 1. Headings according to =SELECT_TAGS= and =EXCLUDE_TAGS= export keywords, and =task=, =inline=, =arch= export options; 2. Comments; 3. Clocks, drawers, fixed-width environments, footnotes, LaTeX environments and fragments, node properties, planning lines, property drawers, statistics cookies, and timestamps according to their corresponding export options; 4. Table rows containing [[*Column Width and Alignment][width and alignment markers]]; 5. Table columns containing [[*Advanced features][recalc marks]]; 13. Expand environment variables in file links according to the =expand-links= export option (author: are we still operating on AST here?); 14. Execute ~org-export-filter-parse-tree-functions~ (author: ditto); 15. Create bibliography listing(s) from citation(s) (author: ditto); 16. Replace =+print_bibliography= keyword(s) with bibliography listing(s) (author: ditto); 17. Transcode the AST according to export backend using recursive, depth-first search, and passing each transcoded node as a string to the export filter (see [[*Filters]]): 18. Format transcoded AST according to the backend's "inner" template; 19. Execute ~org-export-filter-body-functions~ on the transcoded and formatted AST; 20. Format the result according to the backend's "outer" template; 21. Finalize bibliography listing(s) (author: correct?) and citation(s); and 22. Execute ~org-export-filter-final-output-functions~. Let me know if you have questions. All the best, Tom -- Thomas S. Dye https://tsdye.online/tsdye