Commit f73ae0e6 authored by Sarah White's avatar Sarah White Committed by Dan Allen
Browse files

reorganize files and update nav and references

parent 82e83e6a
......@@ -8,17 +8,22 @@ asciidoc:
listing-caption: Example@
nav:
- modules/ROOT/nav.adoc
- modules/document/nav.adoc
- modules/blocks/nav-basics.adoc
- modules/attributes/nav.adoc
- modules/toc/nav.adoc
- modules/document/nav.adoc
- modules/sections/nav.adoc
- modules/blocks/nav-paragraph.adoc
- modules/text/nav.adoc
- modules/blocks/nav.adoc
- modules/macros/nav.adoc
- modules/lists/nav.adoc
- modules/tables/nav.adoc
- modules/macros/nav.adoc
- modules/blocks/nav-styles.adoc
- modules/verbatim/nav.adoc
- modules/tables/nav.adoc
- modules/stem/nav.adoc
- modules/attributes/nav-counter.adoc
- modules/blocks/nav-open.adoc
- modules/ROOT/nav-comment.adoc
- modules/toc/nav.adoc
- modules/directives/nav.adoc
- modules/subs/nav.adoc
- modules/pass/nav.adoc
......
......@@ -2,4 +2,4 @@
//* xref:get-started.adoc[]
** xref:doctypes.adoc[]
** xref:elements.adoc[]
** xref:attributes:get-started.adoc[]
** xref:attributes:types.adoc[]
.Document Attributes
* xref:document-attributes.adoc[]
* xref:attribute-entries.adoc[]
** xref:names-and-values.adoc[]
** xref:wrap-values.adoc[]
** xref:attribute-entry-substitutions.adoc[]
** xref:inline-attribute-entries.adoc[]
* Built-in Document Attributes
** xref:attribute-entries.adoc[]
*** xref:names-and-values.adoc[]
*** xref:wrap-values.adoc[]
*** xref:attribute-entry-substitutions.adoc[]
*** xref:inline-attribute-entries.adoc[]
** xref:built-in-attributes.adoc[]
** xref:reference-built-in-attributes.adoc[]
** xref:boolean-attributes.adoc[]
** xref:unset-built-in-attributes.adoc[]
* Custom Document Attributes
*** xref:boolean-attributes.adoc[]
** xref:custom-attributes.adoc[]
** xref:reference-custom-attributes.adoc[]
** xref:unresolved-references.adoc[]
// ** Unset Custom Attributes
* xref:assignment-precedence.adoc[]
//** Using Document Attributes from the CLI
//** Using Document Attributes from the API
.Element Attributes
** xref:unset-attributes.adoc[]
** xref:reference-attributes.adoc[]
*** xref:unresolved-references.adoc[]
** xref:assignment-precedence.adoc[]
* xref:element-attributes.adoc[]
** xref:positional-and-named-attributes.adoc[]
* xref:styles.adoc[]
* xref:ids.adoc[]
* xref:options.adoc[]
* xref:roles.adoc[]
** xref:ids.adoc[]
** xref:options.adoc[]
** xref:roles.adoc[]
= Manage Document Attribute Assignment Precedence
= Document Attribute Assignment Precedence
:navtitle: Attribute Assignment Precedence
== Default attribute value precedence
......
= Set and Unset a Boolean Attribute
= Set Boolean Attributes
// [#boolean-attribute]
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.
= Set and Define Built-In Document Attributes
// [#set-built-in]
= Declare Built-In Document Attributes
:navtitle: Declare Built-In Attributes
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`).
......
= Set and Define Custom Document Attributes
= Declare Custom Document Attributes
:navtitle: Declare Custom Attributes
// [#set-user-defined]
//If you're familiar with writing in XML, you might recognize a document attribute as a user-defined entity.
When you find yourself typing the same text repeatedly, or text that often needs to be updated, consider creating your own attribute.
[#user-defined-names]
......@@ -39,4 +39,4 @@ not responsible for any loss of hair, chocolate, or purple socks.
----
<.> Long values can be xref:wrap-values.adoc[soft wrapped] using a backslash (`\`).
Now, you can xref:reference-custom-attributes.adoc[reference these attributes] throughout the document.
Now, you can xref:reference-attributes.adoc#reference-custom[reference these attributes] throughout the document.
= Get Started with Document Attributes
= Document Attributes
You can think of a document attribute as a global variable for the AsciiDoc language.
......
= Get Started with Element Attributes
= Element Attributes
Element attributes are a powerful means of controlling the built-in settings of individual block and inline elements.
They're also used to apply user-defined behavior and supplemental information, such as citation information and fallback content, to certain elements.
......@@ -9,17 +9,14 @@ They're also used to apply user-defined behavior and supplemental information, s
Element attributes:
* Declare the style and ID of an element
* Declare the ID of an element
* Turn on or turn off an individual element's built-in features
* Configure the built-in features of an individual element
* Apply user-defined information, such as citation metadata, fallback text, link text, and target content, to an individual element
* Apply user-defined roles and behaviors to an individual element
They're set and defined directly on the element they're modifying using an attribute list.
Element attributes are classified as positional or named.
Attributes can be assigned to individual elements in a document using an attribute list.
They're set and defined directly on the element they're modifying using an attribute list.
[#attribute-list]
== Attribute lists
......
= The ID Attribute
= ID Attribute
The `id` attribute specifies a unique name for an element.
That name can only be used once in a document.
......
= The Options Attribute
= Options Attribute
The `options` attribute is a versatile xref:positional-and-named-attributes.adoc#named[named attribute] that can be assigned one or more values.
It can be defined globally as document attribute as well as a block attribute on an individual block.
......@@ -100,7 +100,8 @@ The following example show how to structure an attribute list when you have styl
property 1:: does stuff
property 2:: does different stuff
----
<.> xref:styles.adoc[Style is a positional attribute] and its value, in this case `horizontal`, is placed at the start of the attribute list.
<.> xref:blocks:styles.adoc[The block style attribute], declared as `horizontal` in this example, is a positional attribute.
A block style value is always placed at the start of the attribute list.
<.> `properties` is prefixed with a dot (`.`), signifying that it's assigned to the xref:roles.adoc[role attribute].
The role and options attributes can be set in either order, i.e., `[horizontal%step.properties]`.
<.> The percent sign (`%`) sets the `options` attribute and assigns the `step` value to it.
......
......@@ -638,14 +638,14 @@ See https://docs.mathjax.org/en/v2.5-latest/tex.html#automatic-equation-numberin
|*_empty_*
|{y}
|{y}
|xref:blocks:paragraph.adoc#hardbreaks[Preserve hard line breaks].
|xref:blocks:breaks.adoc#hardbreaks-attribute[Preserve hard line breaks].
|hide-uri-scheme
|{n}
|_empty_
|{y}
|
|xref:macros:links.adoc#hide-the-uri-scheme[Hides URI scheme] for raw links.
|xref:macros:links.adoc#hide-uri-scheme[Hides URI scheme] for raw links.
|media
|{n}
......@@ -792,7 +792,7 @@ Only used when `icons` attribute is set to `font`.
|*image*, font
|{y}
|{y}
|Chooses xref:macros:icons.adoc#enable-icons[images or font icons] instead of text for admonitions.
|Chooses xref:macros:icons.adoc#icons-attribute[images or font icons] instead of text for admonitions.
|iconsdir
|Only used when `icons` attribute is set to `image`
......
= Reference Custom Attributes
= Reference Document Attributes
:navtitle: Reference Attributes
:disclaimer: Don't pet the wild Wolpertingers. We're not responsible for any loss \
of hair, chocolate, or purple socks.
:url-repo: https://github.com/asciidoctor/asciidoctor
......@@ -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.
Our servers don't like them either.
= Reference Built-in Attributes
You'll likely use the values of certain built-in attributes in specific locations throughout a document.
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 an explicitly set and defined built-in document attribute
TBA
== Reference an automatically set and defined built-in document attribute
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.
[source]
----
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 (`+{ }+`).
As you can see below, the attribute reference is replaced with the attribute's value when the document is processed.
TIP: Wolpertingers don't like temperatures above 100{deg}C.
Our servers don't like them either.
= The Role Attribute
= Role Attribute
Blocks and many inline elements can be assigned one or more roles using the `role` attribute.
The `role` attribute is a xref:positional-and-named-attributes.adoc#named[named attribute].
......
= Get Started with Attributes
= AsciiDoc Attributes
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.
////
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment