Experimental public branch for inline special blocks

Experimental public branch for inline special blocks

[Juan Manuel Macías]

Hi,

Finally, I have made public on GitLab my experimental branch for the new
(possible) inline-special-block element:

<https://gitlab.com/maciaschain/org-mode.git>

The code incorporates fixes and modifications and I have also added some
ideas from Maxim Nikulin. The LaTeX and HTML backends are complete,
although of course it can still be perfected. Recapitulating the
necessary information:

The new element can be nested and supports other elements such as links,
macros, emphasis marks, etc.

The basic syntax:

┌────
│ &foo{lorem ipsum dolor}
└────

produces in LaTeX:

┌────
│ \foo{lorem ipsum dolor}
└────

and in HTML:

┌────
│ <span class="foo">lorem ipsum dolor</span>
└────

There is also an anonymous variant:

┌────
│ &_{lorem ipsum dolor}
└────

Optional attributes in square brackets are supported. There are a series
of 'universal' attributes, common to each backend. At the moment:
`:lang', `:color' and `:smallcaps'. Example:

┌────
│ &foo[:color red :smallcaps t :lang it]{lorem ipsum dolor}
└────

Specific to the LaTeX backend we have the `:prelatex' and `:postlatex'
attributes (which introduce arbitrary code before and after the content)
and `:latex-command', which overrides the exported command.
`:latex-command nocommand' does not export a command flag. Examples:

┌────
│ &foo[:prelatex [bar] :postlatex {baz} :lang it :latex-command blah]{lorem ipsum dolor}
└────

==>

┌────
│ \foreignlanguage{italian}{\blah[bar]{lorem ipsum dolor}{baz}}
└────

┌────
│ &_[:prelatex \foo{bar} :color red]{lorem ipsum dolor}
└────

==>

┌────
│ {\color{red}\foo{bar}lorem ipsum dolor}
└────

Likewise, for HTML we have the `:html-tag' and `:html-class' attributes
(which override the tags and the class name) and another one, more
generic, `:html', which introduces arbitrary code, such as
`style="..."'.

We can group lists of attributes as aliases. The syntax waould be:

┌────
│ &alias!{text}
└────

and we can also combine aliases with more single attributes:

┌────
│ &alias![more-attributes]{text}
└────

An example: let's imagine that we want a specific block for short quotes
in Latin and italics (it is normative in some typographical traditions
that quotes in classical Latin are put in italics instead of quotation
marks):

┌────
│ #+options: inline-special-block-aliases:(("latin" :lang "la" :latex-command "textit" :html-tag "em"))
│ 
│ Caesar's famous quote: &latin!{Alea iacta est}
│ 
│ Caesar's famous quote: &latin![:smallcaps t :color blue]{Alea iacta est}
└────

==> LaTeX:

┌────
│ Caesar's famous quote: \foreignlanguage{latin}{\textit{Alea iacta est}}
│ 
│ Caesar's famous quote: {\scshape{}\color{blue}\foreignlanguage{latin}{\textit{Alea iacta est}}}
└────

== HTML:

┌────
│ Caesar's famous quote: <em lang="la" class="latin">Alea iacta est</em>
│ 
│ Caesar's famous quote: <em style="color:blue;font-variant:small-caps;" lang="la" class="latin">Alea iacta est</em>
└────


Best regards,

Juan Manuel 

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: Experimental public branch for inline special blocks

[Stefan Nobis]

Hi Juan,

first of all: Thank you for your great work. Looks really good.

Just out of curiosity: Why a special syntax for alias expansion?

From a syntax and user point of view, I think I would prefer a simpler
syntax. So

    &alias{text}

would check if an alias is registered and if yes use it. This way it
would be easier to change/add options later on without the need for
changing all the inline-block commands and add a "!" (not a big deal,
just two rather simple replace commands).

But even as it is it's a very nice and welcome extension (at least to
me)!

-- 
Until the next mail...,
Stefan.

Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Hi, Stefan,

Stefan Nobis writes:

> first of all: Thank you for your great work. Looks really good.

You're welcome! :-)

> Just out of curiosity: Why a special syntax for alias expansion?
>
> From a syntax and user point of view, I think I would prefer a simpler
> syntax. So
>
>     &alias{text}
>
> would check if an alias is registered and if yes use it. This way it
> would be easier to change/add options later on without the need for
> changing all the inline-block commands and add a "!" (not a big deal,
> just two rather simple replace commands).

I think you're right. I have removed the need for "!" in the last
commit.

Now the syntax is:

&alias{text}

Best regards,

Juan Manuel 

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Hi again,

The odt backend is now complete with the `org-odt-inline-special-block'
function. Some particularities of exporting to odt:

- The only specific attribute is :odt-style, which overrides the default
  style. Example:

&foo{lorem ipsum} ==> the style is "foo"

&foo[:odt-style bar]{lorem ipsum} ==> the style is "bar". Same with the
anonymous variant &_[:odt-style bar]{lorem ipsum}.

- The three global attributes supported in the LaTeX and HTML backends
  are also supported in odt: `:lang', `:color' and `:smallcaps'. I have
  learned that these direct format elements are in odt "automatic
  styles", which must be declared before the body. I haven't thought of
  any other way to do it than using a list of automatic styles that is
  inserted inside `org-odt-template', with each export. Some examples with
  various combinations:

&foo[:color magenta :odt-style Bold]{this is magenta and bold}

&foo[:color red :odt-style Emphasis]{this is red and emphasis}

&Underline[:color green]{this is green and underline}

&foo[:color blue]{this is blue with &_[:smallcaps t]{smallcaps}}

And a screenshot: https://i.imgur.com/KNhYQrv.png

Best regards,

Juan Manuel 

naming: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 02/03/2024 03:34, Juan Manuel Macías wrote:
> 
> Finally, I have made public on GitLab my experimental branch for the new
> (possible) inline-special-block element:

I find the feature name confusing, however I am unsure if others share 
my opinion.

In Org syntax, "elements" are paragraphs and larger parts, while parts 
within paragraphs are named objects. I admit that for org-element 
everything is element.

In CSS "display: inline block" makes an HTML element a rectangular block 
inside a paragraph while new feature is mostly intended for normal text 
flow. I admit that &parbox[...]{...} may be used to create an instance 
similar to inline block and that "inline source blocks" are already 
described in the manual.

Does anybody have an idea of a better name for a feature? Maybe 
something like inline custom objects, snippets. "Objects" are used to 
describe syntax, but not used in the manual though.

Re: naming: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> Does anybody have an idea of a better name for a feature? Maybe 
> something like inline custom objects, snippets. "Objects" are used to 
> describe syntax, but not used in the manual though.

Custom inline markup.

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

Re: naming: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> Max Nikulin <manikulin@gmail.com> writes:
>
>> Does anybody have an idea of a better name for a feature? Maybe 
>> something like inline custom objects, snippets. "Objects" are used to 
>> describe syntax, but not used in the manual though.
>
> Custom inline markup.

Custom span?

I chose "inline special block" because special blocks, and because of
the parallelism inline code block/code block.

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: naming: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> In Org syntax, "elements" are paragraphs and larger parts, while parts
> within paragraphs are named objects. I admit that for org-element
> everything is element.

In my initial message I used 'element' loosely. Note that
inline-special-block is included in org-element-all-objects, where
inline-src-block is also.

Re: naming: Re: Experimental public branch for inline special blocks

[Samuel Wales]

If language is not correct, then what is said is
not what is meant; if what is said is not what is meant,
then what must be done remains undone; if this remains
undone, morals and art will deteriorate; if justice goes
astray, the people will stand about in helpless
confusion. Hence there must be no arbitrariness in what is
said. This matters above everything.  --- analects

On 3/4/24, Juan Manuel Macías <maciaschain@posteo.net> wrote:
> Max Nikulin writes:
>
>> In Org syntax, "elements" are paragraphs and larger parts, while parts
>> within paragraphs are named objects. I admit that for org-element
>> everything is element.
>
> In my initial message I used 'element' loosely. Note that
> inline-special-block is included in org-element-all-objects, where
> inline-src-block is also.
>
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: naming: Re: Experimental public branch for inline special blocks

[Samuel Wales]

[i did not aim that at any particular person!]

On 3/4/24, Samuel Wales <samologist@gmail.com> wrote:
> If language is not correct, then what is said is
> not what is meant; if what is said is not what is meant,
> then what must be done remains undone; if this remains
> undone, morals and art will deteriorate; if justice goes
> astray, the people will stand about in helpless
> confusion. Hence there must be no arbitrariness in what is
> said. This matters above everything.  --- analects
>
> On 3/4/24, Juan Manuel Macías <maciaschain@posteo.net> wrote:
>> Max Nikulin writes:
>>
>>> In Org syntax, "elements" are paragraphs and larger parts, while parts
>>> within paragraphs are named objects. I admit that for org-element
>>> everything is element.
>>
>> In my initial message I used 'element' loosely. Note that
>> inline-special-block is included in org-element-all-objects, where
>> inline-src-block is also.
>>
>>
>
>
> --
> The Kafka Pandemic
>
> A blog about science, health, human rights, and misopathy:
> https://thekafkapandemic.blogspot.com
>


-- 
The Kafka Pandemic

A blog about science, health, human rights, and misopathy:
https://thekafkapandemic.blogspot.com

Re: naming: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 05/03/2024 00:49, Juan Manuel Macías wrote:
> Ihor Radchenko writes:
>> Max Nikulin writes:
>>
>>> Does anybody have an idea of a better name for a feature? Maybe
>>> something like inline custom objects, snippets. "Objects" are used to
>>> describe syntax, but not used in the manual though.
>>
>> Custom inline markup.
> 
> Custom span?
> 
> I chose "inline special block" because special blocks, and because of
> the parallelism inline code block/code block.

Special blocks are really block-level elements. I see similarity, 
however with a better term we could avoid "inline" specifier. I think, 
the new beast may serve in some cases currently handled by macros. LaTeX 
snippets are named "fragments" in the manual.

Custom fragment?

Re: naming: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> Special blocks are really block-level elements. I see similarity, 
> however with a better term we could avoid "inline" specifier. I think, 
> the new beast may serve in some cases currently handled by macros. LaTeX 
> snippets are named "fragments" in the manual.
>
> Custom fragment?

Not sure if I like it. In my mind, "fragment" implies no nesting. But
the point of the "inline special blocks" is to allow nesting as needed.

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

Re: naming: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> Special blocks are really block-level elements. I see similarity,
> however with a better term we could avoid "inline" specifier. I think,
> the new beast may serve in some cases currently handled by macros.
> LaTeX snippets are named "fragments" in the manual.
>
> Custom fragment?

