emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Ihor Radchenko <yantar92@posteo.net>
To: Orm Finnendahl <orm.finnendahl@selma.hfmdk-frankfurt.de>
Cc: emacs-orgmode@gnu.org
Subject: Re: multipage html output
Date: Tue, 09 Jul 2024 17:55:51 +0000	[thread overview]
Message-ID: <87ttgy78m0.fsf@localhost> (raw)
In-Reply-To: <Zow6MSUqrwYak2Qs@orm-t14s>

Orm Finnendahl <orm.finnendahl@selma.hfmdk-frankfurt.de> writes:

>> Is there any situation when you need to export the full document
>> vs. multipage to different places?
>
> Actually that is what I'm currently doing (and what I need for my
> publishing chain): The single-page document is not in the html folder
> used for the multipage document. Both files happen to have the same
> name so it wouldn't work out, if I want to generate single-page along
> the multipage version, without having to change the document.

If this is the case, users may potentially need similar diverging
settings for single- vs. multi- page documents for almost any given
export option, not just the ones you mentioned.

To address such situations, we may, for example, allow an alternative
"multi" version of each export keyword to act specially when multipage
export is used. Consider that there is an export option #+SAMPLEOPTION.
If the document has only "#+SAMPLEOPTION: value", exporter will use it
for both normal and multipage export. However, we may allow an
alternative #+SAMPLEOPTION[multipage]: multipage value that will be used
instead when defined.

In addition to defining alternative variants of in-buffer settings, we
also need to provide the equivalent feature for custom variables
defining the export options. We can do it by treating the value of such
export-related variables specially - we may allow special values like
[org-export-variants :default default-value :multipage multipage-value]
and provide helper functions like

(org-export-set-option option-name  value) ; :default
(org-export-set-option option-name :multipage value) ; for multipage export only
(org-export-set-option option-name :singlepage value) ; just for singlepage export

(Or can be some other consistent way to define alternatives; feel free
to brainstorm)

>> > - org-html-multipage-front-matter
>> >
>> >   A list to specify pages in front of the headlines of the
>> >   document. Possible values are 'title, 'title-toc and 'toc. title-toc
>> >   is a combined page containing the title and the toc. Multiple
>> >   entries are possible.
>> 
>> This sounds orthogonal to multipage export. May you please illustrate
>> what you want to achieve by introducing this option? Maybe there is an
>> existing feature that can be re-used instead of creating something new?
>
> Could be: The toc as a first page is needed, when you don't want a toc
> on the side of each html page, e.g. when using the classical info
> layout. And it might be necessary to be able to distinguish between a
> separate title page with author and the toc on the next page (or a
> combined page with title and toc or no front matter at all because the
> title appears on every page). If this is possible with already
> existing options, even better. I just think that it might be necessary
> to be able to distinguish between the needs for html output format
> vs. the needs for LaTex or single-page output without having to edit
> the document (I need that as my publishing chain is going to export
> info, html multipage, pdf output and html single-page output using the
> same org file).

Sorry, but I still do not quite understand. May you please illustrate a
bit more with some kind of simple example?

>> > - org-html-multipage-join-first-subsection
>> >
>> >   Boolean: Non-nil means that the first subsection of a section
>> >   without a body will be joined on the section page
>> >   (recursively). See my generated example pages linked below
>> >   (Chapters 4, 5 and 7 for a recursive example)
>> 
>> Sorry, but I cannot understand anything from there. May you explain in
>> words?
>
> Consider a case like this:
>
> * Headline 1
> ** Headline 2
> *** Headline 3
>     Text for Headline 3
>
> Without the above option, Headline 1, Headline 2 and Headline 3 would
> be on separate pages with Headline 1 and Headline 2 being empty pages
> with just the Headline. The option puts all three Headlines and the
> Contents of Headline 3 on the same page. See here:

I see. It sounds useful given that your strategy to split the document
into pages is "on each headline on each level".

