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 2HesIY3gimUMMAEAkFu2QA (envelope-from ) for ; Tue, 26 Dec 2023 15:17:49 +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 sCXJGo3gimV09AAAqHPOHw (envelope-from ) for ; Tue, 26 Dec 2023 15:17:49 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=Yjp6KUZU; 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=1703600269; 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:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=BZ1MsPn/e0df+kLgox86lun7mISjhVQ1L5dJL9/R9ac=; b=Wfv1OSInCwkvZ0uDhRhB2ptLUUroRiT3jeCbCIr/ltgr7TEWGITZbMCnxFC3SizTCB4++Y ZDG3fV6XUIAkEBQTWxCzPhsWB38dKQhpNm0OyiPGhm8xYKQtA1/mhMiy2zj/2nkKnAe16r qv1/4zMALIU3iEuKtOPZjjmxBS2+8tQUoCd5Twikewx9h1nmI2vmuNLmSFyaRVfifw0ar2 6ZWAyIj61tJRSFnBSeysNc5gbsDXMcw/KpvQsK4zehWdfHuVjdPbqLdnbxVwUi+NTBE3PW zT+irlnxv15wrqFQpBpiVXvVfXEKxK/4F1BGo3W+YhSQHvoFzvjpavtDuDHg0Q== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1703600269; a=rsa-sha256; cv=none; b=AHiyEoO+oUbjiUFpxLi22kjIEEK6ZY/WGB84lAxut2b62UkjkFnKbX91RHxEmPgZx5t/98 M08t5YUkWMKpFCp73YgBGvq54YkfeWomKiasDIuVx5+zr/9QzlQFGEEJ1sCvivsLl7Hmz6 WFUmX3PZDsIAnAYJr83QuNaleWCSIGudEmeT9tUTDx/qBueAJQHqsHGHka0ENkK5e6yd92 TYJ8dpoEJHUazKLfbXX+EDqlLySSeGxLovEHfW5XvrpbpD9DEzADEqH3wXXj1EmW7/qaSy QXjAlWU/64rVJzXhOgkTdvDwxIFRf1Xqo0EH1FOenTTAIaFwBDsz8kEJmYCwpg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=Yjp6KUZU; 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 1B80C346AB for ; Tue, 26 Dec 2023 15:17:49 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rI8Ef-0000yH-9d; Tue, 26 Dec 2023 09:16:45 -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 1rI8Ec-0000xz-Mc for emacs-orgmode@gnu.org; Tue, 26 Dec 2023 09:16:42 -0500 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rI8EZ-0003MF-FZ for emacs-orgmode@gnu.org; Tue, 26 Dec 2023 09:16:42 -0500 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 1C971240104 for ; Tue, 26 Dec 2023 15:16:36 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1703600196; bh=PARU44a0diIe2UpBQOZzxTa8C3sKqxDeokXn+qEM5ks=; h=From:To:Subject:Date:Message-ID:MIME-Version:From; b=Yjp6KUZUl1ArGAQx51UOK7d5LczpHyA1WGsgiLgWcBp4zj/MOq2O/kJqUq/5eXiTD YGkTcZsZN38LQDoCBNEwHmFTj+UV83e4jEu+Z8NcSGLLOMTv9/IXodtKoiD4xmvUjG 4ecpPFmXJdHOcwWKpYPDStq+8EHjyOc5Tdaqjtbz8w65GanFLYz5di2QybT3c4cusS A6sKinwf5RjRd8+UGv/hEZGkxZCbMk5PsEW7L+RFREGUwq4FAPHPXzdBi5OSaJciAy fOsjBDThv+rZNaFkSiYKohrNC2jeuDqjC7SBGzd/qrdyhrKUHi2a66olpN6k5+cvQO BUxKf256mpqQw== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4SzxfC4jcwz6tv5 for ; Tue, 26 Dec 2023 15:16:35 +0100 (CET) From: Ihor Radchenko To: emacs-orgmode@gnu.org Subject: [PATCH] org-manual: Describe export process flow Date: Tue, 26 Dec 2023 14:19:43 +0000 Message-ID: <87wmt1dp1c.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=185.67.36.66; envelope-from=yantar92@posteo.net; helo=mout02.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: 1B80C346AB X-Migadu-Scanner: mx12.migadu.com X-TUID: BVr0KS5Exa6H --=-=-= Content-Type: text/plain 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. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-doc-org-manual.org-Describe-export-flow.patch >From 57d290b710c85e0411855937e224d2cecdbd52da Mon Sep 17 00:00:00 2001 Message-ID: <57d290b710c85e0411855937e224d2cecdbd52da.1703600243.git.yantar92@posteo.net> From: Ihor Radchenko Date: Tue, 26 Dec 2023 15:15:23 +0100 Subject: [PATCH] doc/org-manual.org: Describe export flow * doc/org-manual.org (Summary of the export process): Explain how the export process is handled in Org mode. --- doc/org-manual.org | 54 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/doc/org-manual.org b/doc/org-manual.org index 7db69cbb6..1a9432b4d 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -16391,6 +16391,60 @@ ** Advanced Export Configuration :DESCRIPTION: Fine-tuning the export output. :END: +*** Summary of the export process + +During export, Org mode processes the source Org buffer in multiple +steps: + +1. The source Org mode buffer is copied into temporary throwaway + buffer that can be edited by export hooks +2. ~org-export-before-processing-hook~ is executed (see [[*Export hooks]]) +3. All the =#+include= keywords are expanded +4. All the commented headings are removed +5. All the macros are replaced in buffer +6. When ~org-export-use-babel~ is non-nil (default), all the src + blocks and babel calls that are not inside archived headings are + processed +7. ~org-export-before-parsing-hook~ is executed (see [[*Export hooks]]) +8. Export option values are calculated, according to in-buffer + keywords, =#+BIND= keywords, buffer-local and global + customizations. +9. Files contributing to bibliography are calculated +10. ~org-export-filter-options-functions~ is executed +11. The buffer is parsed, generating abstract syntax tree (AST) +12. The AST is cleaned from buffer elements that should not be + exported: + - Heading are removed according to =SELECT_TAGS= and + =EXCLUDE_TAGS= export keywords; =task=, =inline=, =arch= export + options + - All the comments are removed + - Clocks, drawers, fixed-width environments, footnotes, latex + environments and fragments, node properties, planning lines, + property drawers, statistics cookies, and timestamps are removed + or kept according to the corresponding export options + - Table rows containing [[*Column Width and Alignment][width and alignment markers]] are removed + - Table columns containing [[*Advanced features][recalc marks]] are removed +13. Environment variables are expanded in all the file links when + =expand-links= export option is set +14. ~org-export-filter-parse-tree-functions~ is executed +15. All the citations are processed according to the chosen citation + backend +16. =#+print_bibliography= keywords are replaced with bibliography + listings +17. AST is transcoded according to the chosen export backend + - The export happens recursively, depth-first + - Each transcoded AST node, as a string, is passed to the + corresponding export filter (see [[*Filters]]) +18. The transcoded AST body is formatted according to backend's + "inner" template +19. The resulting body is passed to + ~org-export-filter-body-functions~ +20. The filtered body is formatted according to backend's outer + template +21. The resulting output is processed by citation backend finalizer +22. ~org-export-filter-final-output-functions~ are applied to the + final output + *** Export hooks :PROPERTIES: :UNNUMBERED: notoc -- 2.42.0 --=-=-= Content-Type: text/plain -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at --=-=-=--