Support for tagging (special) blocks

Support for tagging (special) blocks

[Sébastien Miquel]

Hi,

I've been using tags on special blocks, src blocks and other, for two
purposes:

  1. to control which blocks get exported, using the `#+exclude_tags`
     property.
  2. to fine tune the export, according to tags, of special blocks such as
     #+BEGIN_exercice                                            :hard:
     …
     #+END_exercice

Does anyone think this is useful and might warrant adding support for ?

-- 
Sébastien Miquel

Re: Support for tagging (special) blocks

[Kaushal Modi]

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

On Wed, Aug 31, 2022 at 4:19 PM Sébastien Miquel <sebastien.miquel@posteo.eu>
wrote:

> Hi,
>
> I've been using tags on special blocks, src blocks and other, for two
> purposes:
>
>   1. to control which blocks get exported, using the `#+exclude_tags`
>      property.
>   2. to fine tune the export, according to tags, of special blocks such as
>      #+BEGIN_exercice                                            :hard:
>      …
>      #+END_exercice
>
> Does anyone think this is useful and might warrant adding support for ?
>

I think that using the #+header: property for something like this might be
more canonical.
https://orgmode.org/manual/Using-Header-Arguments.html

Example:

=====
#+header: :tags noexport
#+begin_foo
..
#+end_foo
=====

or

=====
#+header: :tags hard
#+begin_foo
..
#+end_foo
=====

It's also relatively easy to parse these headers:

=====
(org-babel-parse-header-arguments (car (org-element-property :header
special-block)))
=====

