A boolean attribute is a built-in attribute that acts like a toggle.
Its sole function is to turn on a feature or behavior.
== Constructing an attribute entry for a boolean attribute
== Boolean attribute entry syntax
A boolean attribute is set with an attribute entry in the header or body of a document.
Its value is always left blank because boolean attributes only accept an _empty string_ value, which Asciidoctor automatically assigns at processing time.
...
...
@@ -17,7 +17,7 @@ Its value is always left blank because boolean attributes only accept an _empty
After the closing colon, press kbd:[Enter].
The attribute is now set and its behavior will be applied to the document.
== Setting a boolean attribute
== Declare a boolean attribute
Let's use an attribute entry to turn on the built-in boolean attribute named `sectanchors`.
When `sectanchors` is set, it xref:sections:title-links.adoc#anchor[activates an anchor in front of a section title] when a cursor hovers over it.
...
...
@@ -28,29 +28,3 @@ When `sectanchors` is set, it xref:sections:title-links.adoc#anchor[activates an
:sectanchors: <.>
----
<.> The value of `sectanchors` is always left empty because it's a boolean attribute.
== Unsetting a boolean attribute
Boolean document attributes can be unset by adding a bang symbol (`!`) directly in front of or after the attribute's name in an attribute entry.
The attribute entry must be on its own line.
[source]
----
:!name-of-a-boolean-attribute:
----
Let's use an attribute entry to turn off the built-in boolean attribute named `sectids`.
Asciidoctor automatically sets `sectids` at processing time unless you unset it.
The `sectids` attribute xref:sections:ids.adoc[generates an ID for each section] from the section's title.
[source]
----
= Document Title
:!sectids: <.>
----
<.> On a new line, type a colon (`:`), directly followed by a bang symbol (`!`), the attribute's name, and then another colon (`:`).
After the closing colon, press kbd:[Enter].
The attribute is now unset and its behavior won't be applied to the document.
Once an attribute is unset, its behavior is deactivated.
When `sectids` is unset, Asciidoctor will not generate IDs from section titles at processing time.
Asciidoctor has numerous attributes reserved for special purposes.
*Built-in attributes* add, configure, and control common features in a document.
...
...
@@ -44,7 +44,7 @@ To override an attribute's default value, you have to explicitly assign a value
The value assigned to an attribute in the document header replaces the default value (assuming the attribute is not locked via the CLI or API).
//Change to override a default value with a user-defined value
=== Override a default asset directory value with a user-defined value
=== Override a default asset directory value
You can also use the built-in asset directory attributes to customize the base path to images (default: `_empty_`), icons (default: `./images/icons`), stylesheets (default: `./stylesheets`) and JavaScript files (default: `./javascripts`).
@@ -8,13 +9,14 @@ You'll likely use the value of a user-defined attribute entry or certain built-i
To reference and use the value of a document attribute, you enclose the attribute's name in curly brackets (`+{name-of-an-attribute}+`).
This inline element is called an *attribute reference*.
== Reference user-defined attributes
[#reference-custom]
== Reference custom attributes
Before you can reference an attribute in a document it must be declare using an attribute entry in the document header.
Let's reference the two user-defined attributes set and assigned values in <<ex-user-attrs>>.
Let's reference the two user-defined attributes set and assigned values in <<ex-set-custom>>.
.User-defined document attributes set in the document header
[source#ex-user-attrs]
.Custom attributes set in the document header
[source#ex-set-custom]
----
= Ops Manual
:disclaimer: Don't pet the wild Wolpertingers. We're not responsible for any loss \
...
...
@@ -25,7 +27,7 @@ of hair, chocolate, or purple socks.
Once you've set and assigned a value to the attribute, you can reference that attribute throughout your document.
In <<ex-reference>>, the attribute `url-repo` is referenced twice and `disclaimer` is referenced once.
.User-defined attribute referenced in the document body
.Custom attributes referenced in the document body
[source#ex-reference]
----
Asciidoctor is {url-repo}[open source]. <.>
...
...
@@ -35,7 +37,7 @@ If you're missing a lime colored sock, file a ticket in
the {url-repo}/issues[Asciidoctor issue tracker]. <.>
----
<.> Attribute references can be used in macros.
<.> Attribute references can be used in blocks, such as xref:blocks:admonition.adoc[admonitions], and inline.
<.> Attribute references can be used in blocks, such as xref:blocks:admonitions.adoc[admonitions], and inline.
Since there isn't a blank line between the `disclaimer` reference and the next sentence, the sentence will be directly appended to the end of the attribute's value when it's processed.
<.> The reference to the `url-repo-ex` attribute is inserted into a longer URL address and used in a xref:macros:url-macro.adoc[URL macro].
...
...
@@ -48,32 +50,21 @@ WARNING: {disclaimer}
If you're missing a lime colored sock, file a ticket in the {url-repo}/issues[Asciidoctor issue tracker].
====
////
To save even more typing, you can store the whole link in an attribute value.
[#reference-built-in]
== Reference an automatically declared attribute
.Link attribute entry
[source]
----
:link-fedpkg: https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]
----
Now you insert this link anywhere in the document using an attribute reference.
An automatically set document attribute is referenced the same way as an explicitly set document attribute.
For instance, Asciidoctor automatically sets all of the character replacement attributes.
That means that you can reference them throughout your document without having to create an attribute entry in its header.
.link-fedpkg attribute usage example
[source]
----
Did you know there's an {link-fedpkg}?
TIP: Wolpertingers don't like temperatures above 100{deg}C. <.>
Our servers don't like them either.
----
<.> Reference the character replacement attribute `deg` by enclosing its name in a set of curly brackets (`+{ }+`).
Note that the link substitution occurs _after_ the attribute reference is resolved.
This works thanks to the default order of substitutions on a paragraph.
If you want the URL macro to be resolved eagerly at the time the attribute is assigned, you need to enclose it in a pass macro.
.Link attribute entry resolved eagerly
[source]
----
:link-fedpkg: pass:m[https://apps.fedoraproject.org/packages/rubygem-asciidoctor[Asciidoctor package for Fedora]]
----
As you can see below, the attribute reference is replaced with the attribute's value when the document is processed.
Now you can use this link in a section title (where the order of substitutions is different).
////
TIP: Wolpertingers don't like temperatures above 100{deg}C.
Attributes set AsciiDoc apart from other lightweight markup languages.
Attributes activate behaviors, styles, and integrations, or hold replacement (variable) content.
There are three types of attributes: document, element, and environment.
There are two types of attributes: document attributes and element attributes.
Document attributes:: xref:document-attributes.adoc[Document attributes] apply built-in behavior and settings to a whole document, or in select cases, to regions of a document.
== Document attributes
xref:document-attributes.adoc[Document attributes] apply built-in behavior and settings to a whole document, or in select cases, to regions of a document.
They make user-defined information available for use throughout a whole document.
They're set and defined in a document's header using an attribute entry, but can also be used from the API or command line.
Element attributes:: xref:element-attributes.adoc[Element attributes] apply built-in and user-defined styles, metadata, and behavior to individual block and inline elements in a document.
== Element attributes
xref:element-attributes.adoc[Element attributes] apply built-in and user-defined styles, metadata, and behavior to individual block and inline elements in a document.
They're set and defined directly on the element they're modifying using an attribute list.
Element attributes are classified as positional or named.
////
Environment attributes:: Environment attributes provide information about the runtime environment, such as how, where, and when a document is being processed.
Environment attributes are built-in and Asciidoctor automatically sets and assigns them values when a document is loaded or converted.
Environment attributes can be referenced wherever attribute references are permitted, but it's recommended that you treat these attributes as read only.
