From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id QCdvEOH/imYhjAAA62LTzQ:P1 (envelope-from ) for ; Sun, 07 Jul 2024 20:51:45 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:58f0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id QCdvEOH/imYhjAAA62LTzQ (envelope-from ) for ; Sun, 07 Jul 2024 22:51:45 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=fail reason="SPF not aligned (relaxed), No valid DKIM" header.from=hfmdk-frankfurt.de (policy=none); 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-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1720385505; 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; bh=NkkEfbsRFJArCrANW1AdaO+RFfXnrCDBfB6uIxdwgqk=; b=jo36I6O4PVoZlAolWJhacTw1RegvWYStXP0UcyigVZ83rMPW1bf5wNRb/zy2qPz7GfV1Ke PqDn0B/XN+axdfJADcB1+mUUmUy7iKT9mz3eCSy0pcLSuhsxMJhAVbn5wrJ3p3NDo430eQ cFVJxrOApFTdTc7KmSGRV5w+QrhRf4gDoNwlPpkVg7f6aBEtFc+Eoysq633jB9WfyutdXu YN932josNoKOj+o99Ji8gd9UjFCJIEoMxc//Ync0yrFFlQKqZVdfAGW1Kb8VpDV1ypFu9S T7rPRsdHmN9KqpkdaYQ7rtlPFB6ntzBSIaDEb+BdxTFsH20zSWqoANrFPztA6Q== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1720385505; a=rsa-sha256; cv=none; b=ts3ocPa0NfH4/juToxjwCFV3cmN/F5Wj2iavp0pXsI86PV0hN1anOhfjNW8H4IQnCxybew ovepf8ChJJ3GWQff82GJm/dQ0JlGtpbfJsjVuygLwfvKaSERnNqcj1phVr029Ntbn3wDHJ GOM5pLyxgF+XmoF01fZA4vReukXt2VS5aQ0RtvzMf9na52s7AfsMjj62LPApmuK4Nl20JW KJbRzvH2rbmqz7DTNfXo8LK9SZtc7xdCFtWB6rqH/1qpnsGh40miIdJhGmuqcBzxd5I9Yh 4tn7g8aj6RuGwpCu88uR1YXg0dx9Wuu+9IKB22oorhWQyxhLf7yqCIM6BIHuIw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; dmarc=fail reason="SPF not aligned (relaxed), No valid DKIM" header.from=hfmdk-frankfurt.de (policy=none); 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" 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 846827D810 for ; Sun, 07 Jul 2024 22:51:44 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sQYqR-0000b7-7s; Sun, 07 Jul 2024 16:50:51 -0400 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 1sQYqO-0000ay-RT for emacs-orgmode@gnu.org; Sun, 07 Jul 2024 16:50:48 -0400 Received: from www.selma.hfmdk-frankfurt.de ([46.4.92.145] helo=mail.selma.hfmdk-frankfurt.de) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sQYqM-0000sy-4m for emacs-orgmode@gnu.org; Sun, 07 Jul 2024 16:50:48 -0400 Received: by mail.selma.hfmdk-frankfurt.de (Postfix, from userid 113) id F24CFF623C2; Sun, 7 Jul 2024 22:50:42 +0200 (CEST) Received: from selma.hfmdk-frankfurt.de (ip-037-201-128-004.um10.pools.vodafone-ip.de [37.201.128.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-256) server-digest SHA256) (Client did not present a certificate) by mail.selma.hfmdk-frankfurt.de (Postfix) with ESMTPSA id C1599F6198A; Sun, 7 Jul 2024 22:50:40 +0200 (CEST) Received: by selma.hfmdk-frankfurt.de (Postfix, from userid 1000) id 5E3F93960515; Sun, 07 Jul 2024 22:50:40 +0200 (CEST) Date: Sun, 7 Jul 2024 22:50:40 +0200 From: Orm Finnendahl To: Ihor Radchenko Cc: emacs-orgmode@gnu.org Subject: Re: multipage html output Message-ID: Mail-Followup-To: Ihor Radchenko , emacs-orgmode@gnu.org References: <875xtmd9nz.fsf@christianmoe.com> <87msmypwfw.fsf@localhost> <87zfqxpeog.fsf@localhost> <87sewp9liq.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable In-Reply-To: <87sewp9liq.fsf@localhost> X-Disclaimer: Why are you listening to me? X-Operating-System: GNU/Linux Organization: Hochschule =?utf-8?B?ZsO8?= =?utf-8?Q?r?= Musik und Darstellende Kunst Frankfurt, Frankfurt, Germany Received-SPF: pass client-ip=46.4.92.145; envelope-from=orm.finnendahl@selma.hfmdk-frankfurt.de; helo=mail.selma.hfmdk-frankfurt.de X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 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: -2.79 X-Spam-Score: -2.79 X-Migadu-Queue-Id: 846827D810 X-Migadu-Scanner: mx11.migadu.com X-TUID: yF40VFzun/pM Hi Ihor, I'm trying to grasp what you are proposing and have some questions to make sure I've understood (please correct me if I'm wrong): - Your idea is to add an option to the backend definition called org-export-pages which is a plist containing information about the way to export the document in case some "multipage" option is chosen in the export dialog. - Am I right that you suggest that all these org-export-pages properties can be overwritten in the header of the org file? - If that is correct I assume multipage export should then be a generic option common to different export backends (if defined) (something like "export-as-multipage") and the question is how to specify that when exporting. Should this option just be listed in the export dialog for every export backend which supports it (like in my current approach for html) and when choosing it the rules of the current definition of org-export-pages in the current context are used? - This implies that the code handling this is done in ox.el like this: The export-pages function in ox.el =20 1. generates the parse-tree =20 2. extracts the subtrees according to the rules 3. calls org-export-to-file on the backends for each of them. 4. optionally also exports the whole document, maybe stripped from its exported sections (replaced by links, etc.) If this is the way you suggest it, it doesn't sound too complicated as most of it is done already. My only concern is that in this case org-export-pages is not really backend specific and therefore the place for it semantically shouldn't be in the definition of the backend, but separate from it. The backend should just define a general function for exporting a subtree to a file for the multipage case as this might differ from the definition for single file output of the complete parse-tree (with the name of this general multipage export function being the same in all backends which support multipage output). This would also imply a mechanism to define different org-export-pages plists and select from them before exporting by calling a generic backend-agnostic org-export-to-pages function in ox.el. This is very elegant but also somewhat different from the current layout of org-export which is single-page single-backend centered. Hmm... -- Orm Am Donnerstag, den 04. Juli 2024 um 16:20:29 Uhr (+0000) schrieb Ihor Radch= enko: > Orm Finnendahl writes: >=20 > > Sure. I'm not at all familiar with the peculiarities of other output > > backends, but see your point. If you can give any hints or have any > > ideas *how* we could find general rules for separating the subtrees, > > which cover foreseeable use cases, or devise a flexible mechanism for > > doing so, I'd be glad to help setting them up and implementing them. I > > definitely agree, the code should be as general as possible while > > providing complete backward compatibility. >=20 > I think that the easiest would be adding a new option to > `org-export-options-alist' - it is already extendable for individual > backends and allows users to tweak things via in-buffer keywords, > properties, variables, and export options. >=20 > The most generic rule would be some kind of function that takes AST > node as input and returns whether that node should be going to a separate > file or not, and if yes, tell (1) which export backend to use to export > that subtree to a file (may as well allow exporting to different > formats, while we are at it); (2) what are the export parameters to be > used for that export, (possibly) including the file path. >=20 > Then, in addition to the most generic (and most flexible) "rule being an > Elisp function", we can allow some simplified semantics to define rules. >=20 > The semantics should probably give a couple of toggles to customize: > (1) which subtrees are selected for export; (2) which export backend is > used (3) how their file names are generated; (4) (optional) how they are > represented when exporting the whole original file; e.g. whether to put > links to exported files in place of their subtrees; (5) (optional) how > the original file is represented in the exported subtrees; e.g. whether > to put backlink to parent file >=20 > The subtree selection may boil down to the usual TAGS matcher (or > function), as described in "11.3.3 Matching tags and properties" section > of the manual. This will cover the previously discussed separation based > on headline level, a tag, or a property. >=20 > The export backend selection may be realized by allowing multiple rules > with each rule defining selection/backend/file name/.... >=20 > In terms of the value semantics in Elisp, I am thinking about something > re-using backend definition format: >=20 > (setq org-export-pages > '(:selector "LEVEL=3D2+blog+TODO=3DDONE" > :backend html > ;; completely remove the exported subtree is original document > ;; is being exported. > :page-transcoder nil > ;; or :page-transcoder #'org-export-page-as-heading-with-link > :export-file-name "%{TITLE}-%{page-number}" ;; or some other kind= of template syntax > ) >=20 > '(:selector a-function-accepting-ast-node > :source-backend any=20 > :backend > (:parent html ;; `org-export-define-derived-backend'-like semant= ics > :options-alist > ;; Do not export private headings in HTML pages. > ((:exclude-tags "EXCLUDE_TAGS" nil (cons "private" org-export-e= xclude-tags) split)))) >=20 > '(:selector "+export_ascii_page" > :source-backend html ; only use this rule when exporting to html > :backend > (:parent ascii > ((template . > (lambda (contents info) > (format "Paged out from %s\n%s" > (plist-get > ;; INFO channel for parent document > (plist-get info :page-source) > :title) > (org-ascii-template contents info))))))))) >=20 > >> 2. Some backends, as you proposed, may target multipage export from the > >> very beginning. So, we need to provide some way for the backend (in > >> org-export-define*-backend) to specify that it wants to split the > >> original parse tree. I imagine some kind of option with default > >> values configured via backend, but optionally overwritten by user > >> settings/in-buffer keywords. > > > > I'll look into that and maybe I can come up with something. I was > > hesitant to propose anything as I tried to stay as limited as possible > > and not get too deep into changing things. If you have suggestions, > > please let me know. >=20 > One way could be simply adding an option like :selector above to the > backend definition. Then, it will be used as default selector: >=20 > (setq org-export-pages > (:selector default :backend html) ; export pages to html with default s= elector > ) >=20 > or even >=20 > (setq org-export-pages > (:backend html) ; export pages to html with default selector > ) >=20 > or just >=20 > ;; export using the same target backend as selected in the export menu > (setq org-export-pages t) > ;; (setq org-export-pages nil) - existing single page export > ;; (setq org-export-pages 'only-pages) - only export pages, ignore origin= al file >=20 > >> 3. Your suggestion to add a new export option for splitting based on > >> headline level is one idea. > >>=20 > >> Another idea is to split out subtrees with :EXPORT_FILE_NAME: > >> property. > > > > I'm not sure I fully understand what you mean: Do you mean specifying > > different :EXPORT_FILE_NAME: properties throughout the same document > > and then export accordingly? >=20 > Yes. It is re-using the existing idea with subtree export >=20 > 13.2 Export Settings >=20 > =E2=80=98EXPORT_FILE_NAME=E2=80=99 > The name of the output file to be generated. Otherwise, Org > generates the file name based on the buffer name and the extension > based on the backend format. >=20 > If a subtree has that property set, it is used as output file name. > Since there is usually no reason to set this property unless you also > want to export subtree to individual file, it makes sense to use this as > selector for what to export as pages. >=20 > Example: >=20 > #+TITLE: Index document >=20 > * Emacs notes > ** Emacs blog post #1 > :PROPERTIES: > :EXPORT_FILE_NAME: my-first-post > :END: > ... > ** Fleeting note at [2024-06-20 Thu 22:16] > Some notes, no need to export them. >=20 > * Personal notes > ** Personal blog post #1 > :PROPERTIES: > :EXPORT_FILE_NAME: private/personal-post-trial > :END: > ... >=20 > >> 6. I can see people flipping between exporting the whole document and > >> multipage document. We probably need some kind of easy switch in M-x > >> org-export-dispatch to choose how to export. > > > > Sure, that is the disadvantage of my proposal to make everything a > > "multipage" document. Another disadvantage is that when the user > > chooses to open the final document or display it in a buffer the user > > can't choose whether to only open/display one page or every exported > > page. In most circumstances it should be advisable to just > > open/display the first page. We can also just add a switch between > > single-page and multipage, with multipage always just exporting to > > file, but that also has disadvantages. >=20 > What to open is a minor detail, really. It can be worked out any moment > we need to. The most sensible default, IMHO, it to open dired with the > containing directory with all the exported pages. >=20 > > As the code I proposed is encapsulated in the html backend and not > > spreading all over the place, I will now first go ahead to finalize > > the existing code to a fully working setup. ASFAICT adapting that to > > other needs shouldn't require a complete rewrite. And I might be > > around for a while ;-) >=20 > I advice against doing this. > While reading your code, I saw that you used some html-specific > functions for modifications in ox.el. If you start by modifying ox.el in > Org git repo directly, simply doing "make compile" will warn about > instances of using functions not defined in ox.el. > Another advantage of editing the ox.el and using Org repository is that > you can run "make test" any time and see if you managed to break Org :) >=20 > --=20 > Ihor Radchenko // yantar92, > Org mode contributor, > Learn more about Org mode at . > Support Org development at , > or support my work at >=20