Re: multipage html output

[Ihor Radchenko <yantar92@posteo.net>]

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

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

Thanks!
I will first focus on reviewing changes to ox.el.

> ox.el
> 
> - added `org-export-collect-tree-info', and

And it is not used anywhere... What is the purpose?

>   org-export-transcode-headline, extracted from `org-export-as'

How does it have anything to do with "headline"? Maybe `org-export-transcode-page'?
 
> - added :multipage case to `org-export-as', calling :process-multipage
>   callback submitted in info. In the multipage case, org-export-as
>   returns nil relying on :process-multipage to do the exporting, while
>   in the single page case it returns the transcoded string to the
>   caller from the backend.

Does it mean that you do not want page splitting to be controlled
globally, in ox.el, as we discussed?
 
> - changed `org-export-collect-footnote-definitions' to get its
>   numbering using `org-export-get-footnote-number' rather than always
>   counting from 1 as before. This should always work for single-page
>   and multipage export.

This looks reasonable. Maybe even as a separate patch we can merge earlier.
 
> - changed that `org-export-numbered-headline-p' always returns t for
>   headlines in the multipage case to ensure headline numbering is
>   collected.

>   NOTE: The single-page case will be handled like before, but it might
>   be a better idea to change the behaviour and do it the same way as
>   in the multipage case: Always collect the headline-numbering and
>   only decide at the transcoding stage whether the headline should be
>   numbered in the output.

Why? What if one wants headlines to be not numbered?

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

https://orgmode.org/worg/org-contribute.html#orge044121

You need to clone Org mode repository and modify it on a public
branch. Then, just share it. Also, please make sure that you track the
latest main branch. Your version of ox.el already diverged from the
latest main.

> 2. How do I add documentation to the org manual?

Edit doc/org-manual.org in the Org repository.

> 3. Should there be test functions for the code added and are there
>    recommendations how to do that?

Yes, ideally.
See testing/README, testing/lisp/test-ox.el, and
testing/lisp/text-ox-html.el files in the Org repo.

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