Feedback on the new "feature" system in org-export (was: [Pre-PATCH] Overhaul of the LaTeX preview system)

[Ihor Radchenko <yantar92@posteo.net>]

Timothy <orgmode@tec.tecosaur.net> writes:

> After months of work, Karthink and I have prepared a rather large patch-set
> completely overhauling the LaTeX preview system. I hope to have a patch set
> shortly, but in the mean time it would be good to get some more people testing
> this.
>
> To test this feature, please check out the `dev' branch of
> <https://git.tecosaur.net/tec/org-mode.git> (it’s the default branch). There are
> also some other changes there currently, but I don’t think anything is broken.

Now, after the last blocker with odt export has been addressed, I am
starting to review the patch formally for merging upstream.

One of the new core mechanisms introduced in the patch is the
"feature" system for building export preambles. It allows building the
preambles selectively, depending on the document contents and current
export configuration.

The feature is mostly designed for use in latex/beamer export where
every additional \usepackage call adds to the compile time. Not to
mention the problem when we have to limit the latex packages we use by
default in order to not create incompatibilities with user packages.

For now, I will provide some high-level feedback:

1. After not following latex-preview feature development for a while,
   with a fresh mind, I find the basic terminology rather confusing.

   When reading the new "Export features" section of the manual, and
   looking through the code, I feel that a more appropriate name for the
   "features" would be "templates" - what you call "feature
   implementations" is, at the end, very similar to Emacs skeletons, but
   with a twist that the template order is not fixed:

   (cl-defstruct (org-export-backend (:constructor org-export-create-backend)
				  (:copier nil))
     ... template-conditions templates)

2. While reading the new manual section, I have an impression that the
   feature/template system can be used in any export backend and that
   document preamble can be customized by users locally, on top of the
   backend.

   However, it is only really true for ox-latex and its derived
   backends. If one, for example, tries to use
   org-export-update-features on 'html (for example, to include some JS
   library conditionally), it will not work.

   I thus feel that the newly added section does not really belong to
   the user manual. Rather to
   https://orgmode.org/worg/dev/org-export-reference.html

3. What could make sense to expose to users (and to add to the user
   manual) is the means to customize the document preamble
   conditionally.

   Now, we have `org-latex-classes' with its awkward syntax of
   
    [DEFAULT-PACKAGES]      \usepackage statements for default packages
    [NO-DEFAULT-PACKAGES]   do not include any of the default packages
    [PACKAGES]              \usepackage statements for packages
    [NO-PACKAGES]           do not include the packages
    [EXTRA]                 the stuff from #+LATEX_HEADER(_EXTRA)
    [NO-EXTRA]              do not include #+LATEX_HEADER(_EXTRA) stuff

   I think that it could be a good idea to support an alternative syntax
   making use of feature/template system.

   Same thing for similar customizations like
   `org-cite-csl-latex-preamble' and `org-latex-engraved-preamble'

   Ideally, we should supply users with a list of templates for the most
   commonly used latex packages, formalizing LaTeX package dependencies
   and conflicts

4. The overall design of the feature/template system is solid, and we can
   extend it in case we need to. However, I am slightly concerned that
   the only user of the new system is ox-latex. I believe that we can
   test the current API better if we try to use it for real in several
   scenarios. I have the following use-cases in mind:

   + `org-latex-classes' and similar user-defined templates
   + `org-latex-template'
   + `org-beamer-template' -> this one is important as we can partially
      inherit from the latex template.
   + `org-html-template' -> something non-LaTeX

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