emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [POLL] Naming of "export features"
  2023-02-10 17:20 [PATCH] Introduce " Timothy
@ 2023-02-21 14:22 ` Timothy
  2023-02-22  1:46   ` Dr. Arne Babenhauserheide
  2023-02-22 12:23   ` Ihor Radchenko
  0 siblings, 2 replies; 22+ messages in thread
From: Timothy @ 2023-02-21 14:22 UTC (permalink / raw)
  To: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 1470 bytes --]

Hi All,

In <https://list.orgmode.org/87lel4gm6b.fsf@gmail.com> progfolio/no-wayman
suggested renaming “export features” to “export contexts”. The difficultly
mainly lies with the fact that we are trying to name two very distinct
components that together provide the functionality I have called “export
features” (see the attached diagram).

To give a recap on the main points raised to/by me so far:
⁃ Doing things based on the state of a document can be described as acting based
  on the “context” of the export, and in this way “export contexts” is a
  reasonable description.
⁃ Providing capabilities via snippets can be framed as akin to dynamically
  gaining a feature.

Both components are crucial to the overall system, however if anything I view
the latter as more important and so am not a fan of describing this system as
“export contexts”. That said, I am open to considering alternatives.

Here is a list of terms which I’d feel comfortable applying to the system:
⁃ export features
⁃ export capabilities
⁃ export snippets

All are imperfect in different ways, and so any choice is a compromise. Let me
know if you have any thoughts.

All the best,
Timothy

-- 
Timothy (‘tecosaur’/‘TEC’), 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/tec>.

[-- Attachment #2: org-export-naming-difficulty.png --]
[-- Type: image/png, Size: 58703 bytes --]

^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-21 14:22 ` [POLL] Naming of " Timothy
@ 2023-02-22  1:46   ` Dr. Arne Babenhauserheide
  2023-02-22  2:40     ` Timothy
  2023-02-22 12:23   ` Ihor Radchenko
  1 sibling, 1 reply; 22+ messages in thread
From: Dr. Arne Babenhauserheide @ 2023-02-22  1:46 UTC (permalink / raw)
  To: Timothy; +Cc: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 826 bytes --]


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

> Both components are crucial to the overall system, however if anything I view
> the latter as more important and so am not a fan of describing this system as
> “export contexts”. That said, I am open to considering alternatives.
>
> Here is a list of terms which I’d feel comfortable applying to the system:
> ⁃ export features
> ⁃ export capabilities
> ⁃ export snippets

From the four, "contexts" sounds the most intimidating to me.

Snippets would conflict in meaning with yasnippet.

It also looks to me as if features may be too generic.

If I understand it correctly, this is conditional enrichment.

Maybe something like export adaption?

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-22  1:46   ` Dr. Arne Babenhauserheide
@ 2023-02-22  2:40     ` Timothy
  2023-02-23 15:55       ` No Wayman
  0 siblings, 1 reply; 22+ messages in thread
From: Timothy @ 2023-02-22  2:40 UTC (permalink / raw)
  To: Dr. Arne Babenhauserheide; +Cc: emacs-orgmode

