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 yErjGCZMi2X6pQAAkFu2QA (envelope-from ) for ; Tue, 26 Dec 2023 22:56:54 +0100 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id 2IZUECZMi2UbYQEAe85BDQ (envelope-from ) for ; Tue, 26 Dec 2023 22:56:54 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=R2VaUew9; 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"; arc=pass ("zohomail.com:s=zohoarc:i=1"); dmarc=none ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1703627814; 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=4vKa9M2UVTFEOI/+WfGNRY11Gh31qCjbL4zXbMdHQbg=; b=d9R4uKJGZtU1jRfdl+lm5B4oPl/lfYbAB8KADQYaHtFbmOfAcpDpJ99Puzyn00zJ/gu4Qc nvcukghfCYP2pU0qvgKDSZ2xhXVHPgyK55rNGU+a3UYyDcy4iO5CEuv6E0AGfdUXruo3v+ 9jvSLB5AXSzY5DvJKf1sbEHh2LjDYxoqZpEpKW+V5mdr+YXq4Yu0oTqCu9NEyT+R41qeU0 kUA1PB0Y/t0qtLRQSqqv34p/RUi1hRfr16aIQLAiBVziyldvQ94MjD3Bfa6hKppWB7eCyG IwtjChPnMRitw120wzGA+z1vhWPyvgq8ZsZUYf1pHsGDei3wLvAfHVgpjT2xjg== ARC-Seal: i=2; s=key1; d=yhetil.org; t=1703627814; a=rsa-sha256; cv=pass; b=B6uKPKzomq9xB6Uyz7YqnJSPpoTKEjh0avgv6bYzMr34JhCMX3OtlsEPloEogfgwh/L0Q6 F+0sglspO9eP9k8Kl1yfLhzSQo78GH/VvBVqMPDhOgzJqjFicV9fv4kzhZjFhNg8hG6I0b nZWi8VEeE+sIx6FKUvuSEL3aCiiMB9VIij/4/VypJ6gbi6/m4MmAGeanV29ijQtINPByAm e8IYULZirPOgKo5a1sTfOplJFgq/JyAeLGA8UOuIav2B4HjfwSLtZa+MjucUMVhUxKfxl3 yVuSy3p5yZRvcfTgI8ARDMQBwS+X6I7Skt7PJxDVlUjJA59aK5S1j0XaBV792w== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=R2VaUew9; 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"; arc=pass ("zohomail.com:s=zohoarc:i=1"); 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 90C19156C0 for ; Tue, 26 Dec 2023 22:56:53 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rIFPH-0003x1-3E; Tue, 26 Dec 2023 16:56:11 -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 1rIFPF-0003wd-7g for emacs-orgmode@gnu.org; Tue, 26 Dec 2023 16:56:09 -0500 Received: from sender4-op-o15.zoho.com ([136.143.188.15]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rIFPC-0001rT-62 for emacs-orgmode@gnu.org; Tue, 26 Dec 2023 16:56:09 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1703627763; cv=none; d=zohomail.com; s=zohoarc; b=YZH7FqARqXpJ683uPuER80ZxcjGN/oHdreJufSdMQAk8btFvt4F+ZL8ZYsUoHxKu4QQ7ww4OWqbl+O1bleMNICG1kV964SZe5rBsW4hhcGAxmWnF4eBaeKwicNlfPAfDbrJGihdqA6gAYUwRlLtnSloJtVFZFVxLVulq9S+Y9us= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1703627763; h=Content-Type:Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:MIME-Version:Message-ID:References:Subject:Subject:To:To:Message-Id:Reply-To; bh=4vKa9M2UVTFEOI/+WfGNRY11Gh31qCjbL4zXbMdHQbg=; b=WS2f2S4XVdJP+kgSIMZ6L5T2mqjh6bzeW2mMWe6asH8feIsK9emfy9X2xD6UrrZxP6PLSq1mbkVdXGd9Ex3L0Qt66AZyj5pl//UM+BmswHmJXJ0ZFVUJHQbVXjzvAsLjjpvhp1CGMf1zs2lwMTUrF0np5tUM4gz+6etOhh2uayo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=excalamus.com; spf=pass smtp.mailfrom=matt@excalamus.com; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1703627763; s=zmail; d=excalamus.com; i=matt@excalamus.com; h=Date:Date:From:From:To:To:Cc:Cc:Message-ID:In-Reply-To:References:Subject:Subject:MIME-Version:Content-Type:Content-Transfer-Encoding:Message-Id:Reply-To; bh=4vKa9M2UVTFEOI/+WfGNRY11Gh31qCjbL4zXbMdHQbg=; b=R2VaUew95YcIcBsuoQ9aPwU4nQQWNvPFgGxdTDC+NjwYxCKO0UnSsgiUlgVJsBf3 tSlWsgpHJrsRx+GbIIOGS9bEVpjSaeMc7zX1Hh79vUmIvTZ8fbCvjZ0PXdQ6rzwLaQo JJUOzEWQxfnJopT8QqniCBYvv8llOM1KBFsf6cRI= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1703627760893779.135211803409; Tue, 26 Dec 2023 13:56:00 -0800 (PST) Date: Tue, 26 Dec 2023 22:56:00 +0100 From: Matt To: "Ihor Radchenko" Cc: "emacs-orgmode" Message-ID: <18ca820a475.e4d2fd59236985.7802095910982651347@excalamus.com> In-Reply-To: <87wmt1dp1c.fsf@localhost> References: <87wmt1dp1c.fsf@localhost> Subject: Re: [PATCH] org-manual: Describe export process flow MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Importance: Medium User-Agent: Zoho Mail X-Mailer: Zoho Mail Received-SPF: pass client-ip=136.143.188.15; envelope-from=matt@excalamus.com; helo=sender4-op-o15.zoho.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-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: -7.91 X-Spam-Score: -7.91 X-Migadu-Queue-Id: 90C19156C0 X-Migadu-Scanner: mx11.migadu.com X-TUID: 0yUbMMbMR97J This looks useful. My only understanding of the problem this addresses is what you wrote: > create a more clear picture on how various export hooks and filters > are used. With this understanding, my first question was, "What hooks exist?" I see that [[https://www.gnu.org/software/emacs/manual/html_node/org/Advanced= -Export-Configuration.html][Advanced Export Configuration]] gives only ~org-export-before-processing-hook~ and ~org-export-before-parsing-hook~. The section below it gives a table of filters. Here are all the hooks and functions for org-export (via =3DC-h v org-export--hooks TAB=3D and =3DC-h v org-export--function TAB=3D). I see 59 of them. | Hooks | Manual (60f357e8b) | Pa= tch | |-------------------------------------------------+--------------------+---= ----| | org-export-before-processing-hook (obsolete) | X | X = | | org-export-before-parsing-hook | X | X = | | org-export-stack-mode-hook | | = | | org-export-filter-options-functions | X | X = | | org-export-filter-parse-tree-functions | X | X = | | org-export-filter-body-functions | X | X = | | org-export-filter-final-output-functions | X | X = | | org-export-before-parsing-functions | | = | | org-export-before-processing-functions | | = | | org-export-filter-babel-call-functions | X | = | | org-export-filter-bold-functions | X | = | | org-export-filter-center-block-functions | X | = | | org-export-filter-clock-functions | X | = | | org-export-filter-code-functions | X | = | | org-export-filter-diary-sexp-functions | X | = | | org-export-filter-drawer-functions | X | = | | org-export-filter-dynamic-block-functions | X | = | | org-export-filter-entity-functions | X | = | | org-export-filter-example-block-functions | X | = | | org-export-filter-export-block-functions | X | = | | org-export-filter-export-snippet-functions | X | = | | org-export-filter-fixed-width-functions | X | = | | org-export-filter-footnote-definition-functions | X | = | | org-export-filter-footnote-reference-functions | X | = | | org-export-filter-headline-functions | X | = | | org-export-filter-horizontal-rule-functions | X | = | | org-export-filter-inline-babel-call-functions | X | = | | org-export-filter-inline-src-block-functions | X | = | | org-export-filter-inlinetask-functions | X | = | | org-export-filter-italic-functions | X | = | | org-export-filter-item-functions | X | = | | org-export-filter-keyword-functions | X | = | | org-export-filter-latex-environment-functions | X | = | | org-export-filter-latex-fragment-functions | X | = | | org-export-filter-line-break-functions | X | = | | org-export-filter-link-functions | X | = | | org-export-filter-node-property-functions | X | = | | org-export-filter-paragraph-functions | X | = | | org-export-filter-plain-list-functions | X | = | | org-export-filter-plain-text-functions | X | = | | org-export-filter-planning-functions | X | = | | org-export-filter-property-drawer-functions | X | = | | org-export-filter-quote-block-functions | X | = | | org-export-filter-radio-target-functions | X | = | | org-export-filter-section-functions | X | = | | org-export-filter-special-block-functions | X | = | | org-export-filter-src-block-functions | X | = | | org-export-filter-statistics-cookie-functions | X | = | | org-export-filter-strike-through-functions | X | = | | org-export-filter-subscript-functions | X | = | | org-export-filter-superscript-functions | X | = | | org-export-filter-table-cell-functions | X | = | | org-export-filter-table-functions | X | = | | org-export-filter-table-row-functions | X | = | | org-export-filter-target-functions | X | = | | org-export-filter-timestamp-functions | X | = | | org-export-filter-underline-functions | X | = | | org-export-filter-verbatim-functions | X | = | | org-export-filter-verse-block-functions | X | = | |-------------------------------------------------+--------------------+---= ----| * Feedback 1: How are the functions not present in the patch handled? I have no clue if they're relevant here or if someone would be confused by their absence. I only noticed that some of them were used in the patch and that the purpose of the patch also deals with filters. * Feedback 2: If I read the patch correctly, the it places the summary *before* the "Export hooks" section. This means that the summary will refer to the hooks before they're introduced (AFAICT, they're only ever mentioned in the "Export hooks" section). The summary should come after the hooks. Maybe before "Extending an existing back-end" or before the next Chapter (Publishing)? * Feedback 3: These are nitpicky things. > 1. The source Org mode buffer is copied into temporary throwaway > buffer that can be edited by export hooks "throwaway" is unnecessary because "temporary" implies it. > 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 I would write out "src" as "source". Do we have an official way to refer to source blocks? For example, we standardize on "Org": https://git.savannah.gnu.org/cgit/emacs/org-mode.git/tree/doc/Documentation= _Standards.org#n47 Capitalize "babel" since it's a name. > 8. Export option values are calculated, according to in-buffer > keywords, =3D#+BIND=3D keywords, buffer-local and global > customizations. The first comma is not necessary. The option values are calculated according to the list that follows (in-buffer keywords, BIND, etc.). Remove the trailing period or add periods to all the others. I tend leave the period of the last sentence of a list. I'm not sure of a style guide that recommends one or the other. Maybe someone knows what's "right"? > - Heading are removed according to =3DSELECT_TAGS=3D and > =3DEXCLUDE_TAGS=3D export keywords; =3Dtask=3D, =3Dinline=3D, =3Da= rch=3D export > options "Heading" should be "Headings" > 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 Maybe use "converted" instead of "transcoded"? I'm a native speaker but I wonder if "converted" is a simpler word for people who aren't. The sentence is simpler by removing the commas and rearranging, "Each transcoded AST node is passed as a string to the corresponding export filter (see [[*Filters]])"" What's an "inner" template and why does that matter? > 20. The filtered body is formatted according to backend's outer > template What's an "outer" template and why does it matter? Should "outer" be quoted like "inner" was? Or, should "inner" be unquoted? > 21. The resulting output is processed by citation backend finalizer "Finalizer" is vague. What's its significance? Does it correspond to a function the end-user might look up? Overall, great work! For each "negative" bit of feedback, there were at least two things that deserve "positive" comments. I saw no spelling errors, you wrote out abbreviations (AST) before using them, and there are no voice issues. Everything was to the point. At first I was confused why this is being added to the manual and not to Worg. However, after reading it more thoroughly, I believe it will be a welcome and helpful addition to the manual. The export process is complex! -- Matt Trzcinski Emacs Org contributor (ob-shell) Learn more about Org mode at https://orgmode.org Support Org development at=C2=A0https://liberapay.com/org-mode