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 OA1sCJNojGV9ZgAAkFu2QA (envelope-from ) for ; Wed, 27 Dec 2023 19:10:27 +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 uIJgBZNojGUqQgEAqHPOHw (envelope-from ) for ; Wed, 27 Dec 2023 19:10:27 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=dqV0+fLN; 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=1703700210; 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=g6K5B3n3J+/CMHbweJKTYao6PBG4iCx21aD+F4mHoXI=; b=sA41nLyHzNRZc/5mHNxK/OGxPqnZyGWerem4CPzLLmgMplmfv71aDWve1OMj0izq/3sTdy kOcwO2Sohww4Bg0Vmj6QaT7oLNP7jfq45wn6rMJmy8axBB51AI7HzoZ+7W8spvE4Bj/LJE rPLcqUBsgxmf+d9xOz7TsknruRir0GF6Ri1KOmwk7XI3iMKdzdv+E3fIScvnhNdcdkx64O rqjFR3iS2l4iKiemTuZpLQ1WYYgoT0r1UoUFOZ6W9KZGwPZf0N9+TJOj/s3ELyq9r1mkHV 9DXeH+10fYMypiVdoiO52EtnyYEzaibefCUVWdP8tMQFXm+Q5bMRkXj6IrvXGA== ARC-Seal: i=2; s=key1; d=yhetil.org; t=1703700210; a=rsa-sha256; cv=pass; b=H7U+nYc/9mT3kTF3FjYuaCKjCf0Jc6lHmiUdO7JQunV9TwndAUiOjXU6eL7WcLqnKWkfb6 UqFz2xPRHhpOe057CZiqzEAE14djH88fudd+DgT/g51vUWC0mgPdj7mFdelUriVKtj2aO7 XcJKTgnDQ6SdnI1byflms7HqKCvrP4vWWpfjSNW64+EdSUkUakiAuCZmxvwy1YRaOfRq+F WPXk2a9HZE57cE+doq0D1WGNVMelXnqk/cOQrjGlTbBtQzDB+qst5rILA7V3aE+EiU5oMa Yto323NpRwShZxSMQNr7F+065NaPGlz7dZAWXvtCXnNOeWHFx1MP+uAk6ruMRg== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=dqV0+fLN; 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") 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 4EE1F36BC7 for ; Wed, 27 Dec 2023 19:03:30 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rIYEf-0005Ib-DO; Wed, 27 Dec 2023 13:02:29 -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 1rIYEd-0005IQ-9V for emacs-orgmode@gnu.org; Wed, 27 Dec 2023 13:02:27 -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 1rIYEb-0007Mm-CV for emacs-orgmode@gnu.org; Wed, 27 Dec 2023 13:02:27 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1703700140; cv=none; d=zohomail.com; s=zohoarc; b=Qwo3HoazTQ4pi/CCNjIwWZFWc8YsiBAGLnpHKAesbMznYisQnMUvHMhY9Bljep7t1G0lXLQ5vkbNj1wnJhW44ZTBPEeVh0pPpHA4jXA2laNGT69c4e9klB8UNMyHEXe5Td7RMecDIBxubp4yrHb/ft6NwMTGh/Zpt2vUsHTHB/8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1703700140; 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=g6K5B3n3J+/CMHbweJKTYao6PBG4iCx21aD+F4mHoXI=; b=iRsRKtUHafrKPQAHJY1Lp4xwiN8IbzoxBBHX7wCJTSWzXRTg23qNE11UPKR+Xp9r3axyqkq6+8kY+TG7kO/6wnK9mK4wWFq/f8eXEUrDEklnboGUy0vOl5WkOrr2vcex27R8D4Lo4ICgRnk564v1FxC+285mWaEQRr7Yi9nFoZA= 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=1703700140; 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=g6K5B3n3J+/CMHbweJKTYao6PBG4iCx21aD+F4mHoXI=; b=dqV0+fLNi1TQnvaTRdfRa5mW48+QL8+JaxGFevziEchPywPu09bKdGfjMYPfZndl LtFnM4//LatIpe6Yf27GidQoHaegakvzc0YX6TubSzrvbOZzfw2YftZmVp0KxIgF84p gvuy7E3Heksnl/d3lYdUYM5kRJnKED/AJcfz60cU= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1703700138029544.1972727147671; Wed, 27 Dec 2023 10:02:18 -0800 (PST) Date: Wed, 27 Dec 2023 19:02:18 +0100 From: Matt To: "Ihor Radchenko" Cc: "emacs-orgmode" Message-ID: <18cac710817.e615cdf1468737.687007161508493949@excalamus.com> In-Reply-To: <87frznefpn.fsf@localhost> References: <87wmt1dp1c.fsf@localhost> <87le9fep69.fsf@localhost> <18cabcd4180.110e4d2ac424365.1929818377821430813@excalamus.com> <87frznefpn.fsf@localhost> Subject: Re: [PATCH v3] 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: -10.29 X-Spam-Score: -10.29 X-Migadu-Queue-Id: 4EE1F36BC7 X-Migadu-Scanner: mx12.migadu.com X-TUID: pLaBuxsX7ktc ---- On Wed, 27 Dec 2023 18:05:05 +0100 Ihor Radchenko wrote ---=20 =20 > Matt matt@excalamus.com> writes: > > Checking ox.el, I see that the commentary says, > > > > ";; See https://orgmode.org/worg/dev/org-export-reference.html> for > > ;; more information." > > > > Maybe also let maintainers know about this manual section: > > > > "See: > > https://orgmode.org/worg/dev/org-export-reference.html > > some-kind-of-reference-to-the-new-manual-section > > " >=20 > AFAIU, you are asking to add it to WORG page. However, it is too early. > The online Org manual that we can link to is only for stable Org > version. So, only after the next release. I was making a different point. I was trying to say that it may be a good idea for the ox.el commentary section to specifically reference the new manual section (next to where it references Worg). The new manual section is unique in that it gives detailed steps about the order of execution. Without knowing the code (so I may be mistaken), it seems like a risk that the ox.el code and manual could get out of sync. This is why I wouldn't suggest documenting the execution order for something like source blocks. However, since end-users have a lot of flexiblity in customizing the export process, it's helpful for them to understand it. It makes sense to add the new manual section. Mentioning the new manual section in the ox.el commentary would help someone new to the ox.el code. It may also help keep the new manual section and ox.el aligned (should anything in the execution order/process change in ox.el) by reminding someone changing the code that there's a manual section specifically about *how* the code works. -- 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