Re: multipage html output

[Ihor Radchenko <yantar92@posteo.net>]

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

>  I made the changes Ihor suggested and made all docstrings compliant
> with checkdoc. Please check whether this is now how you imagined it.

Thanks! I still have comments, but let's not focus on this minor issue
yet.

> Concerning the options stored in the org-page properties rather than
> in info I mentioned in an earlier mail, I found out it actually
> doesn't really change anything substantially or clarifies/reduces the
> code, so I decided against it.  ATM it doesn't make all that much
> sense to me.

Ok, but I am seeing

> (defun org-export-transcode-org-page (org-page _ info)
> ...
>     (let* ((body-only (org-element-property :body-only org-page))
> ...
> (put-text-property
>          0 1 :output-file (org-element-property :output-file org-page) final-output)

which is still relying upon custom properties.

> If we're nearing code completion, we could also start tackling the
> documentation. I think there should be an addition for the multipage
> filter in ox.el (under "Filter System") and maybe some other additions
> to explain the mechanism for multipage output (where?)

> Maybe I can also get some assessment what's needed in org-manual and
> what to change in order to make the doc additions proposals I made
> compliant with the rest of org-manual.

No, we are not nearing code completion.
I am just getting started on the review process.
We still need to decide and finalize the changes to export system that
we need to adapt globally, without tying it to ox-html exporter.
We are still at high-level review stage.

See the next set of comments below

> (defun org-export--annotate-info (backend info &optional subtreep visible-only ext-plist)
> ...
>     (when (plist-get info :multipage)
>       (setq tree (org-export-filter-apply-functions
>                   (plist-get info :filter-multipage)
>                   (funcall
>                    (plist-get info :multipage-split-function) tree info)

:multipage-split-function should be added to the :translate-alist I
think.  It should be documented what :multipage-split-function is
supposed to do in the docstring of `org-export-define-backend'.

I do not feel like :multipage-split-function is supposed to be export
_option_. It is more internal. That's why :translate-alist, where the
internals like templates and transcoders lie.

> (defun org-export-transcode-org-page (org-page _ info)
> ...
    > (let* ((body-only (org-element-property :body-only org-page))
    >        (info (cl-list* ;; add :tl-headline and :tl-headline-number to info
    >               :tl-headline headline
    >               :tl-headline-number
    >               (alist-get
    >                headline
    >                (plist-get info :headline-numbering))
    >               info))

May you please explain what is the purpose of constructing custom INFO
plist, what all these parameters do, and why you re-do the export again
in the transcoder discarding the CONTENTS argument provided?

> (defun org-export-transcode-org-data (data body info)
>   "Transcode DATA with BODY.  Return transcoded string.
> DATA is the top `org-data' node of the parse-tree.  INFO is the
> communication channel plist."
>   (if (plist-get info :multipage)
>       ;;; for multipage output the `org-data' node contains `org-page'
>       ;;; pseudo elements as contents, so we call `org-export-data' on
>       ;;; each of them and return the collected results.
>       (mapcar (lambda (org-page)
>                 (org-export-data org-page info))
>               (org-element-contents data))

This is not a transcoder's job to export its contents.
Please move special handling of org-page AST nodes to `org-export-data'.

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