Commit dfa31406 authored by Dan Allen's avatar Dan Allen
Browse files

resolves #24 rework reference table for built-in attributes (PR #25)

* rewrite intro
* fix incorrect values and descriptions
* consolidate Header Set and Body Set columns to Header Only
* resolves #1 indicate implied values separated from default values
* clarify difference between effective value and implied value
* update description of fields
* adjust column widths
* add several missing attributes
* move any above empty in legend for document attributes table
* remove outdated footnote and fix references to the remaining one
* rename Values column to Allowable Values
* rename Header Only column for security attributes to CLI/API only
* configure content in table header to align to bottom
parent ecb1db79
= Document Attributes Reference = Document Attributes Reference
// TODO use icons or emoji for y and n
:y: Yes :y: Yes
:n: No :n: No
:en: – :endash: –
//// Document attributes are used either to configure behavior in the processor or to relay information about the document and its environment.
Need to update the compatibility guide with: This page catalogs all the built-in (i.e., reserved) document attributes in AsciiDoc.
* numbered = sectnums Unless otherwise marked, these attributes can be modified (set or unset) from the API using the `:attributes` option, from the CLI using the `-a` option, or in the document (often in the document header) using an attribute entry.
* docinfo1 = docinfo
* docinfo2 = docinfo
* toc-class = use custom theme https://github.com/asciidoctor/asciidoctor.org/issues/379[issue #379]
* toc-placement = toc
* notitle = showtitle!
* encoding = ignored always UTF-8
////
Built-in document attributes can be set and unset using an attribute entry. Use the follow legend to understand the columns and values in the tables on this page.
Automatically Set:: The attribute is set automatically by Asciidoctor and assigned its default value at processing time if you don't set it explicitly in the API, command line, or document. [horizontal]
Automatically set attributes can be unset with the `!`. Set By Default:: The attribute is automatically set and assigned a default value by the AsciiDoc processor.
The default value is indicated in *bold* (e.g., `*skip*`).
Values:: Allowable Values:: Allowable values for the attribute.
Numeric values and values shown in _italic_ are instructional and indicate a value type (e.g., _any_, _empty_, _number_, 1{endash}5, etc.).
+ +
* _empty_ value: The _empty_ value indicates the attribute doesn't have an explicit value. * _any_ -- Any value is accepted.
* _empty_ -- Indicates the attribute doesn't require an explicit value.
The attribute is simply turned on by being set. The attribute is simply turned on by being set.
* *default* value: Attributes that have built-in values may have a default value which is indicated by the *bolded value*. * _empty_[=`effective`] -- In some cases, an empty value is interpreted by the processor as one of the allowable non-empty values.
If you set the attribute but leave the value empty, Asciidoctor will fall back to this default value at processing time. This effective value is prefixed with an equals sign and enclosed in square brackets (e.g., [=`auto`]).
* If the attribute doesn't accept an _empty_ value or have a *default* value, than you must explicitly assign the attribute an accepted built-in or user-defined value. The effective value will not be visible to an attribute reference.
* (`implied`) -- Built-in attributes that are not set may have an implied value.
The implied value is enclosed in parentheses (e.g., (`attributes`)).
An implied value cannot be resolved using an attribute reference.
Header Set:: The attribute can be set and assigned a value (or unset) in the document's header. +
In almost all cases, these attributes can also be set, defined, or unset in the API or command line. If the attribute doesn't accept _any_ or _empty_, than you must only assign one of the allowable values or specified value type.
If you set an attribute from the command line or API, it's defined for the whole document and can't be changed in the document header or body unless `@` is added to the end of the value.
See xref:assignment-precedence.adoc[] for more information.
The one exception to this rule is the `sectnums` attribute, which can always be changed.
Body Set:: The attribute can be set, assigned a value, or unset in the document's body (anywhere below the document header). Header Only:: The attribute must be set or unset by the end of the document header (i.e., set by the API, CLI, or in the document header).
When you set an attribute in the body, it's visible from the point it's set until it's unset (unless it's overridden by the xref:assignment-precedence.adoc[assignment precedence]). Otherwise, the assignment won't have any effect on the document.
If an attribute is not marked as _Header Only_, it can be set anywhere in the document, assuming the attribute is not locked by the API or CLI.
However, changing an attribute only affects behavior for content that follows the assignment (in document order).
== Compliance attributes == Compliance attributes
[%autowidth,cols="~m,^~,~,^~,^~,~"] [cols="30m,20,^10,^10,30"]
|=== |===
|Name |Automatically Set |Values |Header Set |Body Set |Notes .>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
|attribute-missing |attribute-missing
|{n} |`drop` +
|`*skip*` +
`drop` +
`drop-line` + `drop-line` +
`*skip*` +
`warn` `warn`
|{y} |{y}
|{y} |{n}
|Controls how xref:unresolved-references.adoc#missing[missing attribute references] are handled. |Controls how xref:unresolved-references.adoc#missing[missing attribute references] are handled.
|attribute-undefined |attribute-undefined
|{n} |`drop` +
|`*drop-line*` + `*drop-line*`
`drop`
|{y} |{y}
|{y} |{n}
|Controls how xref:unresolved-references.adoc#undefined[undefined attributes] are handled. |Controls how xref:unresolved-references.adoc#undefined[attribute unassignments] are handled.
|compat-mode |compat-mode
|_empty_
|{n} |{n}
e|empty |{n}
|{y} |Controls when the legacy parsing mode is used to parse the document.
|{y}
|Controls when the legacy parser is used to parse the document.
|experimental |experimental
|_empty_
|{n} |{n}
e|empty
|{y} |{y}
|{n} |Enables xref:macros:ui-macros.adoc[] and the xref:macros:keyboard-macro.adoc[].
|Enables xref:macros:ui-macros.adoc[] and xref:macros:keyboard-macro.adoc[].
|reproducible |reproducible
|_empty_
|{n} |{n}
e|empty
|{y} |{y}
|{n}
|Prevents last-updated date from being added to HTML footer or DocBook info element. |Prevents last-updated date from being added to HTML footer or DocBook info element.
Useful for storing the output in a source code control system as it prevents spurious changes every time you convert the document. Useful for storing the output in a source code control system as it prevents spurious changes every time you convert the document.
//Alternatively, you can use the SOURCE_DATE_EPOCH environment variable to fix the value. //Alternatively, you can use the SOURCE_DATE_EPOCH environment variable to fix the value.
|skip-front-matter
|_empty_
|{n}
|{y}
|Consume YAML-style frontmatter at top of document and store it in `front-matter` attribute.
//<<front-matter-added-for-static-site-generators>>
|=== |===
[#builtin-attributes-i18n] [#builtin-attributes-i18n]
== Internationalization and numbering == Localization and numbering attributes
[%autowidth,cols="~m,^~,~,^~,^~,~"] [cols="30m,20,^10,^10,30"]
|=== |===
|Name |Automatically Set |Values |Header Set |Body Set |Notes .>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
|appendix-caption |appendix-caption
|Only when section assigned `Appendix` style |_any_ +
|`*Appendix*` + `*Appendix*`
_user-defined_
|{y}
|{y} |{y}
|{n}
|Label added before an xref:sections:appendix.adoc[appendix title]. |Label added before an xref:sections:appendix.adoc[appendix title].
|appendix-number |appendix-number
|Only when section assigned `Appendix` style |_character_ +
|`*A*` + (`@`)
_letter or number_ |{n}
|{y} |{n}
|{y} |Sets the seed value for the appendix number sequence.^[<<fn-number,1>>]^
|Stores appendix letter or number sequence start.
|appendix-refsig |appendix-refsig
| |_any_ +
|`*Appendix*` + `*Appendix*`
_any_
|{y}
|{y} |{y}
|{n}
|Signifier added to Appendix title cross references. |Signifier added to Appendix title cross references.
|caution-caption |caution-caption
|_any_ +
`*Caution*`
|{y} |{y}
|`*Caution*` + |{n}
_any_
|{y}
|{y}
|Text used to label CAUTION admonitions when icons aren't enabled. |Text used to label CAUTION admonitions when icons aren't enabled.
|chapter-number |chapter-number
|Only when `doctype` is `book` |_number_ +
|`*1*` + (0)
_number_ |{n}
| |{n}
| |Sets the seed value for the chapter number sequence.^[<<fn-number,1>>]^
|Stores chapter number sequence start. _Book doctype only_.
|chapter-refsig |chapter-refsig
| |_any_ +
|`*Chapter*` + `*Chapter*`
_any_
|{y}
|{y} |{y}
|{n}
|Signifier added to Chapter titles in cross references. |Signifier added to Chapter titles in cross references.
_Book doctype only_.
|chapter-label |chapter-signifier
|Only when `doctype` is `book` |_any_
|`*Chapter*` + |{n}
_any_ |{n}
|{y}
|{y}
|xref:sections:chapters.adoc[Label added to level-1 section titles (chapters)]. |xref:sections:chapters.adoc[Label added to level-1 section titles (chapters)].
_PDF converter only_.
_Book doctype only_. _Book doctype only_.
|example-caption |example-caption
|_any_ +
`*Example*`
|{y} |{y}
|`*Example*` + |{n}
_any_
|{y}
|{y}
|Text used to label example blocks. |Text used to label example blocks.
|example-number |example-number
|{y} |_number_ +
|`*1*` + (0)
_number_ |{n}
| |{n}
| |Sets the seed value for the example number sequence.^[<<fn-number,1>>]^
|Stores example number sequence start.
|figure-caption |figure-caption
|_any_ +
`*Figure*`
|{y} |{y}
|`*Figure*` + |{n}
_any_
|{y}
|{y}
|Text used to label images and figures. |Text used to label images and figures.
|figure-number |figure-number
|{y} |_number_ +
|`*1*` + (0)
_number_ |{n}
| |{n}
| |Sets the seed value for the figure number sequence.^[<<fn-number,1>>]^
|Stores figure number sequence start.
|important-caption |important-caption
|_any_ +
`*Important*`
|{y} |{y}
|`*Important*` + |{n}
_any_
|{y}
|{y}
|Text used to label IMPORTANT admonitions when icons are not enabled. |Text used to label IMPORTANT admonitions when icons are not enabled.
|lang |lang
| |_valid XML language code_ +
|`*en*` + (`en`)
valid XML country code |{n}
|{y} |{y}
| |Language used on root element of the output document.
|Language used on root element of the output document
|last-update-label |last-update-label
| |_any_ +
|`*Last updated*`, _any_ `*Last updated*`
|{y}
|{y} |{y}
|
|Text used for “Last updated” label in footer. |Text used for “Last updated” label in footer.
|listing-caption |listing-caption
|{n}
|_any_ |_any_
|{y} |{n}
|{y} |{n}
|Text used to label listing blocks. |Text used to label listing blocks.
|listing-number |listing-number
| |_number_ +
|`*1*`, _number_ (0)
| |{n}
| |{n}
|Stores listing number sequence start. |Sets the seed value for the listing number sequence.^[<<fn-number,1>>]^
|manname-title |manname-title
| |_any_ +
|`*NAME*`, _any_ (`Name`)
|{n}
|{y} |{y}
|
|Label for program name section in the man page. |Label for program name section in the man page.
|nolang |nolang
|{n}
|_empty_ |_empty_
|{n}
|{y} |{y}
|
|Prevents `lang` attribute from being added to root element of the output document. |Prevents `lang` attribute from being added to root element of the output document.
|note-caption |note-caption
|_any_ +
`*Note*`
|{y} |{y}
|`*Note*`, _any_ |{n}
|{y}
|{y}
|Text used to label NOTE admonitions when icons aren't enabled. |Text used to label NOTE admonitions when icons aren't enabled.
|preface-title |part-refsig
|_any_ +
`*Part*`
|{y}
|{n} |{n}
|Signifier added to Part titles in cross references.
_Book doctype only_.
|part-signifier
|_any_ |_any_
|{y} |{n}
|{y} |{n}
|xref:sections:chapters.adoc[Label added to level-0 section titles (parts)].
_Book doctype only_.
|preface-title
|_any_
|{n}
|{n}
|Title text for an anonymous preface when `doctype` is `book`. |Title text for an anonymous preface when `doctype` is `book`.
|section-refsig |section-refsig
| |_any_ +
|`*Section*` + `*Section*`
_any_
|{y}
|{y} |{y}
|{n}
|Signifier added to title of numbered sections in cross reference text. |Signifier added to title of numbered sections in cross reference text.
|table-caption |table-caption
|_any_ +
`*Table*`
|{y} |{y}
|`*Table*` + |{n}
_any_
|{y}
|{y}
|Text of label prefixed to table titles. |Text of label prefixed to table titles.
|table-number |table-number
|{y} |_number_ +
|`*1*` + (0)
_number_ |{n}
|{y} |{n}
|{y} |Sets the seed value for the table number sequence.^[<<fn-number,1>>]^
|Stores table number sequence start.
|tip-caption |tip-caption
|_any_ +
`*Tip*`
|{y} |{y}
|`*Tip*` + |{n}
_any_
|{y}
|{y}
|Text used to label TIP admonitions when icons aren't enabled. |Text used to label TIP admonitions when icons aren't enabled.
|toc-title |toc-title
|Only if `toc` is set |_any_ +
|`*Table of Contents*` + `*Table of Contents*`
_any_ |{y}
|{y} |{y}
|
|xref:toc:title.adoc[Title for table of contents]. |xref:toc:title.adoc[Title for table of contents].
|untitled-label |untitled-label
| |_any_ +
|`*Untitled*` + `*Untitled*`
_any_ |{y}
|{y} |{y}
|
|Default document title if document doesn't have a document title. |Default document title if document doesn't have a document title.
|warning-caption |version-label
|_any_ +
`*Version*`
|{y} |{y}
|`*Warning*` +
_any_
|{y} |{y}
|See xref:document:version-label.adoc[].
|warning-caption
|_any_ +
`*Warning*`
|{y} |{y}
|{n}
|Text used to label TIP admonitions when icons aren't enabled. |Text used to label TIP admonitions when icons aren't enabled.
|=== |===
== Header and metadata attributes == Document metadata attributes
[cols="10m,^15,15,^5,^5,30"] [cols="30m,20,^10,^10,30"]
|=== |===
|Name |Automatically Set |Values |Header Set |Body Set |Notes .>|Name .>|Allowable Values .>|Set By Default .>|Header Only .>|Notes
|app-name |app-name
|{n}
|_any_ |_any_
|{n}
|{y} |{y}
|
|Adds `application-name` meta element for mobile devices inside HTML document head. |Adds `application-name` meta element for mobile devices inside HTML document head.
|author |author
|Only if present in author info line
|_any_ |_any_
|Extracted from author info line
|{y} |{y}
|{n}
|Can be set automatically via the author info line or explicitly. |Can be set automatically via the author info line or explicitly.
See xref:document:author-information.adoc[]. See xref:document:author-information.adoc[].
|authorinitials |authorinitials
|Only if present in author info line or `author`
|_any_ |_any_
|Extracted from `author` attribute
|{y} |{y}
|{n}
|Derived from the author attribute by default. |Derived from the author attribute by default.
See xref:document:author-information.adoc[]. See xref:document:author-information.adoc[].
|authors |authors
|Only if present in author info line
|_any_ |_any_
|Extracted from author info line
|{y} |{y}
|{n}
|Can be set automatically via the author info line or explicitly as a comma-separated value list. |Can be set automatically via the author info line or explicitly as a comma-separated value list.
See xref:document:author-information.adoc[]. See xref:document:author-information.adoc[].
|copyright