Re: multipage html output

[Orm Finnendahl <orm.finnendahl@selma.hfmdk-frankfurt.de>]

Am Montag, den 08. Juli 2024 um 15:29:47 Uhr (+0000) schrieb Ihor Radchenko:
> Orm Finnendahl <orm.finnendahl@selma.hfmdk-frankfurt.de> writes:
> 
> > For the backend I'm planning to realize the following options
> > (implemented as custom variables, which can be overwritten in the
> > document):
> >
> > - org-html-multipage-export-directory
> >
> >   The directory for the exported files (relative or absolute).
> 
> I am wondering about the reasoning behind not re-using
> #+EXPORT_FILE_NAME: here (its directory part) and simply defaulting to
>  `default-directory'.
> 
> 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.

> > - org-html-multipage-head
> >
> >   (similar to HTML_HEAD but will be used instead of the HTML_HEAD for
> >   custom css/js)
> 
> Again, why not directly using #+HTML_HEAD?

Same as above: My multipage has a completely different css and js and
I think this is unavoidable. All this is just for being able to do
both exports without interfering.

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

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

https://www.selma.hfmdk-frankfurt.de/finnendahl/klangsynthesebuch

Chapters 4, 4.8, 5, 5.4 and 6 (two Headline levels combined) and
Chapter 7 (three Headline levels combined) are examples of joined
headlines and the other (sub)chapters are examples, how Chapters
containing body text are handled. It's mainly a matter of style but in
some situations it doesn't make much sense to me to add content below
a headline just to avoid an empty page in multipage html output.

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

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

--
Orm