You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
64 lines
2.5 KiB
64 lines
2.5 KiB
4 years ago
|
////
|
||
|
|
Included in:
|
||
|
|
|
||
|
|
- user-manual: Attributes: Setting attributes on an element
|
||
|
|
////
|
||
|
|
|
||
|
|
// tag::intro[]
|
||
|
|
An attribute list can apply to blocks, inline quotes text, and macros.
|
||
|
|
The attributes and their values contained in the list will take precedence over attribute entries.
|
||
|
|
|
||
|
|
.Anatomy of an attribute list
|
||
|
|
[positional_attribute1,positional_attribute2,name_attribute1="value"]
|
||
|
|
|
||
|
|
Attribute lists:
|
||
|
|
|
||
|
|
. apply to blocks as well as macros and inline quoted text
|
||
|
|
. can contain positional and named attributes
|
||
|
|
. take precedence over global attributes
|
||
|
|
// end::intro[]
|
||
|
|
|
||
|
|
==== Positional attribute
|
||
|
|
// tag::pos[]
|
||
|
|
Positional attributes are un-named values at the start of the attribute list.
|
||
|
|
The attribute that they are assigned to depends on the type of the element:
|
||
|
|
|
||
|
|
* `icon:` (1) size
|
||
|
|
* `image:` and `image::` (1) alt text, (2) width, (3) height
|
||
|
|
* Delimited blocks: (1) block name (aka style)
|
||
|
|
* Other inline quoted text: (1) role
|
||
|
|
|
||
|
|
For example, the following two image macros are equivalent.
|
||
|
|
|
||
|
|
[source,asciidoc]
|
||
|
|
----
|
||
|
|
image::sunset.jpg[Sunset,300,400]
|
||
|
|
|
||
|
|
image::sunset.jpg[alt=Sunset,width=300,height=400]
|
||
|
|
----
|
||
|
|
|
||
|
|
The second macro is just a duplicate of the first macro written out longhand.
|
||
|
|
// end::pos[]
|
||
|
|
|
||
|
|
==== Named attribute
|
||
|
|
// tag::name[]
|
||
|
|
A named attribute consists of a name and a value separated by an `=` character (e.g., `name=value`).
|
||
|
|
|
||
|
|
If the value contains a space, comma, or quote character, it must be enclosed in double or single quotes (e.g., `name="value with space"`).
|
||
|
|
In all other cases, the surrounding quotes are optional.
|
||
|
|
If present, the enclosing quotes are dropped from the parsed value.
|
||
|
|
|
||
|
|
To undefine a named attribute, set the value to `None` (case sensitive).
|
||
|
|
// end::name[]
|
||
|
|
|
||
|
|
==== Attribute List Substitutions
|
||
|
|
// tag::subs[]
|
||
|
|
Attribute references are expanded before the block attribute list is processed.
|
||
|
|
Therefore, it's not necessary to force substitutions to be applied if you simply want to use a document attribute reference in a block attribute.
|
||
|
|
|
||
|
|
If the attribute name (for a positional attribute) or value (for a named attribute) is enclosed in single quotes (e.g., `+title='Processed by https://asciidoctor.org[Asciidoctor]'+`), <<subs,normal substitutions>> are applied to the value at assignment time (with some exceptions).
|
||
|
|
No special processing is performed if the value is not enclosed in quotes or is enclosed in double quotes.
|
||
|
|
|
||
|
|
If the attribute value contains the same quote character being used to enclose the value, escape the quote character in the value by prefixing it with a backslash (e.g., `title="\"Dark Horse\" is a song by George Harrison"`).
|
||
|
|
// end::subs[]
|