From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id sA8ZMXdwn2bbDQAAqHPOHw:P1 (envelope-from ) for ; Tue, 23 Jul 2024 08:57:27 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0.migadu.com with LMTPS id sA8ZMXdwn2bbDQAAqHPOHw (envelope-from ) for ; Tue, 23 Jul 2024 10:57:27 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=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"; dmarc=fail reason="SPF not aligned (relaxed), No valid DKIM" header.from=hfmdk-frankfurt.de (policy=none) ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1721725047; 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:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post; bh=K8yoR2WMNDw8lHTzUcZqAV9TNNyOipZYS9coLvKHOWw=; b=BaD1QaaVK6HtkxA3gfitv/SMY5FWYiKTDaJ1dVnVpntatsjsatOe8Qu+mV/QNXy43RZQGD ynTsu3nQnHh9FoU+CqUrb9UHmphCmhFcZpc1vjhNxgyhlRL0EPMfWho6aQicwj+VzAjqhJ jvC5q+rr98Drfc0tOBWt8zYehh4ozdhXjpEuvuGv5VJ/dcywK1S7jUmu2M5p7MUCoJcKKj DvCozhQeufulcYME0QOSwoN08YH4D3Jqf46gytKvYAT9QSB8XotZqx2weUXS8oz++8toHw g610KQaD8f/clIAyPKxv08SsjdIFzX2BLqkSsBbQRgb7J9OC58lrYWO7Ihp0+A== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=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"; dmarc=fail reason="SPF not aligned (relaxed), No valid DKIM" header.from=hfmdk-frankfurt.de (policy=none) ARC-Seal: i=1; s=key1; d=yhetil.org; t=1721725047; a=rsa-sha256; cv=none; b=rdEsdXdiqPPkb/XLLXhdLBGdTjyE7yfbULtSgeXE+OhD5Q7v3hhkaSWyuTd9rF/XZAs3MA mksMTLyEcZ8z0/OhLesEWekJZDL2wO5ZaO+lBWdSv4wPaeK4gmAU4rsd3woV19TCXOPyEv NJEJDtQU5N+J4KBZoueNFTFiH0GjuN4qNv53WLPssHjRCoEqkaPWPUF4XAsLlZS1hSyHzw wudmuO4LEb+JpeTEox+fTBhEFUDy0QxD0NFe94mZ4CEmDU/HdR+B+5H/IOypenxoiYt72Z Z2q5J1uKw6BlMbrQL7pke6WkjPkux5mqQP9K7beYanb4Fd5G1Q6Y8Lf7EzqiuQ== 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 4F70F9501 for ; Tue, 23 Jul 2024 10:57:27 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sWBJm-0000rp-83; Tue, 23 Jul 2024 04:56:22 -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 1sWBJk-0000pY-FF for emacs-orgmode@gnu.org; Tue, 23 Jul 2024 04:56:20 -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 1sWBJh-0007AP-Fy for emacs-orgmode@gnu.org; Tue, 23 Jul 2024 04:56:20 -0400 Received: by mail.selma.hfmdk-frankfurt.de (Postfix, from userid 113) id 8B983F62481; Tue, 23 Jul 2024 10:56:11 +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 5C6EFF6247F for ; Tue, 23 Jul 2024 10:56:09 +0200 (CEST) Received: by selma.hfmdk-frankfurt.de (Postfix, from userid 1000) id B7630396054C; Tue, 23 Jul 2024 10:56:07 +0200 (CEST) Date: Tue, 23 Jul 2024 10:56:07 +0200 From: Orm Finnendahl To: emacs-orgmode@gnu.org Subject: Re: multipage html output Message-ID: Mail-Followup-To: emacs-orgmode@gnu.org References: <87y16bzzxl.fsf@localhost> <87o777zxkv.fsf@localhost> <87r0c2781h.fsf@localhost> <87r0c05com.fsf@localhost> <87wmlp38gr.fsf@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <87wmlp38gr.fsf@localhost> 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-Country: US X-Migadu-Flow: FLOW_IN X-Spam-Score: -0.91 X-Migadu-Queue-Id: 4F70F9501 X-Migadu-Scanner: mx10.migadu.com X-Migadu-Spam-Score: -0.91 X-TUID: ECk/gVx0rxt7 Hi, I managed to get the proposal for the multipage output done. Please review it and let me know what you think/would prefer to change. I'm pretty open about it. You can find it here: https://github.com/ormf/ox-html-multipage The code is intended to replace ox.el and ox-html.el. The repository contains a pretty exhaustive CHANGELOG.txt to show what I did. I also found a way to tackle the problem with the correct output template by integrating both approaches into one template with the option of customizing it simply with css. Here are the two layouts, the first being just the plain output with a css styling similar to the plain singlepage output, the second with the navigation elements integrated into the main-text-body: 1. Plain https://www.selma.hfmdk-frankfurt.de/finnendahl/klangsynthesebuch-plain/ 2. Inline navigation https://www.selma.hfmdk-frankfurt.de/finnendahl/klangsynthesebuch/ My code proposal shouldn't break anything in the single-page export for any backend and produce the exact same output as before with one exception: There now is an option :html-numbered-link-format which applies to numbered links to Chapters, Sections or Images. If the link doesn't have a label, in previous versions of ox-html the link label just consisted of a number. With the chenge, the link label will be replaced by a customizable string for the three cases. The default setting now is "Chapter %s", "Section %s" and "Fig. %s", which will get translated using the org-export-dictionary (I added those entries in ox.el). The customizable strings can be set to "%s" if the previous behaviour is preferred, but I consider it an enhancement and assume, the new behaviour is preferred by most users. In addition I found a minor bug regarding infojs and implemented a more general way to determine footnote numbers (which is not a bug in single-page output, but in my opinion a more concise method aligning with the way footnote numbers are created in the first place). The new multipage output will get triggered with 'C-c C-e h m'. Whether the first page opens in a buffer, browser or the output just get written to file can be controlled with the :html-multipage-open option in the file (or as a customized variable). In addition these customizable options are implemented: - :html-multipage-head-include-default-style default css style for multipage documents. - :html-multipage-join-empty-bodies / org-html-multipage-join-empty-bodies Whether to join subheadlines on the same page in case a headline has no body text (I tried to clarify that in the doc string of the defcustom). - :html-multipage-export-directory / org-html-multipage-export-direcotry The directory for the multipage output (relative or absolute). - :html-multipage-nav-format / org-multipage-nav-format Html snippets for the top navigation elements. - :html-multipage-split / org-multipage-split Where to split the document. Possible values are 'toc to split at the toc entries or a number indicating the headline level. - :html-multipage-toc-to-top / org-html-multipage-toc-to-top link destination from toc (either directly to the headline, or to the top of the page, more convenient in the standard case with the navigation on top). I did *not* implement: - Front matter options as I think the standard tools for org mode cover most cases I thought of very elegantly and it seemed somewhat clunky to me. - Page split at section-filenames. The main reason for this is that it needs a longer discussion, how this should get implemented correctly to cover all use cases. In principle it is not very complicated, especially with my better understanding of the underlying principles of ox. But if I understand Ihor's ideas correctly, it is a separate issue altogether which won't be handled properly in the html backend but rather in a general multipage backend which is backend agnostic. I'm perfectly willing to tackle this and to contribute, but currently I think it is better to make the proposed code with applied improvements available, as it is useful and pretty complete for the use case of publishing an org document to multiple html pages. If the code gets reviewed and accepted I have some questions regarding final submittal: 1. How do I provide the code? Is there a mechanism like issuing a merge-request or how is it normally done? 2. How do I add documentation to the org manual? 3. Should there be test functions for the code added and are there recommendations how to do that? I'm glad that I finally got it done. Hope you like it and please let me know what you think. -- Orm