Re: multipage html output

[Orm Finnendahl]

Hi Ihor,

 it was easier than I thought, although still nasty:

https://github.com/ormf/org-mode/tree/org-html-multipage

Maybe you can check whether this is along the lines of what you had in
mind.

Am Montag, den 05. August 2024 um 18:22:22 Uhr (+0000) schrieb Ihor Radchenko:
> I am also a bit surprised that you went as far as adding documentation
> to the manual. We are a bit early into the review, so things are still
> going to change. Let's focus on the code first.

Don't be, it was just an exercise, not much work and I expect there
are probably changes. I just thought to present it for commentary.

> > +    (setq tmp-info info)
> > ...
> > +    (setq global-prop org-export-filters-alist)
> 
> I noticed temporary debug statements and some (message ...) statements
> sprinkled around. They are ok for the time being, but will need to be
> removed before merging upstream.

of course. I removed most of them now.

> > +(defvar org-export-multipage-split-functions nil
> > +  "List of functions applied when multipage output has to be split.")
> 
> Please be a bit more specific about what these functions are. Here is an
> example of a complete docstring:
> 
> (defvar org-export-filter-parse-tree-functions nil
>   "List of functions applied to the parsed tree.
> Each filter is called with three arguments: the parse tree, as
> returned by `org-element-parse-buffer', the backend, as
> a symbol, and the communication channel, as a plist.  It must
> return the modified parse tree to transcode.")

done.

> Also, please mention that `org-export-multipage-split-functions' are
> called _only_ when multipage output is requested. This means that
> `org-html-multipage-split' does not need to check :multipage property.

done.

> > +(defun org-html-transcode-org-data (data content info)
> > +  "Transcode the top org-data node of the org file to export.
> > ...
> 
> > +(defun org-html-transcode-multipage (info &optional body-only)
> > +  "Central routine transcoding to multipage output called by
> > +`org-html-transcode-org-data' called from `org-export-as'.
> > ...
> 
> I see nothing specific to HTML in these two functions.  Please, factor
> them out into ox.el. I think that they can be all merged into the
> default `org-export-transcode-org-data'.

I factored out org-html-transcode-multipage to
org-export-transcode-multipage and got rid of
org-html-transcode-multipage.

> > +(defun org-html-multipage-split (data _backend info)
> > ...
> > +        (if (not (file-writable-p dir)) (error "Output dir not writable")
> > +          (let* ((encoding (or org-export-coding-system 
> > buffer-file-coding-system))
> 
> Checking output dir does not belong here.

That was a leftover, I had already fixed but forgot to delete the
condition statement, thanks.

> 
> This is awkward.  Why not modifying DATA directly? Say, you can
> transform it into (org-data (...) (org-page ...) (org-page ...) ...).

I implemented it now by making org-page elements full citizens,
adopting their contents so that you can org-export-data on them. It
was quite nasty concerning link resolution but I found a reasonable
way to solve this.

This is just a proposal to check whether this architecture is the way
to go. I got the idea that it might be feasible to integrate all page
related properties directly into the properties of each org-page
element rather than annotating info with this information. I will look
into that in the following days as it might simplify the code
somewhat, but it won't be a drastic change (just again probably a
chasing of many nasty details ;-).

--
Orm