Conceptually, I see this as one of possible customizations for paging
strategies. Your `org-html-multipage-join-first-subsection' simply tells
to split off pages only when there is non-empty contents inside the
containing headings.

This also reveals that we may sometimes want more than just to tell how
to split the document. After splitting, we may want to rearrange the
pages differently (maybe even re-order?). In other words, multipage
export may need to:

1. Take document AST
2. Split it into multiple parts
3. Filter the obtained part list (post-process)
4. Perform actual per-page export
...

>> > - org-html-multipage-split
>> >
>> >   How to split the document. Possible values are
>> >
>> >   'toc for generating a page for each toc entry.
>> 
>> May I guess that the previous option may have something do with
>> situation when #+TOC: keyword is in the middle of a text?
>
> No: In the online document of the link above the page splitting
> follows the toc (with the exception of the page joining explained
> above), meaning that each visible toc entry will generate one page. Be
> aware that this is not obvious on the online page as subfolders are
> folded automatically using the css (folded elements have the class
> "toc-hidden"). If you look at the html page source you can see that
> every page contains the full toc to enable other css or js based
> styling decisions.

Sounds reasonable. I guess that the docstring can be improved :)

>> Do I understand correctly that your alternative layout is simply a
>> question of custom #+HTML_HEADER? Or is there something more to it?
>
> In my layout the main difference is that the nav left and nav right
> elements are part of the page-main-body rather than part of
> <content>. I'm not positive this is elegantly manageable with css,
> when the navigation is outside the page-main-body.

Sorry, but I am lost. What do you mean by "content" and what do you mean
by "page-main-body"?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>


  reply	other threads:[~2024-07-09 17:55 UTC|newest]

Thread overview: 72+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-07-03  9:44 multipage html output Orm Finnendahl
2024-07-03 10:33 ` Dr. Arne Babenhauserheide
2024-07-03 10:58 ` Christian Moe
2024-07-03 11:05   ` Ihor Radchenko
2024-07-03 14:34     ` Christian Moe
2024-07-04  9:50     ` Orm Finnendahl
2024-07-04 11:41       ` Ihor Radchenko
2024-07-04 13:33         ` Orm Finnendahl
2024-07-04 16:20           ` Ihor Radchenko
2024-07-07 19:33             ` Orm Finnendahl
2024-07-08 15:29               ` Ihor Radchenko
2024-07-08 19:12                 ` Orm Finnendahl
2024-07-09 17:55                   ` Ihor Radchenko [this message]
2024-07-10 18:03                     ` Orm Finnendahl
2024-07-10 18:53                       ` Ihor Radchenko
2024-07-07 20:50             ` Orm Finnendahl
2024-07-08 15:05               ` Ihor Radchenko
2024-07-08 15:41                 ` Orm Finnendahl
2024-07-08 15:56                   ` Ihor Radchenko
2024-07-08 19:18                     ` Orm Finnendahl
2024-07-09 18:08                       ` Ihor Radchenko
2024-07-10 19:37                         ` Orm Finnendahl
2024-07-11 12:35                           ` Ihor Radchenko
2024-07-13  7:44                             ` Orm Finnendahl
2024-07-13 10:13                               ` Ihor Radchenko
2024-07-13 11:01                                 ` Orm Finnendahl
2024-07-23  8:56                                 ` Orm Finnendahl
2024-07-23 10:24                                   ` Ihor Radchenko
2024-07-23 11:35                                     ` Orm Finnendahl
2024-07-23 12:52                                       ` Ihor Radchenko
2024-07-23 14:56                                         ` Orm Finnendahl
     [not found]                                         ` <Zp_EhDDxxYRWKFPL@orm-t14s>
     [not found]                                           ` <874j8g2lvq.fsf@localhost>
2024-07-23 15:36                                             ` Orm Finnendahl
2024-07-23 14:13                                       ` Ihor Radchenko
     [not found]                                         ` <Zp_b2lL2SzDswa-w@orm-t14s>
2024-07-23 17:10                                           ` Ihor Radchenko
2024-07-23 20:35                                             ` Orm Finnendahl
2024-07-24 10:20                                               ` Ihor Radchenko
2024-07-24 11:24                                                 ` Orm Finnendahl
2024-07-25  9:49                                                 ` Orm Finnendahl
2024-07-25  9:57                                                   ` Ihor Radchenko
2024-07-25  9:57                                                 ` Orm Finnendahl
2024-07-25 10:04                                                   ` Ihor Radchenko
2024-07-25 14:59                                                     ` Orm Finnendahl
2024-07-27 19:24                                                     ` Orm Finnendahl
2024-07-27 19:39                                                       ` Ihor Radchenko
2024-08-05 16:52                                                         ` Orm Finnendahl
2024-08-05 18:22                                                           ` Ihor Radchenko
2024-08-06  7:19                                                             ` Orm Finnendahl
2024-08-06 18:47                                                             ` Orm Finnendahl
2024-08-06 20:04                                                               ` Orm Finnendahl
2024-08-10 12:32                                                               ` Ihor Radchenko
2024-08-11 10:54                                                                 ` Orm Finnendahl
2024-08-11 13:47                                                                   ` Ihor Radchenko
2024-08-11 14:44                                                                     ` Orm Finnendahl
2024-08-12  8:35                                                                       ` Orm Finnendahl
2024-08-12 17:10                                                                         ` Ihor Radchenko
2024-08-12 18:58                                                                           ` Orm Finnendahl
2024-08-17  7:21                                                                             ` Rudolf Adamkovič
2024-08-17 14:05                                                                             ` Ihor Radchenko
2024-08-19 16:31                                                                               ` Orm Finnendahl
2024-08-22 12:27                                                                                 ` Ihor Radchenko
2024-07-26  8:22                                                 ` Orm Finnendahl
2024-07-27 13:01                                                   ` Ihor Radchenko
2024-07-27 14:25                                                     ` Orm Finnendahl
2024-07-23 14:19                                       ` Ihor Radchenko
2024-07-23 15:13                                         ` Orm Finnendahl
2024-07-23 16:20                                           ` Ihor Radchenko
2024-07-23 17:02                                             ` Orm Finnendahl
2024-07-23 17:13                                               ` Ihor Radchenko
2024-07-23 19:00                                                 ` Orm Finnendahl
2024-07-03 21:11 ` Rudolf Adamkovič
  -- strict thread matches above, loose matches on Subject: below --
2024-07-06  5:47 Pedro Andres Aranda Gutierrez
2024-07-06  9:04 ` Orm Finnendahl

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87ttgy78m0.fsf@localhost \
    --to=yantar92@posteo.net \
    --cc=emacs-orgmode@gnu.org \
    --cc=orm.finnendahl@selma.hfmdk-frankfurt.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).