I think "custom" is an important part of defining the new object. Unlike
other elements/objects, such as emphasis marks, this one does not add
any (let's say) "logical or semantic" information. I mean, emphasis
marks (to continue with the example) are useful when reading an Org
document as it is. But the new object is rather a segment of text that
must be exported in a certain way to LaTeX, odt, HTML, etc. Something
like "&foo{some text}" does not provide any information to the reader,
but rather to the exporters and the output format. So, how about
something like:

- Custom Export Fragment

- Custom Export Span

- Custom Export "Whatever"

- ...

?

(I especially like "span" because of the similarity with html and family.
Pandoc uses the term bracketed spans for its custom markdown).

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: naming: Re: Experimental public branch for inline special blocks

[Suhail Singh]

Ihor Radchenko <yantar92@posteo.net> writes:

> In my mind, "fragment" implies no nesting.

FWIW, in the mind of this Org mode user as well.

> But the point of the "inline special blocks" is to allow nesting as
> needed.

Yes, exactly!  As "inline code blocks" are to "code blocks" so too are
"inline special blocks" to "special blocks".

I generally try and abstain from bike-shedding, but as a data point, the
intent of "inline special blocks" was quite clear to me based on the
name alone.  This was, in no small part, due to the similarity with
"inline code blocks" (cf. "code blocks") as well as "special blocks".

I hope the name of this "syntactic object", when incorporated into Org
mode, doesn't change.  But if it were to, I do hope the names of other
similar syntactic terms are similarly updated.

-- 
Suhail

Re: naming: Re: Experimental public branch for inline special blocks

[Suhail Singh]

Suhail Singh <suhailsingh247@gmail.com> writes:

> ... due to the similarity with "inline code blocks" (cf. "code
> blocks") as well as "special blocks".

.. due to the /relation/ with "inline code blocks" (cf. "code blocks")
as well as "special blocks".

> But if it were to, I do hope the names of other similar syntactic
> terms are similarly updated.

But if it were to, I do hope the names of other /related/ syntactic
terms are similarly updated.

-- 
Suhail

smallcaps: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 02/03/2024 03:34, Juan Manuel Macías wrote:
> │ Caesar's famous quote: &latin![:smallcaps t :color blue]{Alea iacta est}
> ==> LaTeX:
> │ Caesar's famous quote: {\scshape{}\color{blue}\foreignlanguage{latin}{\textit{Alea iacta est}}}
> == HTML:
> │ Caesar's famous quote: <em style="color:blue;font-variant:small-caps;" lang="la" class="latin">Alea iacta est</em>

I am in doubts if smallcaps should be hardcoded. From my point of view, 
current implementation is unnecessary rigid. In this particular example 
:smallcaps is an ad-hoc property. I would expect its usage through an 
alias definition, e.g.

#+options: inline-special-block-aliases:(("definition" :smallcaps t))

If some type is used through the document multiple times then it is 
better to avoid style="font-variant:small-caps" and use a CSS class 
instead. Even for LaTeX it may be better to define a dedicated command 
to be closer to semantic markup.

Moreover different decorations may be used in LaTeX and HTML. Some type 
may be typed in small caps in LaTeX, but in HTML it may use regular font 
and some color.

Perhaps an e.g. user-configurable and extensible alist of types with 
per-backend properties should be used instead.

A portion of wisdom how to represent small caps for each export backend 
may be handy, but accessing it should be more flexible.

Re: smallcaps: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin <manikulin@gmail.com> escribió:

> If some type is used through the document multiple times then it is 
> better to avoid style="font-variant:small-caps" and use a CSS class 
> instead. Even for LaTeX it may be better to define a dedicated command 
> to be closer to semantic markup.
>
> Moreover different decorations may be used in LaTeX and HTML. Some type 
> may be typed in small caps in LaTeX, but in HTML it may use regular font 
> and some color.

The "global attribute" concept implies that there should be (ideally)
the same result in all possible backends (naturally, if the output is
plain text, :color doesn't make much sense). Global attributes are a
quick and easy (for the user) way to create direct formatting, analogous
to the LaTeX commands \textcolor, \textsc, etc. Its casual use is the
most recommended, in my opinion. Let's imagine that a user wants to
color segments of text, in the same color, for LaTeX and odt, and does
not want to bother with predefined styles or macros in odt and LaTeX
respectively.

If a segment of text must have a different appearance, for example, in
LaTeX (small caps) and HTML (red color), you can put:

&_[:html style="color:red;" :prelatex \scshape{}]{text}

And if one wants to have more robust control, for example because many
text segments must have a certain treatment in HTML, odt or LaTeX,
styles, classes and macros can always be defined in the output format.
Additionally, there are the :odt-style, :latex-command, :html-tag and
:html-class attributes to override what is necessary. What's more, in
specific cases global attributes can be added.

I think that the current implementation is very flexible and gives rise
to many possible variations, and the combination of direct formatting
and styles to suit the user.

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: naming: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 05/03/2024 00:29, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>> Does anybody have an idea of a better name for a feature? Maybe
>> something like inline custom objects, snippets. "Objects" are used to
>> describe syntax, but not used in the manual though.
> 
> Custom inline markup.

"Markup" is something abstract to my taste. I would prefer something 
related to concrete instances of such objects.

Decorators sometimes stressed as "inline decorators"?

Re: smallcaps: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 06/03/2024 00:28, Juan Manuel Macías wrote:
> Max Nikulin escribió:
> I think that the current implementation is very flexible and gives rise
> to many possible variations, and the combination of direct formatting
> and styles to suit the user.

OK, just consider it as my dissenting opinion. I believe that it should 
be possible for the same Org document

   #+options: inline-special-block-aliases:(("definition" :smallcaps t))

   &definition{Example} or &_[:smallcaps t]{ad-hoc}

to export it as

   <span style="font-variant:small-caps;">Example</span>
   or <span style="font-variant:small-caps;">ad-hoc</span>

or as

   <span class="definition">Example</span>
   or <span class="small-caps">ad-hoc</span>

by adjusting of global settings. The former one be suitable for a CMS 
that does not allow user CSS and the latter one is preferable for a site 
under full user control and having CSS

   .definition, .small-capps { font-variant: small-caps; }

Re: naming: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> Custom inline markup.
>
> "Markup" is something abstract to my taste. I would prefer something 
> related to concrete instances of such objects.

IMHO, the whole point of the discussed construct is exactly being abstract
and multi-purpose.

> Decorators sometimes stressed as "inline decorators"?

I dislike "decorators" because it is not a term we use anywhere in Org
mode. I'd prefer to reuse an existing term, if at all 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>

Re: smallcaps: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> OK, just consider it as my dissenting opinion. I believe that it should
> be possible for the same Org document
>
>    #+options: inline-special-block-aliases:(("definition" :smallcaps t))
>
>    &definition{Example} or &_[:smallcaps t]{ad-hoc}
>
> to export it as
>
>    <span style="font-variant:small-caps;">Example</span>
>    or <span style="font-variant:small-caps;">ad-hoc</span>
>
> or as
>
>    <span class="definition">Example</span>
>    or <span class="small-caps">ad-hoc</span>
>
> by adjusting of global settings. The former one be suitable for a CMS
> that does not allow user CSS and the latter one is preferable for a site
> under full user control and having CSS
>
>    .definition, .small-capps { font-variant: small-caps; }

With the current implementation this:

#+options: inline-special-block-aliases:(("definition" :smallcaps t))

&definition{Example}

produces:

<span style="font-variant:small-caps;" class="definition">Example</span>

:smallcaps simply adds a (say) direct formatting layer. I am not a fan
of any form of direct formatting. But, as I already said, I think that
these types of global attributes can be useful for users who do not want
to bother with predefining styles, classes or commands in
odt/html/LaTeX, or because they do not know how to do it. They simply
want a text to be exported with a certain color or with small caps, or
with more effects (in case more global attributes are implemented
(background color, text size, etc).

I think an option could be added to disable global attributes or specify
which backend they should be used on. Anyway, I would not see it
necessary, but perhaps other users think differently.

--
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

To avoid zero width space: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 02/03/2024 03:34, Juan Manuel Macías wrote:
> 
> Finally, I have made public on GitLab my experimental branch for the new
> (possible) inline-special-block element:
> 
> <https://gitlab.com/maciaschain/org-mode.git>

The new feature is promising as an alternative for U+200B zero width 
space as an escape character (info "(org) Escape Character"). It may 
adjusted to allow really plain text markup instead of a character 
invisible by default:

(org-export-string-as "Example of &_{*intra*}&_{/word/} markup"
		      'html
		      '(:export-options (body-only)))
"<p>
Example of <span><b>intra</b></span><span><i>word</i></span> markup</p>
"

However to produce clean export result <span> elements should not be 
added if no attributes are specified. My expectation is

"<p>
Example of <b>intra</b><i>word</i> markup</p>
"

Earlier discussions:

- Denis Maier. Org-syntax: Intra-word markup. Thu, 2 Dec 2021 11:50:32 
+0100. 
https://list.orgmode.org/4897bc60-b74f-ccfd-e13e-9b89a1194fdf@mailbox.org
- Juan Manuel Macías. On zero width spaces and Org syntax. Fri, 03 Dec 
2021 12:48:16 +0000. https://list.orgmode.org/87ilw5yhv3.fsf@posteo.net
- Vincent Belaïche. RE: [RFC] Creole-style / Support for 
**emphasis**__within__**a word** Mon, 24 Jan 2022 10:50:10 +0000. 
https://list.orgmode.org/PAXPR06MB809350C21E7C75A2A110C529845E9@PAXPR06MB8093.eurprd06.prod.outlook.com

Re: To avoid zero width space: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> However to produce clean export result <span> elements should not be
> added if no attributes are specified. My expectation is
>
> "<p>
> Example of <b>intra</b><i>word</i> markup</p>
> "

It seems like a good idea to me. Currently, in LaTeX:

&_{lorem ipsum dolor} ==> LaTeX ==> lorem ipsum dolor

It can also be extended to html, odt and the rest of the backends.

That is, by default, the anonymous variant without attributes simply
returns the content.

Another possibility (with the current implementation):

#+options: inline-special-block-aliases:(("b" :html-tag "b")("i" :html-tag "i"))

&b{intra}&i{word}

--
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: To avoid zero width space: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> However to produce clean export result <span> elements should not be
> added if no attributes are specified. My expectation is
>
> "<p>
> Example of <b>intra</b><i>word</i> markup</p>
> "

With the latest commit now the anonymous variant without attributes
simply returns the content (in LaTeX, HTML and odt). You can try:

&_{/lorem/}&_{*ipsum*}&_{_dolor_}

==> LaTeX: \emph{lorem}\textbf{ipsum}\uline{dolor}

==> HTML <i>lorem</i><b>ipsum</b><span class="underline">dolor</span>

==> ODT <text:span text:style-name="Emphasis">lorem</text:span><text:span text:style-name="Bold">ipsum</text:span><text:span text:style-name="Underline">dolor</text:span>


-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: naming: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 06/03/2024 17:56, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>>> Custom inline markup.
>>
>> "Markup" is something abstract to my taste. I would prefer something
>> related to concrete instances of such objects.
> 
> IMHO, the whole point of the discussed construct is exactly being abstract
> and multi-purpose.

Almost everything in Org syntax may be called "markup", so using this 
word for a specific object may lead to confusion unless a couple of 
extra words are added to make it clear what kind of markup is referred to.

I had an idea to name new object "markup macro" since its role is close 
to existing macro ("substitution macro"), but I discarded it because 
"markup" is too general.

>> Decorators sometimes stressed as "inline decorators"?
> 
> I dislike "decorators" because it is not a term we use anywhere in Org
> mode. I'd prefer to reuse an existing term, if at all possible.

I had a hope to find a unique word that will be convenient for usage in 
discussions, a term that will be uniformly used in the manual and in the 
syntax specification.

If others are happy to name "block" instances that are neither solid nor 
shaped as blocks then I see no point to continue this discussion.

P.S. I am neutral in respect to "span".

false positives: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 02/03/2024 03:34, Juan Manuel Macías wrote:
> 
> Finally, I have made public on GitLab my experimental branch for the new
> (possible) inline-special-block element:
> 
> <https://gitlab.com/maciaschain/org-mode.git>

It seems the parser finds new objects where syntactical constructs are 
incomplete:

   (org-export-string-as "Alpha&Beta{"
		      'html
		      '(:export-options (body-only)))
   "<p>\nAlpha<span class=\"Beta\"></span>{</p>\n"

My expectation is

   "<p>\nAlpha&amp;Beta{</p>\n"

Even worse

   (org-export-string-as "Alpha&Beta["
		      'html
		      '(:export-options (body-only)))

    Debugger entered--Lisp error: (wrong-type-argument 
number-or-marker-p nil)

I think, this particular case deserves a unit test despite it is too 
early for extensive test suite.

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> It seems the parser finds new objects where syntactical constructs are
> incomplete:
>
>   (org-export-string-as "Alpha&Beta{"
> 		      'html
> 		      '(:export-options (body-only)))
>   "<p>\nAlpha<span class=\"Beta\"></span>{</p>\n"

mmm, right. And there may also be a problem with the subscripts: &_{subscript}...

Perhaps we should think about a structure less prone to ambiguities. For
example:

&:type[attrs]{text} / &:_[attrs]{text}

(I think someone had suggested something like this in a past message,
but I can't find it, apologies).

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: false positives: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

>>   (org-export-string-as "Alpha&Beta{"
> ...
> mmm, right. And there may also be a problem with the subscripts: &_{subscript}...
>
> Perhaps we should think about a structure less prone to ambiguities. For
> example:
>
> &:type[attrs]{text} / &:_[attrs]{text}

I suggest @type[...]{...}. Akin Texinfo constructs.

(Texinfo because of
previous RMS' request to implement better support for markup used in
software manuals - keeping things close to Texinfo syntax will make life
easier if we ever reach the point when Org mode is used as standard
documentation format.) 

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

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> Juan Manuel Macías <maciaschain@posteo.net> writes:
>
>>>   (org-export-string-as "Alpha&Beta{"
>> ...
>> mmm, right. And there may also be a problem with the subscripts: &_{subscript}...
>>
>> Perhaps we should think about a structure less prone to ambiguities. For
>> example:
>>
>> &:type[attrs]{text} / &:_[attrs]{text}
>
> I suggest @type[...]{...}. Akin Texinfo constructs.
>
> (Texinfo because of
> previous RMS' request to implement better support for markup used in
> software manuals - keeping things close to Texinfo syntax will make life
> easier if we ever reach the point when Org mode is used as standard
> documentation format.) 

+1

(one character is always better than two)

Re: naming: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> IMHO, the whole point of the discussed construct is exactly being abstract
>> and multi-purpose.
>
> Almost everything in Org syntax may be called "markup", so using this 
> word for a specific object may lead to confusion unless a couple of 
> extra words are added to make it clear what kind of markup is referred to.

Yup. "inline custom markup". I feel that it's enough. Do I miss something?

> I had an idea to name new object "markup macro" since its role is close 
> to existing macro ("substitution macro"), but I discarded it because 
> "markup" is too general.

I do not find "too general" as a big problem.
I am not sure if I like macro. "macro" feels like something replaced
literally, without extra processing. But the proposed object has little
to do with literal replacement.

>>> Decorators sometimes stressed as "inline decorators"?
>> 
>> I dislike "decorators" because it is not a term we use anywhere in Org
>> mode. I'd prefer to reuse an existing term, if at all possible.
>
> I had a hope to find a unique word that will be convenient for usage in 
> discussions, a term that will be uniformly used in the manual and in the 
> syntax specification.

Manual was one of the reasons I chose "markup". Because this word is
used in "Markup for Rich Contents" section of the manual. Further, we
refer to "markup" when talking about emphasis/monospace in "12.2
Emphasis and Monospace" section.

> If others are happy to name "block" instances that are neither solid nor 
> shaped as blocks then I see no point to continue this discussion.

I am slightly in favor of "markup" vs. "block".

> P.S. I am neutral in respect to "span".

I do not like this for the same reason as "decorators" - unfamiliar
terminology.

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

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> I suggest @type[...]{...}. Akin Texinfo constructs.
>
> (Texinfo because of
> previous RMS' request to implement better support for markup used in
> software manuals - keeping things close to Texinfo syntax will make life
> easier if we ever reach the point when Org mode is used as standard
> documentation format.) 

I have modified the syntax in the last commit. Now:

@type[...]{...} (or @_[...]{...})

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: false positives: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> I have modified the syntax in the last commit. Now:
>
> @type[...]{...} (or @_[...]{...})

I am wondering if @@[...]{...} would be better than @_...
It should be slightly easier to type.

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

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko <yantar92@posteo.net> escribió:

> I am wondering if @@[...]{...} would be better than @_...
> It should be slightly easier to type.

Another possibility would be @:[...]{...}, which is somewhat shorter.

(I don't have any special preference, although @@ visually reminds me a
bit of the export snippet).

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Juan Manuel Macías writes:

> Ihor Radchenko <yantar92@posteo.net> escribió:
>
>> I am wondering if @@[...]{...} would be better than @_...
>> It should be slightly easier to type.
>
> Another possibility would be @:[...]{...}, which is somewhat shorter.
>
> (I don't have any special preference, although @@ visually reminds me a
> bit of the export snippet).

Anyway, in the last commit I replaced _ with @. Let's see how it goes...
Now the anonymous variant is @@[...]{...}.

Re: naming: Re: Experimental public branch for inline special blocks

[Samuel Wales]

cannot follow discussion but is the role and scope of the proposed
semantics settled and agreed upon by those who do?

Re: false positives: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 08/03/2024 01:21, Juan Manuel Macías wrote:
>> Ihor Radchenko escribió:
>>
>>> I am wondering if @@[...]{...} would be better than @_...
>>> It should be slightly easier to type.
> 
> Anyway, in the last commit I replaced _ with @. Let's see how it goes...
> Now the anonymous variant is @@[...]{...}.

Unfortunately the issue, I have reported, has not fixed. I admit, the 
examples have become more contrived

   (org-export-string-as "Alpha@Beta{"
               'html
               '(:export-options (body-only)))
   "<p>\nAlpha<span class=\"Beta\"></span>{</p>\n"

   (org-export-string-as "Alpha@Beta["
               'html
               '(:export-options (body-only)))
   Debugger entered--Lisp error: (wrong-type-argument number-or-marker-p 
nil)

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

>   (org-export-string-as "Alpha@Beta{"
>               'html
>               '(:export-options (body-only)))
>   "<p>\nAlpha<span class=\"Beta\"></span>{</p>\n"
>
>   (org-export-string-as "Alpha@Beta["
>               'html
>               '(:export-options (body-only)))
>   Debugger entered--Lisp error: (wrong-type-argument
>   number-or-marker-p nil)

Maybe in that case you could add a zero width space character.

In any case, if someone has reasons to write "Alpha@Beta{" they may also
have reasons to write "Alpha_Beta":

(org-export-string-as "Alpha_beta"
              'html
              '(:export-options (body-only)))

<p>
Alpha<sub>beta</sub></p>


-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: false positives: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 08/03/2024 22:44, Juan Manuel Macías wrote:
> Max Nikulin writes:
> 
>>    (org-export-string-as "Alpha@Beta{"
>>                'html
>>                '(:export-options (body-only)))
>>    "<p>\nAlpha<span class=\"Beta\"></span>{</p>\n"
>>
>>    (org-export-string-as "Alpha@Beta["
>>                'html
>>                '(:export-options (body-only)))
>>    Debugger entered--Lisp error: (wrong-type-argument
>>    number-or-marker-p nil)
> 
> Maybe in that case you could add a zero width space character.
> 
> In any case, if someone has reasons to write "Alpha@Beta{" they may also
> have reasons to write "Alpha_Beta":
> 
> (org-export-string-as "Alpha_beta"
>                'html
>                '(:export-options (body-only)))
> <p>
> Alpha<sub>beta</sub></p>

 From my point of view it is a pitfall with Org syntax, but parser works 
as it should.

On the other hand if there is no closing bracket then it is not an 
inline special block, so this part of document should be considered as 
text (unless some other objects are recognized).

Currently Org parser does not signal errors even for invalid input.

Re: false positives: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

>>   Debugger entered--Lisp error: (wrong-type-argument
>>   number-or-marker-p nil)
>
> Maybe in that case you could add a zero width space character.
>
> In any case, if someone has reasons to write "Alpha@Beta{" they may also
> have reasons to write "Alpha_Beta":

1. Parser must not throw errors on text files. Ever. Any text file is a
   valid Org file.
2. We should demand paired {...}, as we do for latex fragments,
   emphasis, inline export snippets, and all other container objects.

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

Re: naming: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 08/03/2024 12:26, Samuel Wales wrote:
> cannot follow discussion but is the role and scope of the proposed
> semantics settled and agreed upon by those who do?

I think, there are enough issues with the proposed feature to discuss. 
Notice "naming" added to the message subject with hope to facilitate 
tracking of specific aspects.

Ihor, I see you intention, however I reserve my vote for some new unique 
word, preferably a single one.

Re: naming: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> Ihor, I see you intention, however I reserve my vote for some new unique 
> word, preferably a single one.

That's fine. I do not insist on my preferences about naming. Rather see
it as a minor issue that can be resolved at any moment after we
implement the functionality. Maybe using a proper poll.

Let's register that we have some disagreement here. To be resolved
before we finalize things.

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

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> Juan Manuel Macías <maciaschain@posteo.net> writes:
>
>>>   Debugger entered--Lisp error: (wrong-type-argument
>>>   number-or-marker-p nil)
>>
>> Maybe in that case you could add a zero width space character.
>>
>> In any case, if someone has reasons to write "Alpha@Beta{" they may also
>> have reasons to write "Alpha_Beta":
>
> 1. Parser must not throw errors on text files. Ever. Any text file is a
>    valid Org file.
> 2. We should demand paired {...}, as we do for latex fragments,
>    emphasis, inline export snippets, and all other container objects.

Ok, I think you and Maxim are right. This is a clear bug. I hope it
was fixed in the last commit.


-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Juan Manuel Macías <maciaschain@posteo.net> escribió:

> Ok, I think you and Maxim are right. This is a clear bug. I hope it
> was fixed in the last commit.

Now:

  (org-export-string-as "Alpha@Beta{" 'latex t))

==> Alpha@Beta\{

  (org-export-string-as "Alpha@Beta{gamma}" 'latex t))

==> Alpha\Beta{gamma}

--
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: false positives: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 09/03/2024 01:57, Juan Manuel Macías wrote:
> 
>> Ok, I think you and Maxim are right. This is a clear bug. I hope it
>> was fixed in the last commit.
> 
>    (org-export-string-as "Alpha@Beta{" 'latex t))
> 
> ==> Alpha@Beta\{
> 
>    (org-export-string-as "Alpha@Beta{gamma}" 'latex t))
> 
> ==> Alpha\Beta{gamma}

However it is still gives

   (org-export-string-as "Alpha@Beta["
               'html
               '(:export-options (body-only)))
   Debugger entered--Lisp error: (wrong-type-argument number-or-marker-p 
nil)

Moreover I am unsure if "@" should be allowed in any position of elements

     (org-export-string-as "@sp@n{}"
               'html
               '(:export-options (body-only)))
   "<p>\n<span class=\"sp@n\">nil</span></p>\n"

   (org-export-string-as "@@@@{}"
               'latex
               '(:export-options (body-only)))
   "\\@@@{nil}\n"

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> However it is still gives
>
>   (org-export-string-as "Alpha@Beta["
>               'html
>               '(:export-options (body-only)))
>   Debugger entered--Lisp error: (wrong-type-argument
>   number-or-marker-p nil)

I think the problem is the contents-begin variable. When it is nil it
produces that error. I will make a new commit to fix the bug.

Thanks for all the tests you're doing!

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: false positives: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Juan Manuel Macías writes:

> Max Nikulin writes:
>
>> However it is still gives
>>
>>   (org-export-string-as "Alpha@Beta["
>>               'html
>>               '(:export-options (body-only)))
>>   Debugger entered--Lisp error: (wrong-type-argument
>>   number-or-marker-p nil)
>
> I think the problem is the contents-begin variable. When it is nil it
> produces that error. I will make a new commit to fix the bug.
>
> Thanks for all the tests you're doing!

Well, I hope that in the last commit the two bugs that you mentioned
have been fixed. Please check:

Albha@Beta[

@sp@n{lorem ipsum}

@@@@{lorem ipsum}

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

`:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

I'm thinking about adding a new global attribute, `:export', that
would granularly control whether or not to export the object and how to
export it.

Possible values: "noexport", "contents" (it would export only the content)
or the backends to which you want to export, separated by spaces. Each
backend should be followed by a "+" sign (= export all) or "*" (export
content only). For example:

@foo[:color red :export latex+ odt* html*]{lorem ipsum dolor}

This means that "lorem ipsum dolor" would be exported with color format
to LaTeX, but only the content would be exported to odt and html.

Wdyt?

Best regards,

Juan Manuel 

Re: false positives: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 09/03/2024 22:24, Juan Manuel Macías wrote:
> Well, I hope that in the last commit the two bugs that you mentioned
> have been fixed. Please check:
> 
> Albha@Beta[
> 
> @sp@n{lorem ipsum}
> 
> @@@@{lorem ipsum}

Thanks, Juan Manuel. I do not see issues any more.

I would still consider unit tests to not break these cases later.

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Juan Manuel Macías writes:

> I'm thinking about adding a new global attribute, `:export', that
> would granularly control whether or not to export the object and how to
> export it.
>
> Possible values: "noexport", "contents" (it would export only the content)
> or the backends to which you want to export, separated by spaces. Each
> backend should be followed by a "+" sign (= export all) or "*" (export
> content only). For example:
>
> @foo[:color red :export latex+ odt* html*]{lorem ipsum dolor}
>
> This means that "lorem ipsum dolor" would be exported with color format
> to LaTeX, but only the content would be exported to odt and html.

I have implemented the new :export attribute in the last commit, to
experiment (in any case, it can always be reverted). The syntax and
usage are as described in the previous message. An example, where we
define an alias for inline comments and another for highlighted text: It
will only be exported as highlighted text to LaTeX (using the lua-ul
package for LuaLaTeX); only the content will be exported to HTML; and it
will not be exported to the rest of the backends.

#+options: inline-special-block-aliases:(("comment" :export "noexport")("hl" :export "latex+ html*" :latex-command "highLight"))
#+latex_header: \usepackage{xcolor,luacolor,lua-ul}
#+latex_compiler: lualatex

@hl{this is highlighted text, only in LaTeX} @comment{this is a comment}

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 10/03/2024 09:08, Juan Manuel Macías wrote:
> I'm thinking about adding a new global attribute, `:export', that
> would granularly control whether or not to export the object and how to
> export it.

I have a bit different expectations in respect to export predicates. It 
should be possible to express that some content should be exported by 
all backend except the given list. The use case is fallback for backends 
not covered by export snippets:

     @@latex:\textbf{\LaTeX() formatting}@@@@html:<strong>HTML 
formatting</strong>@@@[...]{*for other backends}

Earlier I raised this issue during discussion of @@:...@@ syntax extension:
Max Nikulin. Re: Org-syntax: Intra-word markup. Fri, 28 Jan 2022 
21:52:17 +0700. 
https://list.orgmode.org/868df76e-69e0-1d14-ae8a-13b746982fcf@gmail.com

Another case for backend predicates is whether it should be applicable 
to derived backends or just to explicitly specified ones.

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> On 10/03/2024 09:08, Juan Manuel Macías wrote:
>> I'm thinking about adding a new global attribute, `:export', that
>> would granularly control whether or not to export the object and how to
>> export it.
>
> I have a bit different expectations in respect to export predicates.
> It should be possible to express that some content should be exported
> by all backend except the given list. The use case is fallback for
> backends not covered by export snippets:
>
>     @@latex:\textbf{\LaTeX() formatting}@@@@html:<strong>HTML
>     formatting</strong>@@@[...]{*for other backends}

I think that in your example (if I understand the intentions correctly)
it would not even be necessary to use export snippets:

#+options: inline-special-block-aliases:(("strong" :latex-command textbf
:html-tag strong :export "latex+ html+ odt*" ))

@strong{formatting}

or even:

@strong{@@latex:\latex{}: @@@@html:HTML: @@ formatting}

As defined, it is exported to LaTeX and HTML with all the formatting,
but only the content is exported to odt. The rest are not exported.
Maybe an "rest" option could be added, to avoid verbosity:

:export "latex+ html+ rest*"

(the complete format is exported to LaTeX and html and only the content to the rest).

However, I think that exporting this object to 'format-agnostic' backends,
such as plain text, would have to be implemented in a way that always
exports the content.

> Earlier I raised this issue during discussion of @@:...@@ syntax extension:
> Max Nikulin. Re: Org-syntax: Intra-word markup. Fri, 28 Jan 2022
> 21:52:17 +0700.
> https://list.orgmode.org/868df76e-69e0-1d14-ae8a-13b746982fcf@gmail.com
>
> Another case for backend predicates is whether it should be applicable
> to derived backends or just to explicitly specified ones.

I don't have a definite opinion. Maybe it would be nice to also take
into account derived backends...

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 11/03/2024 20:59, Juan Manuel Macías wrote:
>>
>> I have a bit different expectations in respect to export predicates.
>> It should be possible to express that some content should be exported
>> by all backend except the given list. The use case is fallback for
>> backends not covered by export snippets:
>>
>>      @@latex:\textbf{\LaTeX() formatting}@@@@html:<strong>HTML
>>      formatting</strong>@@@[...]{*for other backends}
> 
> I think that in your example (if I understand the intentions correctly)
> it would not even be necessary to use export snippets:
> 
> #+options: inline-special-block-aliases:(("strong" :latex-command textbf
> :html-tag strong :export "latex+ html+ odt*" ))

Your example uses a closed list of backends while "not (html or latex)" 
may be applicable to ascii, rst, some wiki dialects, etc. 
Backend-specific markup may be more complex and content of fallback 
option may be different from text used in export snippets. Perhaps I 
shouldn't give so simple example.

Side note: I expect that the new object will be more convenient than 
export snippets in most cases.

> :export "latex+ html+ rest*"

"rest" might be a valid backend name.

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> Your example uses a closed list of backends while "not (html or
> latex)" may be applicable to ascii, rst, some wiki dialects, etc.

Makes sense.

> Backend-specific markup may be more complex and content of fallback
> option may be different from text used in export snippets. Perhaps I
> shouldn't give so simple example.

I think I have understood the essentials, but perhaps it would be good
to see a slightly more complex scenario.

> Side note: I expect that the new object will be more convenient than
> export snippets in most cases.

I think so. In any case, although this object is proving pleasantly
versatile for us, I think we should not lose sight of the fact that its
main purpose is to be an inline text container with export properties.
Exports snippets are more for literal code inclusion. There can be
border uses between both objects, as there can also be with macros and
links. I suppose the ideal is to always choose the feature that best
suits a given context. One can put, for example @esindex[:export
latex+]{some word}, but in this case it would be more comfortable to put
@@latex:\esindex{some word}@@ or even use a macro.

>> :export "latex+ html+ rest*"
>
> "rest" might be a valid backend name.

I will try to implement the "rest" option.

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Stefan Nobis]

Juan Manuel Macías <maciaschain@posteo.net> writes:

>>> :export "latex+ html+ rest*"

>> "rest" might be a valid backend name.

> I will try to implement the "rest" option.

What about "others" or even ":others" as a placeholder for any not
explicitly mentioned export backend?

Another quick thought crossing my mind: May make "+" the default (so
"latex" means "latex+" and only use a marker char like '*' for
"content only")?

-- 
Until the next mail...,
Stefan.

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

In the last commit I have introduced some changes. Now this new feature
is no longer hardcoded in each backend but is controlled by an external
function in ox.el. I think this can simplify the implementation for
other backends.

As Stefan Nobis proposed, the "+" sign is now not necessary:

backend-name = full export

backend-name* = only contents

And the "rest" option is introduced, with the same syntax as before.

Examples:

@foo[:export noexport]{lorem ipsum dolor}

==> does not export anything

@foo[:export contents]{lorem ipsum dolor}

==> only contents

@foo[:export latex]{lorem ipsum dolor}

==> exports only to LaTeX

@foo[:export latex odt* html*]{lorem ipsum dolor}

==> exports everything to LaTeX, but to odt and HTML only the content

@foo[:export latex* rest]{lorem ipsum dolor}

==> content to LaTeX but full export to the rest of the backends

@foo[:export latex rest*]{lorem ipsum dolor}

==> the opposite of the above.

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 12/03/2024 20:45, Juan Manuel Macías wrote:
> 
> backend-name = full export
> backend-name* = only contents
> And the "rest" option is introduced, with the same syntax as before.
> 
> Examples:

It is not clear for me how to achieve the following. Add a link

[[https://youtube.com/...][Org mode in action demo (video)]]

for all backends (EPUB, LaTeX, ODT, text, etc.) besides HTML because 
there is an #+export_html block with player embedded using an iframe.

Instead of "noexport" and "rest" that may be confused with backend names 
I would consider "+" and "*" without any name. I would consider some 
characters like "-", "_", "!", "~" to express "do not export to this and 
derived backends" and "do not export for specified backend only".

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> It is not clear for me how to achieve the following. Add a link
>
> [[https://youtube.com/...][Org mode in action demo (video)]]
>
> for all backends (EPUB, LaTeX, ODT, text, etc.) besides HTML because
> there is an #+export_html block with player embedded using an iframe.

Sorry, I don't quite understand this. Could you please elaborate?

> Instead of "noexport" and "rest" that may be confused with backend
> names I would consider "+" and "*" without any name. I would consider
> some characters like "-", "_", "!", "~" to express "do not export to
> this and derived backends" and "do not export for specified backend
> only".

how about the following:

- "--" :: do not export

- "**" :: export only the content

- "==" :: rest (full)

- "=*" :: rest (only the content)

- "!backend-name+ :: export this backend (full)

- "!backend-name*" :: export this backend (only the content)

- "!backend-name- :: do not export this backend

?

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 13/03/2024 00:41, Juan Manuel Macías wrote:
> Max Nikulin writes:
> 
>> It is not clear for me how to achieve the following. Add a link
>>
>> [[https://youtube.com/...][Org mode in action demo (video)]]
>>
>> for all backends (EPUB, LaTeX, ODT, text, etc.) besides HTML because
>> there is an #+export_html block with player embedded using an iframe.
> 
> Sorry, I don't quite understand this. Could you please elaborate?

--- 8< ---
&_[:exports -html]{Watch [[https://youtube.com/...][Org mode in action 
demo]] video.}

#+begin_export html
<iframe src="https://youtube.com/embed/..."
  title="Org mode in action demo"
  width="..." height="..."></iframe>
#+end_export
--- >8 ---

should be exported to HTML without the sentence with the link
--- 8< ---
<iframe src="https://youtube.com/embed/..."
  title="Org mode in action demo"
  width="..." height="..."></iframe>
--- >8 ---

however only the sentence with the link is exported to LaTeX or any 
other format
--- 8< ---
Watch \href{https://youtube.com/...}{Org mode in action demo} video.
--- >8 ---

>> Instead of "noexport" and "rest" that may be confused with backend
>> names I would consider "+" and "*" without any name. I would consider
>> some characters like "-", "_", "!", "~" to express "do not export to
>> this and derived backends" and "do not export for specified backend
>> only".
> 
> how about the following:
> - "--" :: do not export
> - "**" :: export only the content
> - "==" :: rest (full)
> - "=*" :: rest (only the content)
> - "!backend-name+ :: export this backend (full)
> - "!backend-name*" :: export this backend (only the content)
> - "!backend-name- :: do not export this backend

I do not see why operator should be duplicated for backends that are not 
specified explicitly. Single "+" (default) or "-" should be enough. I 
have not got your idea with leading "!". From my point of view it is 
redundant.

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

>> how about the following:
>> - "--" :: do not export
>> - "**" :: export only the content
>> - "==" :: rest (full)
>> - "=*" :: rest (only the content)
>> - "!backend-name+ :: export this backend (full)
>> - "!backend-name*" :: export this backend (only the content)
>> - "!backend-name- :: do not export this backend
>
> I do not see why operator should be duplicated for backends that are not 
> specified explicitly. Single "+" (default) or "-" should be enough. I 
> have not got your idea with leading "!". From my point of view it is 
> redundant.

It was necessary with the previous implementation, which excessively
abused regexp. Not now (I want to do a few more tests and I'll make a
new commit with the changes). With the new implementation, now:

-  do not export

*  export only the content

= rest (full)

=* rest (contents only)

backend- do not export this backend (and the backends derived from it)

backend+ (or, perhaps, just "backend") export this backend (idem)

backend* export this backend (contents only) (idem)

I think your example with the video link would also be possible with the
new implementation.

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Juan Manuel Macías writes:

> It was necessary with the previous implementation, which excessively
> abused regexp. Not now (I want to do a few more tests and I'll make a
> new commit with the changes). With the new implementation, now:
>
> -  do not export
>
> *  export only the content
>
> = rest (full)
>
> =* rest (contents only)
>
> backend- do not export this backend (and the backends derived from it)
>
> backend+ (or, perhaps, just "backend") export this backend (idem)
>
> backend* export this backend (contents only) (idem)
>
> I think your example with the video link would also be possible with the
> new implementation.

Please try the latest commit:

@@[:export html-]{Watch [[https://youtube.com/...][Org mode in action demo]] video.}

#+begin_export html
<iframe src="https://youtube.com/embed/..."
  title="Org mode in action demo"
  width="..." height="..."></iframe>
#+end_export

It would not be exported to html or its derived backends.

(In your example you used `-html' instead of `html-'. I have no
preference for one variant or another).

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

To summarize the latest improvements and modifications to the `:export'
attribute...

The attribute supports one or more elements separated by a space. Each
element can be any of the following signs: "*" (export only the
content), "-" (do not export), "=" (export the rest normally), "=*"
(export the rest, but only the content), "=-" (do not export the rest).
Additionally, backend names can be given explicitly, alone or
accompanied by the "*" or "-" signs, that is (where "backend" equals the
name of the backend):

  backend: export normally for that backend and its derived backends;

  backend-: do not export for that backend or its derived backends.

  backend*: export only the content for that backend and its derived
  backends.

Some examples with valid combinations:

@foo[:export *]{lorem ipsum}

==> export only the content

@foo[:export -]{lorem ipsum}

==> do not export

@foo[:export latex-]{lorem ipsum}

==> do not export to LaTeX

@foo[:export latex- html* =]{lorem ipsum}

==> do not export to LaTeX, export only the content to html and export the
rest normally.

@foo[:export latex =*]{lorem ipsum}

==> export normally to LaTeX but export only the content to the rest

@foo[:export latex =-]{lorem ipsum}

==> export normally to LaTeX and not export to the rest

And below is a complete example based on a possible use case that Max
had exposed:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 To see a demo of the Fairlight CMI, watch @@[:export html =-]{this
 video} @@[:export
 html-]{[[https://www.youtube.com/watch?v=am0GBuS_7cE][this video]]}
 with Peter Vogel.
 
 #+begin_export html
 <iframe width="560" height="315"
 src="https://www.youtube.com/embed/am0GBuS_7cE?si=X7pghJhtdfOT1hby"
 title="YouTube video player"
 frameborder="0"
 allow="accelerometer;
 autoplay; clipboard-write; encrypted-media; gyroscope;
 picture-in-picture; web-share"
 allowfullscreen></iframe>
 #+end_export
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 15/03/2024 09:19, Juan Manuel Macías wrote:
> The attribute supports one or more elements separated by a space. Each
> element can be any of the following signs: "*" (export only the
> content), "-" (do not export), "=" (export the rest normally), "=*"
> (export the rest, but only the content), "=-" (do not export the rest).
> Additionally, backend names can be given explicitly, alone or
> accompanied by the "*" or "-" signs, that is (where "backend" equals the
> name of the backend):

1. "-" is a valid backend name and valid last character of backend name
2. From the description it is not clear to me what is effect of "rest" 
specified for more than one backend.

I have had into the code. I would expect something like the following 
(characters may be changed, the code is not heavily tested). Two 
characters from the following groups may be appended to backend name:

+ full (default)
* content
/ skip
(these ones may be used without backed name to specify fallback action)

= this and derived backends (default)
. this, but not derived backends
Perhaps it is necessary to add possibility that
these rules may coexist (use loop instead of assoc)

(ignore
  (pp
   (let ((rules
          (org-export--inline-special-block-make-backend-alist
           (org-split-string "latex/ html./ ascii+ *"))))
     (mapcar (lambda (backend)
               (list backend
                     (org-export--inline-special-block-export-decision 
rules backend)))
             '(odt latex beamer html md ascii)))))

Gives

((odt content)
  (latex nil)
  (beamer nil)
  (html nil)
  (md content)
  (ascii full))

Function definitions:

(defun org-export--inline-special-block-make-backend-alist
     (rules)
   (nconc
    (let (result)
      (dolist (spec rules)
        (if (string-match
 
"\\`\\([-_a-zA-Z0-9]*\\)\\(?:\\([/+*]\\)\\|\\([=.]\\)\\([/+*]\\)?\\)?\\'"
             spec)
            (let ((name (match-string 1 spec))
                  (inherit (match-string 3 spec))
                  (what (or (match-string 2 spec)
                            (match-string 4 spec))))
	     (push (cons
                     (if (string-equal "" name) '@ (intern name))
                     (cons (or (not inherit) (string-equal inherit "="))
                           (if what (string-to-char what) ?+)))
		   result))
	 (message "invalid :export specification %S" spec)))
      result)))

(defun org-export--inline-special-block-export-decision
     (rules-alist backend)
   (when (symbolp backend)
     (setq backend (org-export-get-backend backend)))
   (let* ((rule (assoc (org-export-backend-name backend) rules-alist))
	 (decision (and rule (cddr rule))))
     (while (and (not decision)
		(setq backend (org-export-backend-parent backend)))
       (setq backend (org-export-get-backend backend))
       (when (and (setq rule (assq (org-export-backend-name backend) 
rules-alist))
                  rule
                  (cadr rule))
         (setq decision (cddr rule))))
     (unless decision
       (setq rule  (assq '@ rules-alist))
       (setq decision (and rule (cddr rule))))
     (pcase decision
       (?+ 'full)
       (?* 'content)
       (?/ nil)
       (_ 'full))))

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 15/03/2024 21:00, Ihor Radchenko wrote:
> Max Nikulin writes:
> 
>> 1. "-" is a valid backend name and valid last character of backend name
> 
> I am not following this branch of the discussion closely, but what about
> not inviting a new DSL here and instead using Elisp sexps here?
> Something like (latex body) (html none) ((not (or latex html)) contents)

I do not mind in general. Just a couple of questions:
- How to specify whether the rule should be applied to derived backends?
- Is there a ready to use function that can interpret such expressions?

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Thank you for your comments.

Max Nikulin writes:

> On 15/03/2024 09:19, Juan Manuel Macías wrote:
>> The attribute supports one or more elements separated by a space. Each
>> element can be any of the following signs: "*" (export only the
>> content), "-" (do not export), "=" (export the rest normally), "=*"
>> (export the rest, but only the content), "=-" (do not export the rest).
>> Additionally, backend names can be given explicitly, alone or
>> accompanied by the "*" or "-" signs, that is (where "backend" equals the
>> name of the backend):
>
> 1. "-" is a valid backend name and valid last character of backend name

I had not thought of it. Can + also be a valid character? 

> 2. From the description it is not clear to me what is effect of "rest"
> specified for more than one backend.

'rest' (=) is equivalent to the rest of the backends that have not been
explicitly set. What happens is that, with my current approach, if you
want to export only one backend, you must enter:

:export backend =- (that is, export this backend and not the rest)

This is not ideal. It should be enough to just put:

:export backend

but I am not able to achieve it.

> I have had into the code. I would expect something like the following
> (characters may be changed, the code is not heavily tested). Two
> characters from the following groups may be appended to backend name:
>
> + full (default)
> * content
> / skip
> (these ones may be used without backed name to specify fallback action)
>
> = this and derived backends (default)
> . this, but not derived backends
> Perhaps it is necessary to add possibility that
> these rules may coexist (use loop instead of assoc)

OK. How about the following?

- Single characters (they affect everything, if backend name is not
  specified, or the rest, if backend name is specified:
  
  * content
  / skip
  . never export derived backends
  = full, this and derived backends (default)

- And in combination with backend names (some examples):

  :export latex* > content to LaTeX, normal to the rest
  
  :export latex/ > do not export to LaTeX

  :export latex. > do not export to LaTeX derived backends

  :export latex . > export normally to LaTeX but do not export the derived backends in the rest of the cases

  etc.

These days I'm going to be a little short on time, due to work, and I
don't know if I'll be able to attend to the list. I want to calmly take
a look at the code you share.

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> 1. "-" is a valid backend name and valid last character of backend name

I am not following this branch of the discussion closely, but what about
not inviting a new DSL here and instead using Elisp sexps here?
Something like (latex body) (html none) ((not (or latex html)) contents)

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

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

>> I am not following this branch of the discussion closely, but what about
>> not inviting a new DSL here and instead using Elisp sexps here?
>> Something like (latex body) (html none) ((not (or latex html)) contents)
>
> I do not mind in general. Just a couple of questions:
> - How to specify whether the rule should be applied to derived backends?
> - Is there a ready to use function that can interpret such expressions?

Good question. I guess that what I propose is still a new DSL at the
end... Oh well.

I guess that the closest existing DSL would be what `buffer-match-p'
function uses.

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

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> (ignore
>  (pp
>   (let ((rules
>          (org-export--inline-special-block-make-backend-alist
>           (org-split-string "latex/ html./ ascii+ *"))))
>     (mapcar (lambda (backend)
>               (list backend
>                     (org-export--inline-special-block-export-decision
>                     rules backend)))
>             '(odt latex beamer html md ascii)))))
>
> Gives
>
> ((odt content)
>  (latex nil)
>  (beamer nil)
>  (html nil)
>  (md content)
>  (ascii full))
>
> Function definitions:
>
> (defun org-export--inline-special-block-make-backend-alist
>     (rules)
>   (nconc
>    (let (result)
>      (dolist (spec rules)
>        (if (string-match
>
> "\\`\\([-_a-zA-Z0-9]*\\)\\(?:\\([/+*]\\)\\|\\([=.]\\)\\([/+*]\\)?\\)?\\'"
>             spec)
>            (let ((name (match-string 1 spec))
>                  (inherit (match-string 3 spec))
>                  (what (or (match-string 2 spec)
>                            (match-string 4 spec))))
> 	     (push (cons
>                     (if (string-equal "" name) '@ (intern name))
>                     (cons (or (not inherit) (string-equal inherit "="))
>                           (if what (string-to-char what) ?+)))
> 		   result))
> 	 (message "invalid :export specification %S" spec)))
>      result)))
>
> (defun org-export--inline-special-block-export-decision
>     (rules-alist backend)
>   (when (symbolp backend)
>     (setq backend (org-export-get-backend backend)))
>   (let* ((rule (assoc (org-export-backend-name backend) rules-alist))
> 	 (decision (and rule (cddr rule))))
>     (while (and (not decision)
> 		(setq backend (org-export-backend-parent backend)))
>       (setq backend (org-export-get-backend backend))
>       (when (and (setq rule (assq (org-export-backend-name backend)
>       rules-alist))
>                  rule
>                  (cadr rule))
>         (setq decision (cddr rule))))
>     (unless decision
>       (setq rule  (assq '@ rules-alist))
>       (setq decision (and rule (cddr rule))))
>     (pcase decision
>       (?+ 'full)
>       (?* 'content)
>       (?/ nil)
>       (_ 'full))))

I've been testing your code and it works very well. It is certainly
finer than the current approach. I think it could be implemented, and we
are testing that.

Tomorrow I will make a new commit with your code.

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 15/03/2024 20:10, Juan Manuel Macías wrote:
> Max Nikulin writes:
>>
>> 1. "-" is a valid backend name and valid last character of backend name
> 
> I had not thought of it. Can + also be a valid character?

https://orgmode.org/worg/org-syntax.html#Affiliated_Keywords
BACKEND
     A string consisting of alphanumeric characters, hyphens, or 
underscores (-_).

>> 2. From the description it is not clear to me what is effect of "rest"
>> specified for more than one backend.
> 
> 'rest' (=) is equivalent to the rest of the backends that have not been
> explicitly set. What happens is that, with my current approach, if you
> want to export only one backend, you must enter:
> 
> :export backend =- (that is, export this backend and not the rest)

At first I thought it may be used as [:export backend=-] and it is the 
reason why I was confused. However I still do not see difference between 
[:export backend -] and [:export backend =-].

> This is not ideal. It should be enough to just put:
> 
> :export backend
> 
> but I am not able to achieve it.

I agree, it is intuitive, but it makes formal rules more complicated.

>    = full, this and derived backends (default)

I would prefer to modify code to handle
[:export latex.+ latex=/]
to apply first declaration (content only) to latex and second one (skip) 
to derived backends. Anyway the code requires optimization. Walk through 
parent backends is likely inefficient.

> These days I'm going to be a little short on time, due to work, and I
> don't know if I'll be able to attend to the list.

Then I will postpone other questions (mostly unrelated to :export).

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 15/03/2024 23:26, Juan Manuel Macías wrote:
> Tomorrow I will make a new commit with your code.

An update with a couple of bugs fixed. Now it is possible to specify 
different export rules for a backend and all its derivatives:

(ignore
  (pp
   (let ((rules
          (org-export--inline-special-block-make-backend-list
           (org-split-string "latex/ html./ html+= ascii+ *"))))
     (mapcar (lambda (backend)
               (let ((hierarchy
                      (org-export--backend-hierarchy backend)))
                 (list backend
                       (org-export--inline-special-block-export-decision
                        rules hierarchy))))
             '(odt latex beamer html md ascii)))))

((odt content)
  (latex nil)
  (beamer nil)
  (html nil)
  (md full)
  (ascii full))

----

(defun org-export--inline-special-block-make-backend-list
     (rules)
   (let (result)
     (dolist (spec rules)
       (if (string-match
 
"\\`\\([-_a-zA-Z0-9]*\\)\\(?:\\([/+*]\\)\\([=.]\\)?\\|\\([=.]\\)\\([/+*]\\)?\\)?\\'"
            spec)
           (let ((name (match-string 1 spec))
                 (inherit (or (match-string 3 spec)
                              (match-string 4 spec)))
                 (what (or (match-string 2 spec)
                           (match-string 5 spec))))
	    (push (cons
                    (if (string-equal "" name) '@ (intern name))
                    (cons (or (not inherit) (string-equal inherit "="))
                          (if what (string-to-char what) ?+)))
		  result))
	(message "invalid :export specification %S" spec)))
     (nreverse result)))

(defun org-export--backend-hierarchy (backend)
   "Result may be cached in INFO."
   (let ((hierarchy))
     (when (not (symbolp backend))
       (setq backend (org-export-backend-name backend)))
     (while backend
       (push backend hierarchy)
       (setq backend (org-export-backend-parent
                      (org-export-get-backend backend))))
     hierarchy))

(defun org-export--inline-special-block-export-decision
     (rule-list hierarchy)
   (let ((hierarchy (cons '@ hierarchy))
         (decision ?+))
     (while (and hierarchy rule-list)
       (let* ((rule (pop rule-list))
              (tail (memq (car rule) hierarchy)))
         (when (and tail
                    (or (not (cdr tail)) ; Current backend.
                        (cadr rule))) ; Inherits.
           (setq hierarchy (cdr tail))
           (setq decision (cddr rule)))))
     (pcase decision
       (?+ 'full)
       (?* 'content)
       (?/ nil)
       (_ 'full))))

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> An update with a couple of bugs fixed. Now it is possible to specify
> different export rules for a backend and all its derivatives:

I have implemented your code in the last commit. I think it is a great
improvement, thanks a lot.

As I mentioned in a past email, these days I will be somewhat busy, but
I will try to keep up to date with your comments. Although it may take a
while to respond.

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 19/03/2024 02:42, Juan Manuel Macías wrote:
> As I mentioned in a past email, these days I will be somewhat busy, but
> I will try to keep up to date with your comments. Although it may take a
> while to respond.

Would you mind against new thread as an umbrella for next bunch of 
topics? Current one becomes too large from my point of view.

For a while a couple of questions related to :export to think on.

I am afraid that :export will cause confusion with :exports for source 
code blocks. Its name differs by just "s" but possible values have 
nothing common.

Another issue is more general and should apply e.g. to HTML attributes 
as well. Consider

--- 8< ---
#+options: inline-special-block-aliases:(("kbd" :export "html*" 
:html-tag kbd))
@kbd{Default} and @kbd[:export "latex*"]{LaTeX}
--- >8 ---

It exports to

     <p>\nDefault and <kbd class="kbd">LaTeX</kbd></p>

I would expect that "html*" is inherited from the parent declaration and 
"latex*" does not override it, so

     <p>\nDefault and LaTeX</p>

On the other hand it should be possible to specify that declared earlier 
rules should be taken into consideration. E.g. "#" might stop further 
processing:

--- 8< ---
#+options: inline-special-block-aliases:(("kbd" :export "html*" 
:html-tag kbd))
@kbd{Default} and @kbd[:export "latex* #"]{LaTeX}
--- >8 ---

makes

     <p>\nDefault and <kbd class="kbd">LaTeX</kbd></p>

result valid.

In the meanwhile I have realized that there is no point in the list of 
parsed rules. You may consider code organized in a bit different way. I 
hope, just a single extra line in these helpers is required to support "#".

(defun org-export--parse-export-rule
     (spec)
   (and (string-match
 
"\\`\\([-_a-zA-Z0-9]*\\)\\(?:\\([/+*]\\)\\([=.]\\)?\\|\\([=.]\\)\\([/+*]\\)?\\)?\\'"
         spec)
        (let ((name (match-string 1 spec))
              (inherit (or (match-string 3 spec)
                           (match-string 4 spec)))
              (what (or (match-string 2 spec)
                        (match-string 5 spec))))
	 (cons
           (if (string-equal "" name) '@ (intern name))
           (cons (or (not inherit) (string-equal inherit "="))
                 (pcase (and what (string-to-char what))
                   ((or ?+ (pred null)) 'full)
                   (?* 'content)
                   (?/ nil)))))))
;; (org-export--parse-export-rule "html+=")

(defun org-export--backend-hierarchy (backend)
   "Result may be cached in INFO."
   (let ((hierarchy))
     (when (not (symbolp backend))
       (setq backend (org-export-backend-name backend)))
     (while backend
       (push backend hierarchy)
       (setq backend (org-export-backend-parent
                      (org-export-get-backend backend))))
     hierarchy))
;; (org-export--backend-hierarchy 'md)

(defun org-export--inline-special-block-export-decision
     (spec-list hierarchy &optional default-rule)
   "Returns (backend inherit . what).
so use `cddr' to get decision."
   (let ((decision '(@ t . full))
         (hierarchy (cons '@ hierarchy)))
     (while (and hierarchy spec-list)
       (let* ((rule (org-export--parse-export-rule (pop spec-list)))
              (tail (and rule (memq (car rule) hierarchy))))
         (if (not rule)
	    (message "invalid :export specification %S" (car spec-list)))
         (when (and tail
                    (or (not (cdr tail)) ; Current backend.
                        (cadr rule))) ; Inherits.
           (setq hierarchy (cdr tail))
           (setq decision rule))))
     (if (and default-rule (memq (car default-rule) hierarchy))
         default-rule
       decision)))

----

(ignore
  (pp
   (let ((rules (org-split-string "latex/ html./ html+= ascii+ *")))
     (mapcar (lambda (backend)
               (let ((hierarchy
                      (org-export--backend-hierarchy backend)))
                 (list backend
                       (cddr
                        (org-export--inline-special-block-export-decision
                         rules hierarchy)))))
             '(odt latex beamer html md ascii)))))

((odt content)
  (latex nil)
  (beamer nil)
  (html nil)
  (md full)
  (ascii full))

Re: `:export' attribute?: Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Max Nikulin writes:

> Would you mind against new thread as an umbrella for next bunch of 
> topics? Current one becomes too large from my point of view.

Ok, I agree. I suggest that from now any new thread related to the new
object have as subject:

"inline-special-block: specific topic to discuss".

Tomorrow I will try to answer all the latest questions related to the
export rules.

inline-special-block: export rules (was: `:export' attribute?: Re: Experimental public branch for inline special blocks)

[Juan Manuel Macías]

Max Nikulin writes:

> I am afraid that :export will cause confusion with :exports for source 
> code blocks. Its name differs by just "s" but possible values have 
> nothing common.

I agree. At the moment two alternative names come to mind: :backends or
:export-rules

> Another issue is more general and should apply e.g. to HTML attributes 
> as well. Consider
>
> --- 8< ---
>
> #+options: inline-special-block-aliases:(("kbd" :export "html*" 
> :html-tag kbd))
>
> @kbd{Default} and @kbd[:export "latex*"]{LaTeX}
> --- >8 ---
>
> It exports to
>
>      <p>\nDefault and <kbd class="kbd">LaTeX</kbd></p>
>
> I would expect that "html*" is inherited from the parent declaration and 
> "latex*" does not override it, so
>
>      <p>\nDefault and LaTeX</p>

But it is the expected result in all attributes. If an attribute of the
same type as the one declared in the alias is added, the value is
overwritten.

In any case, since in this case the attribute allows cumulative values,
I think the approach should be at the level of the attribute name itself
and not the code to manage the export rules. For example:

:export [or whatever new name we give it] ==> normal behavior, overwrites the values

:export+ ==> adds the new values to the values defined in the alias

This syntax could also be extended to other cases. Perhaps we want
attributes like :prelatex, :postlatex, or :html to support accumulating
values. It could be easily solved from the functions of each backend. In
other cases, of course, it wouldn't make sense (a block can't have two
languages at the same time), but in that scenario, if someone puts
:lang+, it simply wouldn't be taken into account. Wdyt?

Re: inline-special-block: export rules

[Max Nikulin]

On 21/03/2024 17:26, Juan Manuel Macías wrote:
> Max Nikulin writes:
> 
>> I am afraid that :export will cause confusion with :exports for source
>> code blocks. Its name differs by just "s" but possible values have
>> nothing common.
> 
> I agree. At the moment two alternative names come to mind: :backends or
> :export-rules

I find :export-rules too abstract. Unless a better name is proposed, I 
prefer :backends.

> :export [or whatever new name we give it] ==> normal behavior, overwrites the values
> :export+ ==> adds the new values to the values defined in the alias

Vim for options allowing list of values has several options
:set opt=value1,value2 " assign new value
:set opt+=value " add to list
:set opt-=value " remove from list if it is there
:set opt& " reset to default value
I am unsure whether all variants should be implemented.

> This syntax could also be extended to other cases. Perhaps we want
> attributes like :prelatex, :postlatex, or :html to support accumulating
> values.

Certainly :export (:backends) is not the only property that should 
accumulate values.

Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> Finally, I have made public on GitLab my experimental branch for the new
> (possible) inline-special-block element:
>
> <https://gitlab.com/maciaschain/org-mode.git>

I have finally finished my review of the previous related discussions.
See my comments and proposals below.

[ Aside: It looks like your public branch is not up-to-date as the time
  of writing this email - I do not see commits changing the syntax to
  @foo{...} and @@{...} yet, as discussed in
  https://list.orgmode.org/orgmode/87sf121e9t.fsf@localhost/)
  I have edited your original message in the quotes to reflect upon the
  newly agreed syntax. ]

---------------------

> The basic syntax:
> @foo{lorem ipsum dolor}

> There is also an anonymous variant:
> @@{lorem ipsum dolor}

> Optional attributes in square brackets are supported
> @foo[:key1 value1 :key2 value2 ...]{lorem ipsum dolor}

Let me list the main goals of the new inline markup within the scope of
overall Org markup and discuss whether the proposed syntax can work to
achieve them.

1. Introduce user-configurable ad-hoc syntax where exporting and
   fontification are fully configurable on Elisp level, per-document
   level, and maybe even per-markup level. Something combining
   flexibility of links and special blocks, but without their
   limitations:

   - In contrast to links, we should be able to nest inline markup
     without restrictions:

     @foo{@bar{text}} ([[foo:a][[[bar:b]]]] is not possible)

     ***This goal is covered by the branch***

   - We should be able to have arbitrary text inside inline markup.
     No sequence of symbols should be prohibited:

     @foo{ can contain leading and trailing spaces }
     @foo{can contain "}" inside, especially inside =verbatim }= text} <-- **ambiguous**
     @foo{can even have "}" at the end boundary}} <-- **ambiguous**
     This is unlike links that prohibit closing "]".

     ***For the above examples, the proposed syntax is ambiguous***

    - We should be able to define special markup for code, where the
      contents is not parsed. Something like

      @code{ unlike =code=, we can have leading and trailing spaces }
      @code{ @foo{is not interpreted inside}}

      ***This goal is not addressed by the experimental branch for now***

2. Allow attaching auxiliary attributes to the on object level, as an
   equivalent of affiliated keywords on element level

   - For example, we should allow assigning height per-link without the
     awkward kludge we have with special handling of
     
     #+attr_html: :height 300
     [[file:image.png]] has a height of 300, but what if we want a
     different height in [[file:another-image.png]]?

     We can thus do
     
     #+attr_html: :height 300
     [[file:image.png]] has a height of 300, but what if we want a
     different height in @@[:html-height 300]{[[file:another-image.png]]}?

     Note how @@{...} markup assigns attributes to objects inside - the
     attributes should be somehow inherited.

     Another example is the proposed @@[:lang "en"]{...} attribute - we
     may want to assign it even beyond current paragraph; for example
     for the whole subtree (aka mark subtree language to be "English").

     ***This is not covered by the branch***

   - We should also be able to assign attributes that contain Org markup
     themselves:

     @@[:alt This image shows a _cat_ climbing a /wall/]{<file:cat.png>}

     ***This is not covered by the branch***

3. The new syntax should allow us to do anything Texinfo markup can do
   (as per RMS request https://list.orgmode.org/orgmode/87bkqx4jyg.fsf@localhost/)

   - Multi-argument markup in Texinfo like for abbreviations
     @abbr{abbreviation[,meaning]}

     Example: @abbr{Comput. J., Computer Journal}
     (https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#g_t_0040abbr)

     We can equivalently (if markup inside attributes is supported) do

     @abbr[:meaning Computer Journal]{Comput. J.}
     or even
     @abbr[Computer Journal]{Comput. J.}

     In theory, we may need even more than 2 arguments.

     ***This is partially covered***

4. The new syntax should allow working around ambiguities of the *DWIM*
   markup without using the awkward zero-width space kludge

   - Intra-word markup

      foo@bold{bar}baz
      
      ***This is covered already***

   - Simultaneous markup
   
     @bold{foo}@italic{bar}
     @@{*foo*}@@{/bar/}

      ***This is covered already***

   - Solving the undesired first-fit-wins parser behaviour:

     /italics stops [[early/?here]], but not later/
     need to *escape stars* like that one*
     你好。*我*不会些这个

     @italic{italics stops [[early/?here]], but not later}
     need to @bold{escape stars* like that one}
     你好。@bold{我}不会些这个

      ***This is covered already***


--------
Proposed modifications to the inline markup syntax
-------

1. @foo{basic form remains the same}

2. @foo{{but we allow arbitrary number of "{{..." to open the markup.
   Then, } inside does not end the @foo markup; we only end it at the
   matching number of }s; "{" and "}" inside do not have to be balanced.}}

3. @foo[alternative brackets]

   In an edge case, when the contents itself is {...}, allow alternative
   brackets

   @foo[{contents surrounded by curly braces}]

4. We also have a special form of syntax where the contents is not at all
   parsed

   @code{this is *verbatim* code; it may contain = or even have
   whitespace at the boundaries                    }

   This is equivalent to #+begin_example example blocks vs.
   #+begin_<arbitrary> special blocks.

   @code{{can also contain "}" inside, using multiple bracket
   alternative}}

   @code[{or be like this}]

5. Change the @foo[:key1 value1 :key2 value2 ...]{lorem ipsum dolor}
   syntax:

   @foo[can have][multiple][arguments]{the last argument is considered object contents}

   Every argument is parsed

   @title[This is an image title, with *markup*]{<file:image.png>}
   @@[:lang cn :alt Hello]{你好}
   @@[:lang cn][:alt Hello]{你好}

   The exporters are responsible to interpret the arguments as needed,
   if keyword arguments are passed.

   We should also not layer additional rules for escaping delimiters
   apart from the existing Org mode markup:

   @@[:lang cn :alt @@{can have :keyword-like inside, insulated inside =@@{...}=}]{...}
   @@[:lang cn][:attr_latex @@{:color blue}]{...}

   This is akin affiliated keywords that are never split into
   keyword/value pairs by org-element, leaving this job downstream to
   specific commands and libraries.
   (The difference is that affiliated keywords are mostly not parsed,
   but parsing is necessary here to address multi-argument markup syntax
   like @abbrev)

-------
Attribute inheritance
-------

As I described in @@[:html-height 300]{[[file:another-image.png]]}
example, we should have some form of attribute inheritance, so that we
are able to assign attributes to arbitrary Org markup, not just to
inline markup objects.

Furthermore, attributes like @@[:lang cn][好工作] may need to be
assigned to the text spanning across multiple paragraphs or even
headings.

I suggest following what we already do for source blocks:

1. org-babel-default-header-args sets global attributes applicable to
   everything globally
2. org-babel-default-header-args:<lang> sets global attributes
   per-language
3. #+PROPERTY: header-args <attributes> sets global attributes per-file
4. #+PROPERTY: header-args:<lang> <attributes> sets language-specific
   attributes
5. :HEADER-ARGS: or :HEADER-ARGS:<lang>: set attributes per-subtree
6. #+HEADERS: <attributes> sets src block attributes
7. Attribute values are merged together:

   org-babel-default-header-args = :cache yes :export none
   #+HEADERS: :cache no :var x=1
   combines into
   :export none :cache no :var x=1

I propose the following naming for inline markup:

  org-default-inline-attributes
  org-default-inline-attributes:<foo>
  #+PROPERTY: inline_attr
  #+PROPERTY: inline_attr:<foo>
  #+INLINE_ATTR: affiliated
  #+INLINE_ATTR:<foo>:

In addition, attributes from @@[:alt Text]{<file:image.png>} are applied
to all the markup inside, including normal non-inline markup objects.

Further, we may allow a special attribute :inherit that will allow more
fine-grained control on where to inherit the attributes from:

#+inline_attr:var: :inherit example
@example[:color gray]{(defvar @var{variable-name} nil)}

As an option, I am not yet sure about, we may also allow per-keyword
control like

@bold[:export latex rest*]{and some more @bold[:export+ html]{inside}}

so that :export and :export+ are combined.

(Despite me using :export example here, what I am proposing is not
limited to :export keyword that have been discussed in-depth in
https://list.orgmode.org/orgmode/87bk7k7tuf.fsf@posteo.net/)

> Optional attributes in square brackets are supported. There are a series
> of 'universal' attributes, common to each backend. At the moment:
> `:lang', `:color' and `:smallcaps'. Example:

-------
On :lang attribute
-------

This attribute is special - language of a text is actually _not_ a
markup. It is more global, and it does not quite fit within the framework
of per-markup type inheritance.

In contrast to something like
@foo[:export latex rest*]{@bar{should be exported everywhere}}
:lang attribute applies to all types of markup inside
@foo{:lang cn}{@bar{公共汽车}}

Moreover, we may want to apply it per-paragraph or per-subtree.

So, we may want to

1. Combine all the nested inline :lang attributes regardless of the
   inline markup types nesting
2. Introduce a new affiliated keyword #+LANGUAGE
3. Introduce a new subtree property :LANGUAGE:
4. Re-use #+LANGUAGE: per-document keyword
5. Use the previous 4 rules to :lang attributes as a special case.

Then, export backends should implement :lang attribute support and ox.el
should provide the means to query it, performing all the necessary
inheritance calculations.

-------
Configurable inline markup export
-------

Given that the discussed inline markup is supposed to improve on the
link export flexibility, and also add more ad-hoc export setting
options, I have the following necessary features in mind:

1. We should have an equivalent of :export link parameter
   This will be Elisp level interface for inline markup, allowing to
   write Org mode syntax extensions (like the one necessary for Texinfo
   feature-parity)

   ***This is not covered by the branch***

2. We should expose per-document ad-hoc markup customization that does
   not require Elisp. Something similar to link abbreviations or macros.

   However, I do not want the inline markup to turn into another variant
   of macros. So, I do like the proposal to define only attributes:

> ┌────
> │ #+options: inline-special-block-aliases:(("latin" :lang "la" :latex-command "textit" :html-tag "em"))
> │ 
> │ Caesar's famous quote: @latin{Alea iacta est}
> │ 
> │ Caesar's famous quote: @latin[:smallcaps t :color blue]{Alea iacta est}
> └────

However, I am not a big fan of the way it is implemented - Elisp syntax
with the need to layer all the (...) and "...".

We may instead re-use my attribute inheritance idea:

#+PROPERTY: inline_attr:latin :lang la :latex-command textit :html-tag em

-------
On :color and :smallcaps attributes or user-customized markup
-------

These proposed attributes are nothing but additional markups that will
become a part of Org mode syntax. I see them as nothing different from
@smallcals{...} and @color{blue}{...} inline markups.

I am not in favour of adding such extra markup to Org mode syntax.
Instead, we can make it a part of inline markup extensions, in parallel
with what we need to support Texinfo-specific markup like @var, @defun,
etc.

I also do not see any clear benefit of adding :color and :smallcaps as
_attributes_. Just markup will do. If one needs to combine
smallcaps/color with other markup, it is a job for ad-hoc markup
definitions.

-------
pre/post-latex (aka templates)
-------

> Specific to the LaTeX backend we have the `:prelatex' and `:postlatex'
> attributes (which introduce arbitrary code before and after the content)
> and `:latex-command', which overrides the exported command.
> `:latex-command nocommand' does not export a command flag. Examples:
>
> ┌────
> │ @foo[:prelatex [bar] :postlatex {baz} :lang it :latex-command blah]{lorem ipsum dolor}
> └────

I do not like the idea of pre/post-<exporter> attributes.
I think that we discussed this particular idea in the past, when talking
about prepending/appending commands like \newpage to headings during
LaTeX export
(https://list.orgmode.org/orgmode/87czbna4e4.fsf@localhost/)

There, I proposed to use a more generalized approach, allowing custom
export templates:

* headline
:PROPERTIES:
:ATTR_BACKEND: :export_template "\begin{myenv}\n%s\n\end{myenv}"
:ATTR_BACKEND+: "The %%s instances are replaced by the exported element"
:ATTR_BACKEND+: (concat "arbitrary sexp, the exported element is bound to: " *this*)
:ATTR_BACKEND+: babel_block_name(exported=*this*)
:ATTR_BACKEND+: "the property lines are concatenated with \" \" (space),"
:ATTR_BACKEND+: "just like the usual approach in `org-export-read-attribute'"
:END:

We can apply the same approach when defining ad-hoc markup, extending it
a little. Rather than using %s, we introduce more placeholders:

   - %contents :: like CONTENTS argument in the export transcoders
   - %transcoded :: the result of what the export backend returns normally
   - %:<number> :: reference to last Nth optional argument. For example
        in @abbrev{Computer Science}{CS} %contents == CS and %:1 =
        Computer Science
   - %:attribute :: the value of attribute

This way,

@@[:prelatex \foo{bar} :color red]{lorem ipsum dolor}

will become

@foo[:latex-template @code[{\color{red}\foo{bar}%contents}]]{lorem ipsum dolor}

-------
On :export attribute
-------

> I'm thinking about adding a new global attribute, `:export', that
> would granularly control whether or not to export the object and how to
> export it.
>
> Possible values: "noexport", "contents" (it would export only the content)
> or the backends to which you want to export, separated by spaces. Each
> backend should be followed by a "+" sign (= export all) or "*" (export
> content only). For example:
>
> @foo[:color red :export latex+ odt* html*]{lorem ipsum dolor}

Similar to :lang attribute, I see this idea to be more general than
inline markup scope. It does not have to be applicable only to inline
markup. We can extend selective export further - to paragraph-level
elements and to headings.

Recently, we even got a feature request to
exclude/include certain subtrees from export for specific backends:
https://list.orgmode.org/orgmode/1008678740.100388.1708624390334@fidget.co-bxl/

So, we can approach this just like for :lang attribute, except that we
do not need special handling with unconditional inheritance for all the
inline markup

1. Allow :lang attributes and make them follow standard inheritance
   rules 
2. Introduce a new affiliated keyword #+EXPORT
3. Introduce a new subtree property :EXPORT:
4. Introduce #+EXPORT: per-document keyword
5. (optional) Introduce new #+SELECT_TAGS:BACKEND:
   #+EXCLUDE_TAGS:BACKEND to allow excluding/selecting subtrees by tag
   (more visible compared to properties)

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

Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 09/04/2024 15:52, Ihor Radchenko wrote:
> Aside: It looks like your public branch is not up-to-date as the time
>    of writing this email - I do not see commits changing the syntax to
>    @foo{...} and @@{...} yet,

Do you have in your local copy the following?

latest commit

ba2fc870c 2024-03-18 20:28:19 +0100 Juan Manuel Macías Chaín: * 
lisp/ox.el: More sensible export rules.

and

97a26a30d 2024-03-07 19:16:01 +0100 Juan Manuel Macías Chaín: * 
lisp/org-element.el: `@' instead of `_' for the anonymous variant.
b2b4d0177 2024-03-07 16:42:58 +0100 Juan Manuel Macías Chaín: * 
lisp/org-element.el: New syntax: `@' instead of `&'.

P.S. In your message I see most of my questions I have not asked.

Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Max Nikulin <manikulin@gmail.com> writes:

> On 09/04/2024 15:52, Ihor Radchenko wrote:
>> Aside: It looks like your public branch is not up-to-date as the time
>>    of writing this email - I do not see commits changing the syntax to
>>    @foo{...} and @@{...} yet,
>
> Do you have in your local copy the following?
> ...

I do now. Apparently, I somehow reviewed an earlier local copy of the
branch.

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

Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> Max Nikulin <manikulin@gmail.com> writes:
>
>> On 09/04/2024 15:52, Ihor Radchenko wrote:
>>> Aside: It looks like your public branch is not up-to-date as the time
>>>    of writing this email - I do not see commits changing the syntax to
>>>    @foo{...} and @@{...} yet,
>>
>> Do you have in your local copy the following?
>> ...
>
> I do now. Apparently, I somehow reviewed an earlier local copy of the
> branch.

Hi, Ihor. Thanks for all your comments. I will try to answer each of the
questions you have raised. Let's see if I can find a space next week...

The latest added to the branch are Maxim's proposals (and code) for
backend control. See this thread:

https://list.orgmode.org/?t=20240321102752

And this other thread, continuation of the previous one:

https://list.orgmode.org/877ciavnwo.fsf_-_@posteo.net/

Best regards,

Juan Manuel 

Re: Experimental public branch for inline special blocks

[Max Nikulin]

On 02/03/2024 03:34, Juan Manuel Macías wrote:
> Finally, I have made public on GitLab my experimental branch for the new
> (possible) inline-special-block element:
> 
> <https://gitlab.com/maciaschain/org-mode.git>

Next part of this thread:

Max Nikulin. inline-special-block: part2. Thu, 11 Apr 2024 17:49:40 +0700.
https://list.orgmode.org/0f1351e2-cb5e-4b65-9faf-c6e78f15c975@gmail.com

Previous discussion:

Juan Manuel Macías. [proof of concept] inline language blocks. Tue, 20 
Feb 2024 20:35:04 +0000.
https://list.orgmode.org/87msrudgcn.fsf@posteo.net

Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> The latest added to the branch are Maxim's proposals (and code) for
> backend control. See this thread:
>
> https://list.orgmode.org/?t=20240321102752
>
> And this other thread, continuation of the previous one:
>
> https://list.orgmode.org/877ciavnwo.fsf_-_@posteo.net/

I have seen these two branches and my comments account for them.

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

Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> Juan Manuel Macías <maciaschain@posteo.net> writes:
>
>> The latest added to the branch are Maxim's proposals (and code) for
>> backend control. See this thread:
>>
>> https://list.orgmode.org/?t=20240321102752
>>
>> And this other thread, continuation of the previous one:
>>
>> https://list.orgmode.org/877ciavnwo.fsf_-_@posteo.net/
>
> I have seen these two branches and my comments account for them.

Ok. Although I will try to answer all your comments in detail [if it's
okay, I can start a new thread called "inline-special-block: general
discussion"] I can anticipate that I would be in favor of removing
global attributes (:smallcaps, :lang, :color). At first I didn't think
it was a bad idea to have certain «pre-cooked» attributes. But later I
realized that the implementation of each backend where it makes sense to
apply these attributes is unnecessarily complicated. Furthermore, the
very flexibility of the new object allows the same goal to be achieved.

Well, next week I will continue commenting. I will try to stay up to
date with everything that is being discussed here. By the way, if
someone wants to collaborate on the branch, I can add them as a
contributor (I'm afraid it is necessary to have a GitLab account, if
I'm not mistaken).

Attributes on images (was:: Experimental public branch for inline special blocks)

[Rick Lupton]

Thanks for taking the time to comment thoroughly on this which seems generally like it would be a good improvement.

On Tue, 9 Apr 2024, at 9:52 AM, Ihor Radchenko wrote:
> 2. Allow attaching auxiliary attributes to the on object level, as an
>    equivalent of affiliated keywords on element level
>
>    - For example, we should allow assigning height per-link without the
>      awkward kludge we have with special handling of
>     
>      #+attr_html: :height 300
>      [[file:image.png]] has a height of 300, but what if we want a
>      different height in [[file:another-image.png]]?
>
>      We can thus do
>     
>      #+attr_html: :height 300
>      [[file:image.png]] has a height of 300, but what if we want a
>      different height in @@[:html-height 300]{[[file:another-image.png]]}?
>
>      Note how @@{...} markup assigns attributes to objects inside - the
>      attributes should be somehow inherited.

This way of assigning a height to the image seems odd to me.  Mostly, the attributes specified by the inline block apply to the block, not the contents, so wouldn't this case be potentially surprising?

Both of these examples mean different things in HTML, and it seems like you might want to create either -- how would you control which was produced using the "@@[:html-height 300]{[[file:another-image.png]]}" syntax?

<span><img height="300"></span>

<span style="height: 300"><img></span>

Instead, I wonder if the problem is that the way of inserting an image using a link itself.  If you need more control, could there be a special "img" inline special block which can handle additional attributes?

For example: 

@img[:height 300]{image.png} has a height of 300, and we can also have images with different heights and attributes like @img[:height 400 :alt "An image"]{another-image.png}.

Or, if using the original syntax, perhaps the attribute should be explicitly :img-attr or :img-height to resolve the ambiguity about which element is being targetted?

Rick

Re: Attributes on images (was:: Experimental public branch for inline special blocks)

[Ihor Radchenko]

"Rick Lupton" <mail@ricklupton.name> writes:

>>      #+attr_html: :height 300
>>      [[file:image.png]] has a height of 300, but what if we want a
>>      different height in @@[:html-height 300]{[[file:another-image.png]]}?
>>
>>      Note how @@{...} markup assigns attributes to objects inside - the
>>      attributes should be somehow inherited.
>
> This way of assigning a height to the image seems odd to me.  Mostly, the attributes specified by the inline block apply to the block, not the contents, so wouldn't this case be potentially surprising?

We already have #+attr_html: :height 300 that applies to the whole
paragraph and it is not going anywhere. So, my idea is natural given the
existing convention.

And I explicitly suggested that attributes of anonymous inline blocks
@@[...]{...} will be inherited by all other markup. This is not just for
images, but in case if we want some extra configuration for other
traditional Org markup:
@@[:weight semi-bold]{All the *bold text here* will *be* semi-bold.}

Also, one may do something like

@@[:html-height 300]{This [[file:image.png]] and that
[[file:other-image.png]]}, but not third [[file:yet-another-image.png]].

> Both of these examples mean different things in HTML, and it seems like you might want to create either -- how would you control which was produced using the "@@[:html-height 300]{[[file:another-image.png]]}" syntax?
>
> <span><img height="300"></span>
>
> <span style="height: 300"><img></span>

Anonymous inline markup will not at all be exported by itself. Its
purpose is to provide attributes or serve as back escape sequence.

So, I envision your examples as

@span{@@[:html-height 300]{<file:image.png>}}

@span[:html-style height: 300]{<file:image.png>}

> Instead, I wonder if the problem is that the way of inserting an image using a link itself.  If you need more control, could there be a special "img" inline special block which can handle additional attributes?
>
> For example: 
>
> Or, if using the original syntax, perhaps the attribute should be explicitly :img-attr or :img-height to resolve the ambiguity about which element is being targetted?

I do not have much of an opinion about the attribute names. If we need
to make them unique, that's totally fine and does not affect the overall
syntax design. I used image height simply as an illustration of the idea
of attribute inheritance. The above example with attributes for *bold*
is illustrating the same idea.

> @img[:height 300]{image.png} has a height of 300, and we can also have images with different heights and attributes like @img[:height 400 :alt "An image"]{another-image.png}.

This is also an option, although it allows setting attributes only for a
single image. Maybe we can modify the anonymous markup to make its
attributes be inherited by a subset of the markup inside:

@@[:parent-of link :height 300]{Only [[file:link.png]] inherits :height
attribute, but not @bold{other markup}}

This way, we can have some interesting options for ad-hoc markup like

#+inline_attr:tall: :parent-of link, latex-fragment :height 1000

@tall{All the images and latex inside will be tall: <file:1.png>
<file:2.png> \(x^2\)}

Another aspect of your example is that you implicitly suggested an
alternative link markup, which raises a more general question - should
we allow making the inline markup an alias of an existing markup?

This may require two alternative approaches:

a. Special treatment of certain inline markup names, like

   @code{verbatim code}
   @verbatim{...}
   @bold{...}
   @italic{...}
   @underline{...}
   @strikethrough{...}
   @link[...]{path}{description}

   (we need such special treatment to make sure that, for example,
   @bold{...} in Org files can still be correctly exported by export
   backends not aware about the new inline markup)

b. In addition to :export_template idea I proposed that would define
   custom *per-backend* export rules, we will need some way to define
   ad-hoc markup in terms of the more traditional Org markup:

   @code{...} == ~code~
   @bold{...} == *bold*

   or even

   @alert{...} == @bold{@italic{...}}

I personally feel that b is more powerful, but it is getting so close to
the idea of {{{macros}}} that we may confuse users.

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

Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> Well, next week I will continue commenting. I will try to stay up to
> date with everything that is being discussed here. By the way, if
> someone wants to collaborate on the branch, I can add them as a
> contributor (I'm afraid it is necessary to have a GitLab account, if
> I'm not mistaken).

It has been quite a while since the last activity in this thread.
Juan, may I know if you had a chance to work on the branch?

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

Re: Experimental public branch for inline special blocks

[Juan Manuel Macías]

Ihor Radchenko writes:

> Juan Manuel Macías <maciaschain@posteo.net> writes:
>
>> Well, next week I will continue commenting. I will try to stay up to
>> date with everything that is being discussed here. By the way, if
>> someone wants to collaborate on the branch, I can add them as a
>> contributor (I'm afraid it is necessary to have a GitLab account, if
>> I'm not mistaken).
>
> It has been quite a while since the last activity in this thread.
> Juan, may I know if you had a chance to work on the branch?

Hi, Ihor,

Thanks for your reminder. I'm sorry for all this long time that I've
been inactive and unresponsive, but the last few months I have had a lot
of work, in addition to other personal circumstances that have kept me
busy. I haven't had time to follow the list or deal with the branch. I
had planned to respond to your comments now in the summer (and I will
probably do so in the next few days), but I am afraid that until
September I will not be able to participate actively or continuously on
the list.

Of course, if someone wants to actively collaborate in the development
of this branch, I have no problem. If necessary, I also have no
objection to moving the repository to another more ‘open’ place (in Gitlab
it is necessary to have an account to collaborate).

Best regards,

Juan Manuel 

-- 
Juan Manuel Macías -- Composición tipográfica, tratamiento de datos, diseño editorial y ortotipografía

Re: Experimental public branch for inline special blocks

[Ihor Radchenko]

Juan Manuel Macías <maciaschain@posteo.net> writes:

> ... until
> September I will not be able to participate actively or continuously on
> the list.

No problem.
I just wanted to make sure that this is not forgotten.

> Of course, if someone wants to actively collaborate in the development
> of this branch, I have no problem. If necessary, I also have no
> objection to moving the repository to another more ‘open’ place (in Gitlab
> it is necessary to have an account to collaborate).

+1

This is an important feature that should be added sooner or later to
address numerous edge cases in the Org markup.

On my side, it is not on the very top of the priorities, so I am happy
that Juan is working on it. If anyone else wants to help, it will be
very welcome as well.

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