Extend attribute definition pattern using the "%" and "." to create variations

I suggest to extend attribute definition pattern by using the unused symbols (probably roles and options) to create variations. For example:

:html: HTML

The original: {html} => HTML

:html%first: HyperText Markup Language ({HTML})

Internal option: In the first use {html} => HyperText Markup Language (HTML)

:html.expanded: HyperText Markup Language  

user-defined roles (inline): [.expanded]{HTML} =>HyperText Markup Language

:html.highlight: #{html}#

user-defined roles (block): in the block with [.highlight] role every {html} => HTML

:html%lang=fa: {html%first}اچ‌تی‌ام‌ال

When attribute lang=fa : {HTML}=> اچ‌تی‌ام‌ال

:html%lang=fa,first: اچ‌تی‌ام‌ال

When attribute lang=fa and it is used for the first time: {HTML}=> اچ‌تی‌ام‌ال HyperText Markup Language (HTML)

:html%sec0%sec1: image:something.png[]

all {html} in title level 0 and 1 are going to be substitute with the image

I think a bunch of predefined options that can be helpful are:

    first (first appearance)
    definition (for glossary)
    backend-html (when the backend is html or ... This of course by if-backend things but it might be a short-form
    sec0, ... (when in title of section x)

I think all your suggestions can be achieved in other ways quite conveniently.


First I would like to state that something like ":html%first:" would be dangerous to use:
let's assume you reference this with
"{html}"
in a pure glossary file (myGloss.adoc), which you include in another asciidoc file (general.adoc) with "include::".
If you include the glossary first, then you will see "HyerTest Markup Language", just as would wanted it.

general.adoc:
-> include::myGloss.adoc[]
-> include::someChapter.adoc[]

If you later decide the put the glossary at the end or another person decides that this glossary is helpful in his project, then maybe the {html%reference} will no be the first anymore, because it was already referenced by another file:

general.adoc:
-> include::someChapter.adoc[]
-> include....
-> include::myGloss.adoc[]

Then myGloss.adoc will not write what you would like to see. So, you should already know in your reference when you reference it for the first time, don't you?


Starting from this, I would rather suggest, that all your suggestions should be achieved by a naming convention in your project.
For instance, do it like:

:html: HTML
:html_expanded: HyperText Markup Language   
:html_first:    {html_expanded} ({html}) 

Do you know {html_first}?
The {html_expanded} has something to do with the Internet.

etc.


For the language-specific stuff I do not see the use-case. Would it not be better to have translations for every asciidoc-file rather than a language attribute? Meaning, you can also have a language-specific file for every language, where the attributes are defined language-specific, too.

Actually what I mean by html%first is the first appearance of {html} decided automatically by asciidoctor in any combination or compilation. The problem with fixed things, such as html_first, is that the same text can be used in different situations. For example, a paper might become a chapter in a book (very common in academic world). Then the first appearance of {html} changes. It cannot be the job of the author to determine/change the text to follow the new compilation. It cannot be the job of render/backend also, because it needs to know the expanded and the acronym forms of the same thing.

My suggestion here is not a very new thing in its essence. The "glossaries" package in Latex use the same concept (e.g. through "gls" macro)

About the language case, glossaries tend to be reusable piece of text, one might even borrow it from another person's/group's writings. The acronym form of something might be the same in many languages but the expanded form would be different. That is {HTML} might expand to "HyperText Markup Language" when language is English but expand to " Hypertext-Auszeichnungssprache" in German. With :html%lang=en: and :html%lang=de: we can have a common glossary file and use {HTML} in the text without the concern that how it expands. In some other languages it might be even common to expand something either only in the document language or both original and document languages.

Also, please not that we need only one entry in the final index page for {HTML} for all languages but not one for English, one for German, one for ...

Finally, I think the idea of context-sensitive variation bring much more flexibility and it is not restricted to these two cases.