[-- Attachment #2: Type: text/html, Size: 1757 bytes --]

Re: Support for tagging (special) blocks

[Fraga, Eric]

On Wednesday, 31 Aug 2022 at 20:10, Sébastien Miquel wrote:
> Does anyone think this is useful and might warrant adding support for ?

I would welcome something like this, whether as tags on the src block
line or as a special header, as Kaushal suggests.

-- 
: Eric S Fraga, with org release_9.5.4-756-g090dac in Emacs 29.0.50

Re: Support for tagging (special) blocks

[Payas Relekar]

Kaushal Modi <kaushal.modi@gmail.com> writes:

Tags are bit more generic though, and allow searching across not just
code blocks, but TODOs as well.

Thanks,
Payas

> On Wed, Aug 31, 2022 at 4:19 PM Sébastien Miquel <sebastien.miquel@posteo.eu>
> wrote:
>
>> Hi,
>>
>> I've been using tags on special blocks, src blocks and other, for two
>> purposes:
>>
>>   1. to control which blocks get exported, using the `#+exclude_tags`
>>      property.
>>   2. to fine tune the export, according to tags, of special blocks such as
>>      #+BEGIN_exercice                                            :hard:
>>      …
>>      #+END_exercice
>>
>> Does anyone think this is useful and might warrant adding support for ?
>>
>
> I think that using the #+header: property for something like this might be
> more canonical.
> https://orgmode.org/manual/Using-Header-Arguments.html
>
> Example:
>
> =====
>
> #+header: :tags noexport
> #+begin_foo
>
> ..
> #+end_foo
> =====
>
> or
>
> =====
>
> #+header: :tags hard
> #+begin_foo
>
> ..
> #+end_foo
> =====
>
> It's also relatively easy to parse these headers:
>
> =====
> (org-babel-parse-header-arguments (car (org-element-property :header
> special-block)))
> =====
>

--

Re: Support for tagging (special) blocks

[Ihor Radchenko]

Payas Relekar <relekarpayas@gmail.com> writes:

> Tags are bit more generic though, and allow searching across not just
> code blocks, but TODOs as well.

They do not. Tags are only considered inside headlines. Trying to allow
tags outside headlines will require major changes across the whole Org
codebase and will still make things incompatible with third party
packages, like org-ql. Not to mention the whole new concept for block
syntax.

If one wants to add "tags" or other keywords associated with blocks or
other Org elements, the right tool to use is affiliated keywords. But
note that Org search infrastructure is tailored towards searching
headlines.

-- 
Ihor Radchenko,
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: Support for tagging (special) blocks

[Sébastien Miquel]

Hi,

Ihor Radchenko writes:
 > They do not. Tags are only considered inside headlines. Trying to allow
 > tags outside headlines will require major changes across the whole Org
 > codebase and will still make things incompatible with third party
 > packages, like org-ql. Not to mention the whole new concept for block
 > syntax.

Tags on block do not need to have the same support as headlines tags.
I'm not suggesting they should interact with the agenda or whatnot.
Support could be behind a user option, and consist only of say easy
tag edition, and `#+exclude_tags:` support. With that scope, the
implementation should be fairly simple. As for third party packages,
it is up to them whether to extend their features to tagged blocks ;
in some case it might not make sense.

 > If one wants to add "tags" or other keywords associated with blocks or
 > other Org elements, the right tool to use is affiliated keywords. But
 > note that Org search infrastructure is tailored towards searching
 > headlines.

Two inconvenients with using affiliated keywords.
  1. There would be no uniform treatment with headline tags. In my use,
     I have the same tags on headline and blocks, and I filter the
     export according to them with #+exclude_tags.
  2. They waste too much space. Say I have some 20 short exercices
     (represented by special blocks). Since I dot not display the
     #+end_ line, each of them takes 2 or 3 lines in my screen. If I
     want to tag those using affiliated keywords that makes for a 50%
     or 33% size increase, with very poor readability.

On a slightly related note, I find it quite unfortunate that one
presently cannot make use of the #+begin_ line of special blocks to
set some kind of optional title instead of using #+name or
#+attr_latex. That's a lot of wasted real estate.


-- 
Sébastien Miquel

Re: Support for tagging (special) blocks

[Ihor Radchenko]

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

> Ihor Radchenko writes:
>  > They do not. Tags are only considered inside headlines. Trying to allow
>  > tags outside headlines will require major changes across the whole Org
>  > codebase and will still make things incompatible with third party
>  > packages, like org-ql. Not to mention the whole new concept for block
>  > syntax.
>
> Tags on block do not need to have the same support as headlines tags.
> I'm not suggesting they should interact with the agenda or whatnot.
> Support could be behind a user option, and consist only of say easy
> tag edition, and `#+exclude_tags:` support. With that scope, the
> implementation should be fairly simple. As for third party packages,
> it is up to them whether to extend their features to tagged blocks ;
> in some case it might not make sense.

We already have ":exports none" header argument.

>  > If one wants to add "tags" or other keywords associated with blocks or
>  > other Org elements, the right tool to use is affiliated keywords. But
>  > note that Org search infrastructure is tailored towards searching
>  > headlines.
>
> Two inconvenients with using affiliated keywords.
>   1. There would be no uniform treatment with headline tags. In my use,
>      I have the same tags on headline and blocks, and I filter the
>      export according to them with #+exclude_tags.

Affiliated keywords are indeed not uniform with headlines. But they are
uniform with everything else. Paragraphs can have affiliated keywords.
Or other blocks. Or lists. Or tables...

>   2. They waste too much space. Say I have some 20 short exercices
>      (represented by special blocks). Since I dot not display the
>      #+end_ line, each of them takes 2 or 3 lines in my screen. If I
>      want to tag those using affiliated keywords that makes for a 50%
>      or 33% size increase, with very poor readability.

> On a slightly related note, I find it quite unfortunate that one
> presently cannot make use of the #+begin_ line of special blocks to
> set some kind of optional title instead of using #+name or
> #+attr_latex. That's a lot of wasted real estate.

Yes, but we do not want to overcomplicate Org syntax. Affiliated
keywords are universal across multiple element types. Adding a
specialized syntax for src blocks will make things complex technically
and create duplicate code.

We can alter the fontification to compact the screen space though. Will
it suffice?

-- 
Ihor Radchenko,
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: Support for tagging (special) blocks

[Sébastien Miquel]

Ihor Radchenko writes:
 > Sébastien Miquel <sebastien.miquel@posteo.eu> writes:
 >
 >> Ihor Radchenko writes:
 >>   > They do not. Tags are only considered inside headlines. Trying 
to allow
 >>   > tags outside headlines will require major changes across the 
whole Org
 >>   > codebase and will still make things incompatible with third party
 >>   > packages, like org-ql. Not to mention the whole new concept for 
block
 >>   > syntax.
 >>
 >> Tags on block do not need to have the same support as headlines tags.
 >> I'm not suggesting they should interact with the agenda or whatnot.
 >> Support could be behind a user option, and consist only of say easy
 >> tag edition, and `#+exclude_tags:` support. With that scope, the
 >> implementation should be fairly simple. As for third party packages,
 >> it is up to them whether to extend their features to tagged blocks ;
 >> in some case it might not make sense.
 >
 > We already have ":exports none" header argument.

For src block yes, but not for special blocks.

To explain where I'm coming from : I write mathematical content
categorized using special blocks, such as theorems, exercices, proofs,
personnal notes, etc. Then from a single org file, I export several
pdf files, filtering the content according to the types and tags of
special blocks : for example, to exclude some proofs, or exercices
that are too hard.

 >
 >>   > If one wants to add "tags" or other keywords associated with 
blocks or
 >>   > other Org elements, the right tool to use is affiliated 
keywords. But
 >>   > note that Org search infrastructure is tailored towards searching
 >>   > headlines.
 >>
 >> Two inconvenients with using affiliated keywords.
 >>    1. There would be no uniform treatment with headline tags. In my use,
 >>       I have the same tags on headline and blocks, and I filter the
 >>       export according to them with #+exclude_tags.
 >
 > Affiliated keywords are indeed not uniform with headlines. But they are
 > uniform with everything else. Paragraphs can have affiliated keywords.
 > Or other blocks. Or lists. Or tables...

That's indeed a good point. In fact, I had been wondering recently how
I could tag a single list item, but I guess affiliated keywords still
can't do that.

 >
 >>    2. They waste too much space. Say I have some 20 short exercices
 >>       (represented by special blocks). Since I dot not display the
 >>       #+end_ line, each of them takes 2 or 3 lines in my screen. If I
 >>       want to tag those using affiliated keywords that makes for a 50%
 >>       or 33% size increase, with very poor readability.
 >
 >> On a slightly related note, I find it quite unfortunate that one
 >> presently cannot make use of the #+begin_ line of special blocks to
 >> set some kind of optional title instead of using #+name or
 >> #+attr_latex. That's a lot of wasted real estate.
 >
 > Yes, but we do not want to overcomplicate Org syntax. Affiliated
 > keywords are universal across multiple element types. Adding a
 > specialized syntax for src blocks will make things complex technically
 > and create duplicate code.
 >
 > We can alter the fontification to compact the screen space though. Will
 > it suffice?
 >

I don't see any possible compactification that doesn't hinder
readability. From my perspective, it is important that the type of the
special block, its title, and its tags are readable.

One thing that org can do in that regard is hide the #+end_ line. For
special blocks, a requirement is that the org-block face should apply
to them too, to see where the block ends.


-- 
Sébastien Miquel

Re: Support for tagging (special) blocks

[Ihor Radchenko]

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

>  > We already have ":exports none" header argument.
>
> For src block yes, but not for special blocks.
>
> To explain where I'm coming from : I write mathematical content
> categorized using special blocks, such as theorems, exercices, proofs,
> personnal notes, etc. Then from a single org file, I export several
> pdf files, filtering the content according to the types and tags of
> special blocks : for example, to exclude some proofs, or exercices
> that are too hard.

We may allow something like

#+attr_all: :exports no

in export.

>  > Affiliated keywords are indeed not uniform with headlines. But they are
>  > uniform with everything else. Paragraphs can have affiliated keywords.
>  > Or other blocks. Or lists. Or tables...
>
> That's indeed a good point. In fact, I had been wondering recently how
> I could tag a single list item, but I guess affiliated keywords still
> can't do that.

Affiliated keywords can be assigned to lists. Not single items though:

#+CAPTION: test1
- item 1
  #+CAPTION: test2
  - item 2
  #+CAPTION: test3
  - item 3

>  >> On a slightly related note, I find it quite unfortunate that one
>  >> presently cannot make use of the #+begin_ line of special blocks to
>  >> set some kind of optional title instead of using #+name or
>  >> #+attr_latex. That's a lot of wasted real estate.
>  >
>  > Yes, but we do not want to overcomplicate Org syntax. Affiliated
>  > keywords are universal across multiple element types. Adding a
>  > specialized syntax for src blocks will make things complex technically
>  > and create duplicate code.
>  >
>  > We can alter the fontification to compact the screen space though. Will
>  > it suffice?
>  >
>
> I don't see any possible compactification that doesn't hinder
> readability. From my perspective, it is important that the type of the
> special block, its title, and its tags are readable.

I feel that I either misunderstand you here or in the previous message.

-- 
Ihor Radchenko,
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: Support for tagging (special) blocks

[Sébastien Miquel]

Ihor Radchenko writes:
 >>   >> On a slightly related note, I find it quite unfortunate that one
 >>   >> presently cannot make use of the #+begin_ line of special blocks to
 >>   >> set some kind of optional title instead of using #+name or
 >>   >> #+attr_latex. That's a lot of wasted real estate.
 >>   >
 >>   > Yes, but we do not want to overcomplicate Org syntax. Affiliated
 >>   > keywords are universal across multiple element types. Adding a
 >>   > specialized syntax for src blocks will make things complex 
technically
 >>   > and create duplicate code.
 >>   >
 >>   > We can alter the fontification to compact the screen space 
though. Will
 >>   > it suffice?
 >>   >
 >>
 >> I don't see any possible compactification that doesn't hinder
 >> readability. From my perspective, it is important that the type of the
 >> special block, its title, and its tags are readable.
 > I feel that I either misunderstand you here or in the previous message.

To clarify, here are the two alternatives I have in mind.

#+tag: easy
#+attr_latex: A classic
#+begin_exercice
Find a necessary and sufficient condition on $N$ and $P$ for $P = NP$
to hold.
#+end_exercice

#+begin_exercice A classic                                      :easy:
Find a necessary and sufficient condition on $N$ and $P$ for $P = NP$
to hold.
#+end_exercice

In my first message, I argue that wasting two lines of my screen
hinders reading and navigating the whole org file.

I'm not sure what fontification trick you had in mind to compact the
space, but if you were thinking of making the meta lines smaller, by
say 50%, I argue in my second message that this hinders the
readability of this single exercice. The first three lines each
contain information that is important to me when I browse the file (as
opposed to information that's only relevant for org export).

The only line that contains no content information is the #+end_exercice
line, which is only here for the org parser.


-- 
Sébastien Miquel

Re: Support for tagging (special) blocks

[Ihor Radchenko]

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

> To clarify, here are the two alternatives I have in mind.
>
> #+tag: easy
> #+attr_latex: A classic
> #+begin_exercice
> Find a necessary and sufficient condition on $N$ and $P$ for $P = NP$
> to hold.
> #+end_exercice
>
> #+begin_exercice A classic                                      :easy:
> Find a necessary and sufficient condition on $N$ and $P$ for $P = NP$
> to hold.
> #+end_exercice
>
> In my first message, I argue that wasting two lines of my screen
> hinders reading and navigating the whole org file.
>
> I'm not sure what fontification trick you had in mind to compact the
> space, but if you were thinking of making the meta lines smaller, by
> say 50%, I argue in my second message that this hinders the
> readability of this single exercice. The first three lines each
> contain information that is important to me when I browse the file (as
> opposed to information that's only relevant for org export).

Thanks for the clarification!
I did not mean to reduce the font size in affiliated keywords.
I was referring to replacing the display of affiliated keywords:

#+name: A classic
#+tag: easy

will be displayed by Emacs as

#+... A classic :easy:

The underlying text will not be changed.
The hidden parts will be revealed upon cursor entering the affiliated
keywords.

-- 
Ihor Radchenko,
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: Support for tagging (special) blocks

[Sébastien Miquel]

Hi,

Ihor Radchenko writes:
> Thanks for the clarification!
> I did not mean to reduce the font size in affiliated keywords.
> I was referring to replacing the display of affiliated keywords:
>
> #+name: A classic
> #+tag: easy
>
> will be displayed by Emacs as
>
> #+... A classic :easy:
>
> The underlying text will not be changed.
> The hidden parts will be revealed upon cursor entering the affiliated
> keywords.

Perhaps something like
#+... name: A classic tag: easy
might be used for any kind of keyword. That'd be quite the trick.

It would certainly improve the situation when an element has several
keywords, but I'm not sure how common that is.

I'll look into implementing such #+name and #+tag keywords, when I
have the time.

On an unrelated note, how is your work on revamping org's
fontification going, if I may ask ? I had had a look at your repo, but
since adapting my configuration would have required some effort I did
not try it.

-- 
Sébastien Miquel

Re: Support for tagging (special) blocks

[Ihor Radchenko]

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

> Hi,
>
> Ihor Radchenko writes:
>> Thanks for the clarification!
>> I did not mean to reduce the font size in affiliated keywords.
>> I was referring to replacing the display of affiliated keywords:
>>
>> #+name: A classic
>> #+tag: easy
>>
>> will be displayed by Emacs as
>>
>> #+... A classic :easy:
>>
>> The underlying text will not be changed.
>> The hidden parts will be revealed upon cursor entering the affiliated
>> keywords.
>
> Perhaps something like
> #+... name: A classic tag: easy
> might be used for any kind of keyword. That'd be quite the trick.

> It would certainly improve the situation when an element has several
> keywords, but I'm not sure how common that is.
>
> I'll look into implementing such #+name and #+tag keywords, when I
> have the time.

Escaping might be an issue.
Another approach could be following out headline format
#+name: Title :tag1:tag2:

In any case, I am not too concerned about the semantics at this point.

In order to implement tag support in named blocks, you will need to add
it to many places in Org, like parser, export, babel, user commands,
etc. It is not trivial. And do not forget about backwards compatibility
and, for example, third-party export backends.

> On an unrelated note, how is your work on revamping org's
> fontification going, if I may ask ? I had had a look at your repo, but
> since adapting my configuration would have required some effort I did
> not try it.

The latest progress is a bit of discussion on parser-based font-lock
keywords in emacs-devel. See
https://yhetil.org/emacs-devel/87wn9srn9n.fsf@localhost/

The code status still requires some decisions to be made about code
design of the parser. In particular, the current (albeit working)
implementation will make it difficult to apply arbitrary fontification
order for parent/child elements. Like in
https://orgmode.org/list/m2mtdp2cwo.fsf@ntnu.no

And I need to write tests, add faces to all possible elements/objects,
and re-factor the code into shorter function.

I have not had much time to work in these lately because of the upcoming
Org release.

-- 
Ihor Radchenko,
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