Re: multipage html output

[Ihor Radchenko <yantar92@posteo.net>]

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

>  attached are the patches for the multipage html export proposal. The
> tgz file contains all commits after branching from the main branch to
> the org-html-multipage branch (see:
> https://github.com/ormf/org-mode/tree/org-html-multipage)

Thanks! Although creating patches is not necessary in your case - remote
git repo is good enough for me to check things.

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.

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

> +(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.")

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.

> +(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'.

> +(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.
You should probably do it in `org-html-export-to-multipage' instead.
Ideally, split function should do splitting, but not other things.

> +              ;; collect all org-pages to be exported.
> +              (plist-put info :multipage-org-pages
> +                         (cl-loop
> +                          for file in section-filenames
> +                          for tl-headline in section-trees
> +                          collect
> +                          (list 'org-page
> +                                (list :output-file (format "%s/%s" dir file)
> +                                      :tl-headline tl-headline
> +                                      :tl-headline-number
> +                                      (alist-get
> +                                       tl-headline
> +                                       stripped-section-headline-numbering))
> +                                nil))))))))

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

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