[-- Attachment #1: Type: text/plain, Size: 847 bytes --]

Hi Arne,

Thanks for your comments.

> From the four, “contexts” sounds the most intimidating to me.
>
> Snippets would conflict in meaning with yasnippet.
>
> It also looks to me as if features may be too generic.
>
> If I understand it correctly, this is conditional enrichment.
>
> Maybe something like export adaption?

I hadn’t thought of applying the term “enrichment”. That or adaptation could be
 a good fit. I think I like the sound of “enriching the export”, and I could
 probably also be sold on “export adaptation” / “adaptive export”.

All the best,
Timothy

-- 
Timothy (‘tecosaur’/‘TEC’), 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/tec>.

^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-21 14:22 ` [POLL] Naming of " Timothy
  2023-02-22  1:46   ` Dr. Arne Babenhauserheide
@ 2023-02-22 12:23   ` Ihor Radchenko
  2023-02-23 15:31     ` No Wayman
                       ` (2 more replies)
  1 sibling, 3 replies; 22+ messages in thread
From: Ihor Radchenko @ 2023-02-22 12:23 UTC (permalink / raw)
  To: Timothy; +Cc: emacs-orgmode

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

> Here is a list of terms which I’d feel comfortable applying to the system:
> ⁃ export features
> ⁃ export capabilities
> ⁃ export snippets

I am looking at the concept again, and I feel that we may be missing
some flexibility here. I do not like the fact that each feature can only
have a simple implementation within specific backend.

Imagine that we would like add a top _and also_ bottom comment when the
Org buffer contains emoji. With the proposed patch, it will be
impossible.

I am thinking about something conceptually similar, but more general.

Instead of detecting "features" in the whole document, let's consider
that for every exported Org element (including org-data, representing
the whole document) we may emit different export output depending on
certain condition being satisfied for either original Org raw source of
the exported element, the element AST, or the exported element contents.
Let's call it "transcoder conditions".

What I have in mind is an ability to parametrize the transcoders like
the following:

(org-export-define-backend 'html
 '((paragraph . ((paragraph-is-a-link? figure-transcoder :name figure)
                 (:unless 'figure paragraph-transcoder))))
 :transcoder-conditions
 '((paragraph . ((paragraph-is-a-link? (lambda (paragraph contents info)...))))))

Several ideas in the above:
1. Name features as "transcoder conditions"
2. The transcoder conditions are now linked to specific Org AST element.
   They may not only be matched against the whole parse tree + whole raw
   Org text, but also against the specific branch of AST + chunk of raw
   Org text corresponding to the branch + the actual exported contents
   of the AST children.
3. "feature implementations" are no longer needed. Instead, export
   transcoders can contain the implementation lists inline. Each
   implementation is selected not only depending on the presence of the
   "feature"/transcoder condition, but also depending on multiple
   features or arbitrary lisp expression results.
4. :when/:prevents apply to specific (possibly named) implementations.
   This makes more sense than matching against feature.
   For example, presence of svg images in latex export may or may not
   mean that \usepackage{svg} is being used, depending on svg
   implementation. We want to match against \usepackage{svg}
   specifically rather than only against the presence of svg images.

WDYT?

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
       [not found] <mailman.336.1676990100.5072.emacs-orgmode@gnu.org>
@ 2023-02-23 15:06 ` No Wayman
  0 siblings, 0 replies; 22+ messages in thread
From: No Wayman @ 2023-02-23 15:06 UTC (permalink / raw)
  To: emacs-orgmode


> ⁃ Providing capabilities via snippets can be framed as akin to 
> dynamically
>   gaining a feature.

I understand some snippets may be used to, for example, include a 
latex package.
However, it's not a requirement that a snippet "add a 
feature/capability" to a document.
What that snippet does depends entirely on the context of the 
export (a latex snippet will not "do" anything if inserted in an 
HTML doc).
What if I want to add some metadata or a string like "Hi, Mom" in 
the preamble of the document? Would it be reasonable to say the 
document has had the "secret mom greeting" capability added, or is 
that an overly complicated way of framing it?
Is the snippet required to have a side-effect on the document?

On the obverse, the snippets are always being added depending on 
the context of the export.
`ox-contextual-snippets` is a much more concrete name than any of 
the others proposed.

> Both components are crucial to the overall system, however if 
> anything I view
> the latter as more important and so am not a fan of describing 
> this system as
> “export contexts”.

How is the latter more important if it depends on the former?

As I mentioned off list, I think naming is only part of the 
problem.
The design and API are currently over-engineered.
That should be discussed before worrying about the name.


 




^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-22 12:23   ` Ihor Radchenko
@ 2023-02-23 15:31     ` No Wayman
  2023-02-23 16:04     ` Bruce D'Arcus
  2023-02-23 19:55     ` Sébastien Miquel
  2 siblings, 0 replies; 22+ messages in thread
From: No Wayman @ 2023-02-23 15:31 UTC (permalink / raw)
  To: yantar92; +Cc: emacs-orgmode, orgmode


>Ihor Radchenko <yantar92@posteo.net> writes:
>
>I am looking at the concept again, and I feel that we may be 
>missing
>some flexibility here. I do not like the fact that each feature 
>can only
>have a simple implementation within specific backend.

Agreed

> What I have in mind is an ability to parametrize the transcoders

This seems like a step in the right direction.


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-22  2:40     ` Timothy
@ 2023-02-23 15:55       ` No Wayman
  2023-02-23 16:17         ` No Wayman
  0 siblings, 1 reply; 22+ messages in thread
From: No Wayman @ 2023-02-23 15:55 UTC (permalink / raw)
  To: orgmode; +Cc: arne_bab, emacs-orgmode


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

> I hadn’t thought of applying the term “enrichment”. That or 
> adaptation could be
> a good fit. I think I like the sound of “enriching the export”, 
> and I could
> probably also be sold on “export adaptation” / “adaptive 
> export”.

Both are horribly abstract in my opinion.
If the aim is to sound overly technical and vague, we should take 
a page from web design and call it "progressive export 
enhancements". /s


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-22 12:23   ` Ihor Radchenko
  2023-02-23 15:31     ` No Wayman
@ 2023-02-23 16:04     ` Bruce D'Arcus
  2023-02-23 19:04       ` Ihor Radchenko
  2023-02-23 19:55     ` Sébastien Miquel
  2 siblings, 1 reply; 22+ messages in thread
From: Bruce D'Arcus @ 2023-02-23 16:04 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: Timothy, emacs-orgmode

On Wed, Feb 22, 2023 at 7:23 AM Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Timothy <orgmode@tec.tecosaur.net> writes:
>
> > Here is a list of terms which I’d feel comfortable applying to the system:
> > ⁃ export features
> > ⁃ export capabilities
> > ⁃ export snippets
>
> I am looking at the concept again, and I feel that we may be missing
> some flexibility here. I do not like the fact that each feature can only
> have a simple implementation within specific backend.

I'm not really following this discussion, but is this perhaps similar
to pandoc/djot's notion of "filters"?

https://github.com/jgm/djot.js#filters

Bruce


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-23 15:55       ` No Wayman
@ 2023-02-23 16:17         ` No Wayman
  0 siblings, 0 replies; 22+ messages in thread
From: No Wayman @ 2023-02-23 16:17 UTC (permalink / raw)
  To: No Wayman; +Cc: orgmode, arne_bab, emacs-orgmode


And to add:

https://books.google.com/ngrams/graph?content=adaption%2Cadaptation%2Ccontext%2Cenhancement%2Cenrichment%2Cfeature&year_start=1800&year_end=2019&corpus=en-2019&smoothing=3

It appears context is king.
All that aside, I think Ihor's proposal sidesteps the whole issue 
while addressing the complexity of the implementation.


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-23 16:04     ` Bruce D'Arcus
@ 2023-02-23 19:04       ` Ihor Radchenko
  0 siblings, 0 replies; 22+ messages in thread
From: Ihor Radchenko @ 2023-02-23 19:04 UTC (permalink / raw)
  To: Bruce D'Arcus; +Cc: Timothy, emacs-orgmode

"Bruce D'Arcus" <bdarcus@gmail.com> writes:

> I'm not really following this discussion, but is this perhaps similar
> to pandoc/djot's notion of "filters"?
>
> https://github.com/jgm/djot.js#filters

Nope. Filters are org-export-filters-alist.

What we are talking about is a generic way to test Org buffer contents +
AST and including/not including something into export output according
to the test result.

Like,

1. If there are images in Org source, include image-related CSS into
   resulting html
2. If exported paragraph consists of a single image, export it as latex
   "figure" environment. Otherwise, export as proper paragraph.
3. If we include \usepackage{foo} in latex export, there is no need to
   \usepackage{bar} because "foo" loads "bar" anyway.

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-22 12:23   ` Ihor Radchenko
  2023-02-23 15:31     ` No Wayman
  2023-02-23 16:04     ` Bruce D'Arcus
@ 2023-02-23 19:55     ` Sébastien Miquel
  2023-02-24 10:27       ` Ihor Radchenko
  2 siblings, 1 reply; 22+ messages in thread
From: Sébastien Miquel @ 2023-02-23 19:55 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

Hi,

Ihor Radchenko writes:
> What I have in mind is an ability to parametrize the transcoders like
> the following:
> 
> (org-export-define-backend 'html
>   '((paragraph . ((paragraph-is-a-link? figure-transcoder :name figure)
>                   (:unless 'figure paragraph-transcoder))))
>   :transcoder-conditions
>   '((paragraph . ((paragraph-is-a-link? (lambda (paragraph contents info)...))))))
> 
> Several ideas in the above:
> 1. Name features as "transcoder conditions"
> 2. The transcoder conditions are now linked to specific Org AST element.
>     They may not only be matched against the whole parse tree + whole raw
>     Org text, but also against the specific branch of AST + chunk of raw
>     Org text corresponding to the branch + the actual exported contents
>     of the AST children.
> 3. "feature implementations" are no longer needed. Instead, export
>     transcoders can contain the implementation lists inline. Each
>     implementation is selected not only depending on the presence of the
>     "feature"/transcoder condition, but also depending on multiple
>     features or arbitrary lisp expression results.
> 4. :when/:prevents apply to specific (possibly named) implementations.
>     This makes more sense than matching against feature.
>     For example, presence of svg images in latex export may or may not
>     mean that \usepackage{svg} is being used, depending on svg
>     implementation. We want to match against \usepackage{svg}
>     specifically rather than only against the presence of svg images.

What benefits does that bring over making enabled features available in 
=info= for the usual transcoders and advising them ?

Your initial example of adding a comment to the end and beginning of the 
document can be done by advising, say, =org-latex-template= and 
concatenating some strings with its =content= argument.

-- 
Sébastien Miquel


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-23 19:55     ` Sébastien Miquel
@ 2023-02-24 10:27       ` Ihor Radchenko
  2023-02-24 12:46         ` Sébastien Miquel
  0 siblings, 1 reply; 22+ messages in thread
From: Ihor Radchenko @ 2023-02-24 10:27 UTC (permalink / raw)
  To: sebastien.miquel; +Cc: emacs-orgmode

Sébastien Miquel <sebastien.miquel@posteo.eu> writes:

> What benefits does that bring over making enabled features available in 
> =info= for the usual transcoders and advising them ?

We should indeed make the features/condition available via info.
However, advising is (1) bad practice unless we have no choice; (2) not
as flexible. I will illustrate below.

> Your initial example of adding a comment to the end and beginning of the 
> document can be done by advising, say, =org-latex-template= and 
> concatenating some strings with its =content= argument.

What you suggest is indeed an OK alternative for my specific example of
adding text to the beginning/end of the document.

However, it will be much harder to add something in the middle of the
exported contents.

Consider that you want to redefine a LaTeX command after certain
\usepackage{foo} call in LaTeX preamble, but before another
\usepackage{bar} call.

Let's assume that the preamble template has the following:

(:template .
 (...
  (:name 'foo :snippet "\\usepackage{foo}")
  ...
  (:name 'bar :snippet "\\usepackage{bar}")
  ...))

Now, we can simply add the following snippet to the template:

(:snippet "<define LaTeX command>" :after 'foo :before 'bar)

and the definition will be automatically inserted at the right place in
the middle of the LaTeX preamble.

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-24 10:27       ` Ihor Radchenko
@ 2023-02-24 12:46         ` Sébastien Miquel
  2023-02-24 13:03           ` Ihor Radchenko
  0 siblings, 1 reply; 22+ messages in thread
From: Sébastien Miquel @ 2023-02-24 12:46 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

Ihor Radchenko writes:
> However, it will be much harder to add something in the middle of the
> exported contents.

I do like the original proposal. The latex preamble is something that
a lot of users will want to modify, and is naturally made of a lot of
concatenated snippets with little interdependence. But I don't see
much point in extending the machinery for any org element.

For most changes, you'll have to copy and modify the original
transcoder's implementation anyway. At this point, you might as well
write the feature logic in lisp (checking features through =info=),
instead of your `transcoder-conditions`.

-- 
Sébastien Miquel


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-24 12:46         ` Sébastien Miquel
@ 2023-02-24 13:03           ` Ihor Radchenko
  2023-02-24 21:38             ` Sébastien Miquel
  0 siblings, 1 reply; 22+ messages in thread
From: Ihor Radchenko @ 2023-02-24 13:03 UTC (permalink / raw)
  To: sebastien.miquel; +Cc: emacs-orgmode

Sébastien Miquel <sebastien.miquel@posteo.eu> writes:

> For most changes, you'll have to copy and modify the original
> transcoder's implementation anyway. At this point, you might as well
> write the feature logic in lisp (checking features through =info=),
> instead of your `transcoder-conditions`.

Consider the feature request from the past about wrapping/prepending
to exported headings:

* Heading1
* Heading2
:PROPERTIES:
:LATEX_TEMPLATE: (:snippet "\clearpage" :order -100)
:END:
# This Heading2 will start on a new page

If we implement export transcoders as much as possible using templates,
it will become very easy for users to adjust the export behavior beyond
what is already possible.

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-24 13:03           ` Ihor Radchenko
@ 2023-02-24 21:38             ` Sébastien Miquel
  2023-02-26 12:28               ` Ihor Radchenko
  0 siblings, 1 reply; 22+ messages in thread
From: Sébastien Miquel @ 2023-02-24 21:38 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

Ihor Radchenko writes:
> Consider the feature request from the past about wrapping/prepending
> to exported headings:
>
> * Heading1
> * Heading2
> :PROPERTIES:
> :LATEX_TEMPLATE: (:snippet "\clearpage" :order -100)
> :END:
> # This Heading2 will start on a new page
>
> If we implement export transcoders as much as possible using templates,
> it will become very easy for users to adjust the export behavior beyond
> what is already possible.

This can be achieved in a couple of lines with advices.

Here's a couple interesting examples that currently cannot, I think.
  + a `multicol` heading property, that wraps the content of the
    heading in a multicol environment.
  + a `nocontent` property that do not export the content of the
    heading
  + Some way to play with the numbering of section, beyond the
    `unumbered` property.

It is indeed unfortunate that org doesn't provide an easy way to get
this behaviour, and achieving it would require the fragmentation
(templating ?) of at least some transcoders. I'm not sure that it
makes sense to do this for anything other than the headings
transcoders, and the main template.

However, this seems orthogonal to your previous proposal. It is not
clear to me how it ties with your syntax.

--
Sébastien Miquel


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-24 21:38             ` Sébastien Miquel
@ 2023-02-26 12:28               ` Ihor Radchenko
  2023-02-26 14:06                 ` Sébastien Miquel
  0 siblings, 1 reply; 22+ messages in thread
From: Ihor Radchenko @ 2023-02-26 12:28 UTC (permalink / raw)
  To: sebastien.miquel; +Cc: emacs-orgmode

Sébastien Miquel <sebastien.miquel@posteo.eu> writes:

>> If we implement export transcoders as much as possible using templates,
>> it will become very easy for users to adjust the export behavior beyond
>> what is already possible.
>
> This can be achieved in a couple of lines with advices.

Only the simplest cases of prepending/appending staff.
If we want to splice into the normal export template, users currently
must either write an output filter or rewrite the trnascoders
completely.

The proposed template system will provide more flexibility to modify the
default export transcoders.

> Here's a couple interesting examples that currently cannot, I think.
>   + a `multicol` heading property, that wraps the content of the
>     heading in a multicol environment.

Could you please illustrate with examples?

>   + a `nocontent` property that do not export the content of the
>     heading

This can be done with :filter-parse-tree or :filter-headline

>   + Some way to play with the numbering of section, beyond the
>     `unumbered` property.

Could you elaborate what kind of "play" you are referring to?

> It is indeed unfortunate that org doesn't provide an easy way to get
> this behaviour, and achieving it would require the fragmentation
> (templating ?) of at least some transcoders. I'm not sure that it
> makes sense to do this for anything other than the headings
> transcoders, and the main template.

Currently, transcoders are opaque functions that expose a limited number
of pre-defined settings. Turning them into templates will allow certain
non-standard alternations that we cannot think of in advance. Without
directly modifying the transcoder function code.

> However, this seems orthogonal to your previous proposal. It is not
> clear to me how it ties with your syntax.

Could you elaborate?

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-26 12:28               ` Ihor Radchenko
@ 2023-02-26 14:06                 ` Sébastien Miquel
  2023-02-27 19:32                   ` Ihor Radchenko
  0 siblings, 1 reply; 22+ messages in thread
From: Sébastien Miquel @ 2023-02-26 14:06 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: emacs-orgmode

Ihor Radchenko writes:
> Only the simplest cases of prepending/appending staff.
> If we want to splice into the normal export template, users currently
> must either write an output filter or rewrite the trnascoders
> completely.
>
> The proposed template system will provide more flexibility to modify the
> default export transcoders.

Reading your original proposal, I see nothing that provides more
flexibility. I can guess at how it would allow one to prepend/append
stuff to the output of the default transcoder. Anything more flexible
than that would require breaking these default transcoders into parts,
which you did not originally mention.

>> Here's a couple interesting examples that currently cannot, I think.
>>    + a `multicol` heading property, that wraps the content of the
>>      heading in a multicol environment.
> Could you please illustrate with examples?

Exported content would be:
#+BEGIN_SRC latex
\section{ABC}
\begin{multicols}{3}
   Section content
\end{multicols}
#+END_SRC

>>    + a `nocontent` property that do not export the content of the
>>      heading
> This can be done with :filter-parse-tree or :filter-headline

I guess. This isn't "couple of lines"-easy though.

>>    + Some way to play with the numbering of section, beyond the
>>      `unumbered` property.
> Could you elaborate what kind of "play" you are referring to?

I cannot think of anything that cannot be achieved through (somewhat
fragile) post-processing with `:filter-headline`.

Anyway, I was only trying to understand if your proposal could easily
do these things. What flexibility does it bring ?

>> It is indeed unfortunate that org doesn't provide an easy way to get
>> this behaviour, and achieving it would require the fragmentation
>> (templating ?) of at least some transcoders. I'm not sure that it
>> makes sense to do this for anything other than the headings
>> transcoders, and the main template.
> Currently, transcoders are opaque functions that expose a limited number
> of pre-defined settings. Turning them into templates will allow certain
> non-standard alternations that we cannot think of in advance. Without
> directly modifying the transcoder function code.
>
>> However, this seems orthogonal to your previous proposal. It is not
>> clear to me how it ties with your syntax.
> Could you elaborate?

See higher. More flexibility requires breaking up some transcoders
into pieces. AFAIU it, the proposal you originally described does not
bring any more flexibility beyond what can be done through short
advices, or indeed the `:filter-` functions. I'm not sure this
dedicated syntax is preferable to advices.

-- 
Sébastien Miquel


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-02-26 14:06                 ` Sébastien Miquel
@ 2023-02-27 19:32                   ` Ihor Radchenko
  0 siblings, 0 replies; 22+ messages in thread
From: Ihor Radchenko @ 2023-02-27 19:32 UTC (permalink / raw)
  To: sebastien.miquel; +Cc: emacs-orgmode

Sébastien Miquel <sebastien.miquel@posteo.eu> writes:

>> The proposed template system will provide more flexibility to modify the
>> default export transcoders.
>
> Reading your original proposal, I see nothing that provides more
> flexibility. I can guess at how it would allow one to prepend/append
> stuff to the output of the default transcoder. Anything more flexible
> than that would require breaking these default transcoders into parts,
> which you did not originally mention.

Here is my refined proposal, which we converged to upon further
discussion with TEC. Basically, we will extend the notion of export
transcoder to be a list instead of a function:

:translate-alist
'(...
  (table :snippets ((table-begin :when caption :snippet "\\begin{table}[htbp]")
                    (caption :snippet (format "\\caption{%s}" (<get caption>)))
                    (centering :snippet "\\centering")
                    (tabular-begin :snippet (format "\\begin{tabular}%s" <get-align>))
                    (contents :snippet <get-contents>)
                    (tabular-end :snippet "\\end{tabular}")
                    (table-end :when caption :snippet "\\end{table}")
          :conditions ((t . table-begin centering table-end tabular-begin contents tabular-end)
                       ((lambda (el info) (org-element-property :caption el)) . caption)))
...)

>>> Here's a couple interesting examples that currently cannot, I think.
>>>    + a `multicol` heading property, that wraps the content of the
>>>      heading in a multicol environment.
>> Could you please illustrate with examples?
>
> Exported content would be:
> #+BEGIN_SRC latex
> \section{ABC}
> \begin{multicols}{3}
>    Section content
> \end{multicols}
> #+END_SRC

With new template system, it will be very easy. You just need to add new
elements to the section template:

By default:

(section :snippets ((contents :snippet (lambda (_ _ contents) contents))))

You can just add

:snippets
(wrap-multicol-begin :before contents :snippet "\\begin{multicols}{3}")
(wrap-multicol-end :after contents :snippet "\\end{multicols}")

:conditions (t . wrap-multicol-begin wrap-multicol-end)


>>>    + a `nocontent` property that do not export the content of the
>>>      heading
>> This can be done with :filter-parse-tree or :filter-headline
>
> I guess. This isn't "couple of lines"-easy though.

Sure. With new system, it will be just

:snippets (section)
(prevent-contents :prevents contents)
:conditions
(t . prevent-contents)

> See higher. More flexibility requires breaking up some transcoders
> into pieces. AFAIU it, the proposal you originally described does not
> bring any more flexibility beyond what can be done through short
> advices, or indeed the `:filter-` functions. I'm not sure this
> dedicated syntax is preferable to advices.

I hope that the above examples clarified things.
As you can see, it is possible to manipulate the order of elements in
the original templates and disable some existing parts quite easily.

Of course, we will first need to rewrite built-in transcoders into
templates. Most of them can be rewritten rather trivially, fortunately.

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
@ 2023-03-01  8:26 Pedro Andres Aranda Gutierrez
  2023-03-01  9:41 ` Ihor Radchenko
  0 siblings, 1 reply; 22+ messages in thread
From: Pedro Andres Aranda Gutierrez @ 2023-03-01  8:26 UTC (permalink / raw)
  To: Org Mode List

[-- Attachment #1: Type: text/plain, Size: 2016 bytes --]

Hi,

before I forget, I have been thinking about this a lot. It may look
tangetial but IMHO it is not...

One thing is having
```
(setq org-cite-export-processors '((beamer . biblatex)
                                (latex .  biblatex)))
```
in your emacs configuration (because you need it for most situations)
and another thing is that this options forces the export process to
check that you are using a bibliography in each and every document you
generate. I may want to write a quick document  with org-mode and
generate a PDF with the LaTEX backend and another thing is that I will
need to include a bibliography even if I don't need it.

Currently, with that config for ox-latex, this MWE chokes because
their is no reference to a bibliography:

------ mwe.org -------------
#+LATEX_CLASS: letter
#+DATE: 01-Mar-2023

Dear friends!

It sucks a bit to need a bibliography to export this letter!

Best, /PA
-----------------------------------
This is the minimal emacs config that chokes at PDF export (C-c C-e lo)
----- mwe.el -----------------
(require 'org)
(require 'ox-latex)
(setq org-cite-export-processors '((beamer . biblatex)
                               (latex .  biblatex)))
(setq org-latex-pdf-process
      '("latexmk -pdflatex='pdflatex --shell-escape
--interaction=nonstopmode' -pdf -f %f"))
(add-to-list 'org-latex-classes
             '("letter"
               "\\documentclass[a4paper]{letter}"))
-------------------------------

To try:

emacs -Q -l mwe.el mwe.org

and then C-c C-e l o in Emacs to get the attached error message and no PDF.

This is all on

GNU Emacs 30.0.50
Development version fad366506974 on master branch; build date 2023-02-23.

It would be nice to take this discussion as an opportunity to 'fix' this

Best, /PA

-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should
run a leader-deposed hook here, but we can't yet

[-- Attachment #2: image.png --]
[-- Type: image/png, Size: 36733 bytes --]

^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-03-01  8:26 [POLL] Naming of "export features" Pedro Andres Aranda Gutierrez
@ 2023-03-01  9:41 ` Ihor Radchenko
  2023-03-01 11:38   ` Pedro Andres Aranda Gutierrez
  0 siblings, 1 reply; 22+ messages in thread
From: Ihor Radchenko @ 2023-03-01  9:41 UTC (permalink / raw)
  To: Pedro Andres Aranda Gutierrez; +Cc: Org Mode List

Pedro Andres Aranda Gutierrez <paaguti@gmail.com> writes:

> One thing is having
> ```
> (setq org-cite-export-processors '((beamer . biblatex)
>                                 (latex .  biblatex)))
> ```

Not a bug.
You need

(setq org-cite-export-processors '((beamer biblatex)
                                (latex biblatex)))

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-03-01  9:41 ` Ihor Radchenko
@ 2023-03-01 11:38   ` Pedro Andres Aranda Gutierrez
  2023-03-02 11:30     ` Ihor Radchenko
  0 siblings, 1 reply; 22+ messages in thread
From: Pedro Andres Aranda Gutierrez @ 2023-03-01 11:38 UTC (permalink / raw)
  To: Ihor Radchenko; +Cc: Org Mode List

Hi Igor

Actually, not including the line makes the MWE work, so you don't
_need_ it as such when there is no bibliography.

When I set org-cite-export-processors in my Emacs setup (for my 99.9%
of cases),
I still can set it to nil in the local variables of the .org file when
I don't want/need
bibtex/biblatex processing (Minor inconvenience I can assume).

<blush>It's in the docstring and I should have read it</blush> but
still, it's a bit confusing and
a more verbose explanation in the manual may help in the future...

Just my .2 cents... /PA

On Wed, 1 Mar 2023 at 10:40, Ihor Radchenko <yantar92@posteo.net> wrote:
>
> Pedro Andres Aranda Gutierrez <paaguti@gmail.com> writes:
>
> > One thing is having
> > ```
> > (setq org-cite-export-processors '((beamer . biblatex)
> >                                 (latex .  biblatex)))
> > ```
>
> Not a bug.
> You need
>
> (setq org-cite-export-processors '((beamer biblatex)
>                                 (latex biblatex)))
>
> --
> 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>



-- 
Fragen sind nicht da um beantwortet zu werden,
Fragen sind da um gestellt zu werden
Georg Kreisler

Headaches with a Juju log:
unit-basic-16: 09:17:36 WARNING juju.worker.uniter.operation we should
run a leader-deposed hook here, but we can't yet


^ permalink raw reply	[flat|nested] 22+ messages in thread

* Re: [POLL] Naming of "export features"
  2023-03-01 11:38   ` Pedro Andres Aranda Gutierrez
@ 2023-03-02 11:30     ` Ihor Radchenko
  0 siblings, 0 replies; 22+ messages in thread
From: Ihor Radchenko @ 2023-03-02 11:30 UTC (permalink / raw)
  To: Pedro Andres Aranda Gutierrez; +Cc: Org Mode List

Pedro Andres Aranda Gutierrez <paaguti@gmail.com> writes:

> Actually, not including the line makes the MWE work, so you don't
> _need_ it as such when there is no bibliography.
>
> When I set org-cite-export-processors in my Emacs setup (for my 99.9%
> of cases),
> I still can set it to nil in the local variables of the .org file when
> I don't want/need
> bibtex/biblatex processing (Minor inconvenience I can assume).
>
> <blush>It's in the docstring and I should have read it</blush> but
> still, it's a bit confusing and
> a more verbose explanation in the manual may help in the future...

Could you please elaborate what you are confused about?
`org-cite-export-processors' docstring?

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


^ permalink raw reply	[flat|nested] 22+ messages in thread

end of thread, other threads:[~2023-03-02 11:30 UTC | newest]

Thread overview: 22+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-03-01  8:26 [POLL] Naming of "export features" Pedro Andres Aranda Gutierrez
2023-03-01  9:41 ` Ihor Radchenko
2023-03-01 11:38   ` Pedro Andres Aranda Gutierrez
2023-03-02 11:30     ` Ihor Radchenko
     [not found] <mailman.336.1676990100.5072.emacs-orgmode@gnu.org>
2023-02-23 15:06 ` No Wayman
  -- strict thread matches above, loose matches on Subject: below --
2023-02-10 17:20 [PATCH] Introduce " Timothy
2023-02-21 14:22 ` [POLL] Naming of " Timothy
2023-02-22  1:46   ` Dr. Arne Babenhauserheide
2023-02-22  2:40     ` Timothy
2023-02-23 15:55       ` No Wayman
2023-02-23 16:17         ` No Wayman
2023-02-22 12:23   ` Ihor Radchenko
2023-02-23 15:31     ` No Wayman
2023-02-23 16:04     ` Bruce D'Arcus
2023-02-23 19:04       ` Ihor Radchenko
2023-02-23 19:55     ` Sébastien Miquel
2023-02-24 10:27       ` Ihor Radchenko
2023-02-24 12:46         ` Sébastien Miquel
2023-02-24 13:03           ` Ihor Radchenko
2023-02-24 21:38             ` Sébastien Miquel
2023-02-26 12:28               ` Ihor Radchenko
2023-02-26 14:06                 ` Sébastien Miquel
2023-02-27 19:32                   ` Ihor Radchenko

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).