Re: multipage html output

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

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