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 YLEpGhQ9jGWi0AAAkFu2QA (envelope-from ) for ; Wed, 27 Dec 2023 16:04:52 +0100 Received: from aspmx1.migadu.com ([2001:41d0:303:e16b::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id GMQlFxQ9jGVGTQAAqHPOHw (envelope-from ) for ; Wed, 27 Dec 2023 16:04:52 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b="IiPD/C8N"; 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=pass ("zohomail.com:s=zohoarc:i=1") ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1703689492; 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=4km9znORVskDcIE2Ox8wC7R3ZIWDocXYbCGPctkOFyI=; b=nntOluznOmh8wmI9VvOf7EtivJ7NYShXlBJkwvehfWvzTUNWxJKnYKh7qn12wfsXIfda6o tVZ5cVtaG9Ib/fKn9rxAAYEAGGvXhPUmlgK7DSypSMFsRNESKNothYmYfeg2zXQfh6L/Uu 8zI2ooQKYSFvYT9Wy4Yxf/QO1ODg9uC/ZTC1BO2Ges1DeWYCLrNZwtaCps3fAJjIKq6gdz 8vVdFcP+EatCKvdhYhfjVELgXg+JovlcLgmRPFhJQ794HxwSdxKGrQSvsOJPyO+UkLohYs U3yvp8kYhAe/lvANhCkthf9VgHI5nM7jMIPRD26OQgVCZLeWOYkEPelS6VLZyQ== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b="IiPD/C8N"; 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=pass ("zohomail.com:s=zohoarc:i=1") ARC-Seal: i=2; s=key1; d=yhetil.org; t=1703689492; a=rsa-sha256; cv=pass; b=ZmUpLqmvMGRT4DKJwEbmzA4bHrQphEYQAwB8Wpltn7B/UKYMKI/Ks8QyUwaqFgipdH5f1Z hTSVXQ5GsAow6f5p5YELUnXMTzXohqM2YWOd6g5OTluywm63pOC+hgkvMalF1cDnU/gwMJ /VCTTHdA18dYNFiP9u0CwDPLvcD9vnI8ABCyXAx+zM4prl98og+BD9e0bpRpCG3o5ssHJm zy9Qj1mjRi+plKP5BoF42DvUSKf9hJhT8Yf6crj+p2CzVzN2NecgnZg1Xl4SMA5QXplDsw SxR0vJ2jILK8oUvbgDQLCX9+Ojl1y1zPc6cPSY54KqglB/tcYzgGioETQLsx8g== 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 EC6FC3FBDE for ; Wed, 27 Dec 2023 16:04:51 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rIVRg-0005a3-Fv; Wed, 27 Dec 2023 10:03:44 -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 1rIVRf-0005Zv-G7 for emacs-orgmode@gnu.org; Wed, 27 Dec 2023 10:03:43 -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 1rIVRc-0006vz-1N for emacs-orgmode@gnu.org; Wed, 27 Dec 2023 10:03:43 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1703689408; cv=none; d=zohomail.com; s=zohoarc; b=RChgtMjRGSSDrKSuhbAF00KzuREcvkLU3ZrtjASRJuufRSmDvQh7Pv/7gy4WDwg1mFv3wnlpbt7k410JiqMwUc4/5whqpdAfjBN43kUQJFRqJdTrPqYI0EWTrZ6qt1bNKNbVr0oGnTWPRGlWMyNb1B9Qp70HGhPhjZdLqkRkE2k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1703689408; 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=4km9znORVskDcIE2Ox8wC7R3ZIWDocXYbCGPctkOFyI=; b=Nw+xcsYGwpDFMRp9TBmFL4jecfzsKaEBOTQgMHT54xHUh628f06sogO3g2mPjaRTtIIKF/YUsE4eSIbrQDCM89dtLEt34KeugwAgIBh6i04QtUoYXNtC24EckG1iYp92oOo+JZNSVfEC+W/yQSngeVgSzuxozINFUJPK811Wv/g= 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=1703689408; 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=4km9znORVskDcIE2Ox8wC7R3ZIWDocXYbCGPctkOFyI=; b=IiPD/C8NnmdllH/PElWDbHA/MKbxoKBkVh0ePOJcTvZOziqOo7JADa/p/TQ+/+BS XqtgIVJyRkgSeC1Zw83DrJNitjsd1YGfq7jQGAUyihQBr4wXDQwjeNeFlgSn0UHVxr6 Ct8is3xkGwDCwPnM+aK4s+LKRx4wjjmiQ+qV8U7c= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1703689404826743.8398036436188; Wed, 27 Dec 2023 07:03:24 -0800 (PST) Date: Wed, 27 Dec 2023 16:03:24 +0100 From: Matt To: "Ihor Radchenko" Cc: "emacs-orgmode" , "Thomas S. Dye" , "Karthik Chikmagalur" Message-ID: <18cabcd4180.110e4d2ac424365.1929818377821430813@excalamus.com> In-Reply-To: <87le9fep69.fsf@localhost> References: <87wmt1dp1c.fsf@localhost> <87le9fep69.fsf@localhost> Subject: Re: [PATCH v2] 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-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Scanner: mx13.migadu.com X-Migadu-Spam-Score: -7.91 X-Spam-Score: -7.91 X-Migadu-Queue-Id: EC6FC3FBDE X-TUID: FyM1Pc0asTxf ---- On Wed, 27 Dec 2023 14:41:32 +0100 Ihor Radchenko wrote ---=20 =20 > Thank you all for the feedback! Thanks for taking the time to write and revise the patches. You didn't explicitly ask for more feedback, so I hope the following feedba= ck on the new patches is in order. Both patches look good. I see no issues with v2-0001-doc-org-manual.org-Fix-some-obsolete-variable-nam.patch For v2-0002-doc-org-manual.org-Describe-export-flow.patch here are some quibbles: > On high-level, the export process consists of 4 major steps: I don't think "On high level" is necessary (it's also missing an 'a'; "On *a* high level"). "Major" implies high-level. "The export process consists of 4 major steps:" If you wanted to keep "high-level", you could replace major with it: "The export process consists of 4 high-level steps:" > 2. Parse the buffer, converting plain Org markup into abstract syntax > tree (AST); Missing "an": "...converting plain Org markup into *an* abstract syntax..." > 5. Parse the accessible portion of the temporary buffer to generate > AST. The AST is a nested list of lists representing Org syntax > elements "...of the temporary buffer to generate *the* AST." or "...of the temporary buffer to generate *an* AST." > Past this point, modifications in the temporary buffer copy no > longer affect export; Org export works only with the AST; Replace "in the" with "to the". "no longer affect export" -> "no longer affect *the* export" Replace "temporary buffer copy" with "temporary buffer" or "temporary copy". "Past this point, modifications to the temporary buffer no longer affect the export; Org export works only with the AST;" > 6. Remove elements that will not be exported from the AST: "Remove elements that are not exported from the AST:" or "Remove elements not exported from the AST:" > - Headings according to =3DSELECT_TAGS=3D and =3DEXCLUDE_TAGS=3D expo= rt > keywords, and =3Dtask=3D, =3Dinline=3D, =3Darch=3D export options (= see > [[*Export Settings]]); Remove comma after "keywords": "Headings according to =3DSELECT_TAGS=3D and =3DEXCLUDE_TAGS=3D export keywords and =3Dtask=3D, =3Dinline=3D, =3Darch=3D export options (see [[*Ex= port Settings]]);" > - Clocks, drawers, fixed-width environments, footnotes, LaTeX > environments and fragments, node properties, planning lines, > property drawers, statistics cookies, timestamps, timestamps, > etc according to =3D#+OPTIONS=3D keyword (see [[*Export Settings]])= ; "timestamps" is written twice. > - Table columns containing recalc marks (see [[*Advanced features]]). This is indented two spaces more than the previous item. Is that what you want? > 7. Expand environment variables in file link AST nodes, according to > the =3Dexpand-links=3D export option (see [[*Export Settings]]); Comma after "nodes" not necessary. "Expand environment variables in file link AST nodes according to the =3Dexpand-links=3D export option (see [[*Export Settings]]);" > 8. Execute ~org-export-filter-parse-tree-functions~. These > functions can modify AST by side effect; I would say "*the* AST" and make "side effect" plural: "...can modify *the* AST by side effect*s*;" > 4. Convert the nodes with children to text, passing the nodes > themselves and their contents to the corresponding transcoders > and then to export filters (see [[*Filters]]). Add a "the": "...and then to *the* export filters (see [[*Filters]])." ----- Checking ox.el, I see that the commentary says, ";; See for ;; more information." Maybe also let maintainers know about this manual section: "See: " ----- Again, good work. AFAIU, you used "affect" and "effect" correctly. Breaking the big list into smaller ones makes it much easier to read. -- 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