Re: multipage html output

[Orm Finnendahl]

Am Dienstag, den 09. Juli 2024 um 17:55:51 Uhr (+0000) schrieb Ihor Radchenko:
> 
> 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)

Yes. Currently I' more concerned with the architecural
layout. Everything else is a matter of taste and easily configured
(and hopefully agreed upon) once the structure is done. I'm very
relaxed and unopinionated about how to handle options as long as they
don't involve changing the org document for each export backend.

> >> > - 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?

Consider a doucument like this:

** Headline 1
** Headline 2
*** Subheadline 2.1

In the multipage export you want a front page with booktitle, author,
date, etc. (maybe even an image...) and as a second page after the
front page you want to have a full toc. Both pages should be reachable
by the side toc but shouldn't get numbered so the toc on the side
would appear like this:

My Booktitle
Contents
1 Headline 1
2 Headline 1
  2.1 Subheadline 1

On the other hand you might always print the booktitle on every page
and as the toc is always at the side you might not need titlepage and
toc as seperate pages.

Or you like the layout of the info mode with just navigation buttons
and no side toc. In these documents, the toc is normally on the first
"home" page. This would also imply a seperate html page with a toc and
possibly the title on it. As there are always different preferences
for this I thought to introduce a list which specifies, what king of
documents should appear at the front of the document which aren't
counted in the toc. All these are -in my opinion- legitimate decisions
not at all unusual in publication situations so I thought I accomodate
for that. Is my explanation somewhat clearer?

> 
> >> > - 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
> ...

yes. we can build a complete machinery around all that, but currently
I fear that this gets a bit out of control for me: I really have to
get going with other things and currently I'd prefer to realize
something that works with the architecture built in way that it is
easlily extendable in the future without having to redo everything
again.

> 
> >> > - 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"?

Look at the tags and ids of the html code on these pages.


--
Orm