Commit 6461f831 authored by Dan Allen's avatar Dan Allen
Browse files

resolves #26 fold intrinsic attributes reference into document attributes reference (PR #27)

parent dfa31406
...@@ -1101,7 +1101,6 @@ To learn more about the available attributes and substitution groups see: ...@@ -1101,7 +1101,6 @@ To learn more about the available attributes and substitution groups see:
* xref:attributes:document-attributes-reference.adoc[] * xref:attributes:document-attributes-reference.adoc[]
* xref:attributes:character-replacement-reference.adoc[] * xref:attributes:character-replacement-reference.adoc[]
* xref:attributes:intrinsic-attributes-reference.adoc[]
* xref:subs:apply-subs-to-blocks.adoc#subs-groups[Substitution Groups] * xref:subs:apply-subs-to-blocks.adoc#subs-groups[Substitution Groups]
.Counter attributes .Counter attributes
......
* Reference * Reference
** xref:ROOT:syntax-quick-reference.adoc[] ** xref:ROOT:syntax-quick-reference.adoc[]
** xref:intrinsic-attributes-reference.adoc[]
** xref:document-attributes-reference.adoc[] ** xref:document-attributes-reference.adoc[]
** xref:character-replacement-reference.adoc[] ** xref:character-replacement-reference.adoc[]
** xref:ROOT:glossary.adoc[] ** xref:ROOT:glossary.adoc[]
...@@ -3,6 +3,7 @@ ...@@ -3,6 +3,7 @@
:y: Yes :y: Yes
:n: No :n: No
:endash: – :endash: –
:url-epoch: https://reproducible-builds.org/specs/source-date-epoch/
Document attributes are used either to configure behavior in the processor or to relay information about the document and its environment. Document attributes are used either to configure behavior in the processor or to relay information about the document and its environment.
This page catalogs all the built-in (i.e., reserved) document attributes in AsciiDoc. This page catalogs all the built-in (i.e., reserved) document attributes in AsciiDoc.
...@@ -23,10 +24,10 @@ Numeric values and values shown in _italic_ are instructional and indicate a val ...@@ -23,10 +24,10 @@ Numeric values and values shown in _italic_ are instructional and indicate a val
The attribute is simply turned on by being set. The attribute is simply turned on by being set.
* _empty_[=`effective`] -- In some cases, an empty value is interpreted by the processor as one of the allowable non-empty values. * _empty_[=`effective`] -- In some cases, an empty value is interpreted by the processor as one of the allowable non-empty values.
This effective value is prefixed with an equals sign and enclosed in square brackets (e.g., [=`auto`]). This effective value is prefixed with an equals sign and enclosed in square brackets (e.g., [=`auto`]).
The effective value will not be visible to an attribute reference. An attribute reference will resolve to an empty value rather than the effective value.
* (`implied`) -- Built-in attributes that are not set may have an implied value. * (`implied`) -- Built-in attributes that are not set may have an implied value.
The implied value is enclosed in parentheses (e.g., (`attributes`)). The implied value is enclosed in parentheses (e.g., (`attributes`)).
An implied value cannot be resolved using an attribute reference. An implied value can't be resolved using an attribute reference.
+ +
If the attribute doesn't accept _any_ or _empty_, than you must only assign one of the allowable values or specified value type. If the attribute doesn't accept _any_ or _empty_, than you must only assign one of the allowable values or specified value type.
...@@ -36,6 +37,229 @@ Otherwise, the assignment won't have any effect on the document. ...@@ -36,6 +37,229 @@ 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. 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). However, changing an attribute only affects behavior for content that follows the assignment (in document order).
== Intrinsic attributes
Intrinsic attributes are set automatically by the processor.
These attributes provide information about the document being processed (e.g., `docfile`), the security mode under which the processor is running (e.g., `safe-mode-name`), and information about the user's environment (e.g., `user-home`).
Many of these attributes are read only, which means they can't be modified (with some exceptions).
Attributes which are not are marked as modifiable.
Attributes marked as both modifiable and API/CLI Only can only be set from the API or CLI.
All other attributes marked as modifiable must be set by the end of the header (i.e., Header Only).
[cols="30m,20,^10,^10,30"]
|===
.>|Name .>|Allowable Values .>|Modifiable .>|API/CLI Only .>|Notes
|backend
|_any_ +
_ex._ html5
|{y}
|{n}
|The backend used to select and activate the converter that creates the output file.
Usually named according to the output format (e.g., `html5`)
|basebackend
|_any_ +
_ex._ html
|{n}
|n/a
|The generic backend on which the backend is based.
Typically derived from the backend value minus trailing numbers (e.g., the basebackend for `docbook5` is `docbook`).
May also indicate the internal backend employed by the converter (e.g., the basebackend for `pdf` is `html`).
|docdate
|_date (ISO)_ +
_ex._ 2019-01-04
|{y}
|{n}
|Last modified date of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|docdatetime
|_datetime (ISO)_ +
_ex._ 2019-01-04 19:26:06 UTC
|{y}
|{n}
|Last modified date and time of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|docdir
|_directory path_ +
_ex._ /home/user/docs
|If input is a string
|{y}
|Full path of the directory that contains the source document.
Empty if the safe mode is SERVER or SECURE (to conceal the file's location).
|docfile
|_file path_ +
_ex._ /home/user/docs/userguide.adoc
|If input is a string
|{y}
|Full path of the source document.
Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file's location).
|docfilesuffix
|_file extension_ +
_ex._ .adoc
|If input is a string
|{y}
|File extension of the source document, including the leading period.
|docname
|_file stem basename_ +
_ex._ userguide
|If input is a string
|{y}
|Root name of the source document (no leading path or file extension).
|doctime
|_time (ISO)_ +
_ex._ 19:26:06 UTC
|{y}
|{n}
|Last modified time of the source document.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|docyear
|_integer_ +
_ex._ {docyear}
|{y}
|{n}
|Year that the document was last modified.^[<<note-docdatetime,1>>,<<note-sourcedateepoch,2>>]^
|embedded
|_empty_
|{n}
|n/a
|Only set if content is being converted to an embedded document (i.e., body of document only).
|filetype
|_any_ +
_ex._ html
|If input is a string
|{y}
|File extension of the output file name (without leading period).
|htmlsyntax
|`html` +
`xml`
|{n}
|n/a
|Syntax used when generating the HTML output.
Controlled by and derived from the backend name (html=html or xhtml=html).
|localdate
|_date (ISO)_ +
_ex._ 2019-02-17
|{y}
|{n}
|Date when the document was converted.^[<<note-sourcedateepoch,2>>]^
|localdatetime
|_datetime (ISO)_ +
_ex._ 2019-02-17 19:31:05 UTC
|{y}
|{n}
|Date and time when the document was converted.^[<<note-sourcedateepoch,2>>]^
|localtime
|_time (ISO)_ +
_ex._ 19:31:05 UTC
|{y}
|{n}
|Time when the document was converted.^[<<note-sourcedateepoch,2>>]^
|localyear
|_integer_ +
_ex._ {localyear}
|{y}
|{n}
|Year when the document was converted.^[<<note-sourcedateepoch,2>>]^
|outdir
|_directory path_ +
_ex._ /home/user/docs/dist
|{n}
|n/a
|Full path of the output directory.
(Cannot be referenced in the content.
Only available to the API once the document is converted).
|outfile
|_file path_ +
_ex._ /home/user/docs/dist/userguide.html
|{n}
|n/a
|Full path of the output file.
(Cannot be referenced in the content.
Only available to the API once the document is converted).
|outfilesuffix
|_file extension_ +
_ex._ .html
|{y}
|{n}
|File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.).
|safe-mode-level
|`0` +
`1` +
`10` +
`20`
|{n}
|n/a
|Numeric value of the safe mode setting.
(0=UNSAFE, 1=SAFE, 10=SERVER, 20=SECURE).
|safe-mode-name
|`UNSAFE` +
`SAFE` +
`SERVER` +
`SECURE`
|{n}
|n/a
|Textual value of the safe mode setting.
|safe-mode-unsafe
|_empty_
|{n}
|n/a
|Set if the safe mode is UNSAFE.
|safe-mode-safe
|_empty_
|{n}
|n/a
|Set if the safe mode is SAFE.
|safe-mode-server
|_empty_
|{n}
|n/a
|Set if the safe mode is SERVER.
|safe-mode-secure
|_empty_
|{n}
|n/a
|Set if the safe mode is SECURE.
|user-home
|_directory path_ +
_ex._ /home/user
|{n}
|n/a
|Full path of the home directory for the current user.
Masked as `.` if the safe mode is SERVER or SECURE.
|===
[[note-docdatetime]]^[1]^ Only reflects the last modified time of the source document file.
It does not consider the last modified time of files which are included.
[[note-sourcedateepoch]]^[2]^ If the SOURCE_DATE_EPOCH environment variable is set, the value assigned to this attribute is built from a UTC date object that corresponds to the timestamp (as an integer) stored in that environment variable.
This override offers one way to make the conversion reproducible.
See the {url-epoch}[source date epoch specification] for more information about the SOURCE_DATE_EPOCH environment variable.
Otherwise, the date is expressed in the local time zone, which is reported as a time zone offset (e.g., `-0600`) or UTC if the time zone offset is 0).
To force the use of UTC, set the `TZ=UTC` environment variable when invoking Asciidoctor.
== Compliance attributes == Compliance attributes
[cols="30m,20,^10,^10,30"] [cols="30m,20,^10,^10,30"]
...@@ -105,7 +329,7 @@ Useful for storing the output in a source code control system as it prevents spu ...@@ -105,7 +329,7 @@ Useful for storing the output in a source code control system as it prevents spu
(`@`) (`@`)
|{n} |{n}
|{n} |{n}
|Sets the seed value for the appendix number sequence.^[<<fn-number,1>>]^ |Sets the seed value for the appendix number sequence.^[<<note-number,1>>]^
|appendix-refsig |appendix-refsig
|_any_ + |_any_ +
...@@ -123,10 +347,10 @@ Useful for storing the output in a source code control system as it prevents spu ...@@ -123,10 +347,10 @@ Useful for storing the output in a source code control system as it prevents spu
|chapter-number |chapter-number
|_number_ + |_number_ +
(0) (`0`)
|{n} |{n}
|{n} |{n}
|Sets the seed value for the chapter number sequence.^[<<fn-number,1>>]^ |Sets the seed value for the chapter number sequence.^[<<note-number,1>>]^
_Book doctype only_. _Book doctype only_.
|chapter-refsig |chapter-refsig
...@@ -153,10 +377,10 @@ _Book doctype only_. ...@@ -153,10 +377,10 @@ _Book doctype only_.
|example-number |example-number
|_number_ + |_number_ +
(0) (`0`)
|{n} |{n}
|{n} |{n}
|Sets the seed value for the example number sequence.^[<<fn-number,1>>]^ |Sets the seed value for the example number sequence.^[<<note-number,1>>]^
|figure-caption |figure-caption
|_any_ + |_any_ +
...@@ -167,10 +391,10 @@ _Book doctype only_. ...@@ -167,10 +391,10 @@ _Book doctype only_.
|figure-number |figure-number
|_number_ + |_number_ +
(0) (`0`)
|{n} |{n}
|{n} |{n}
|Sets the seed value for the figure number sequence.^[<<fn-number,1>>]^ |Sets the seed value for the figure number sequence.^[<<note-number,1>>]^
|important-caption |important-caption
|_any_ + |_any_ +
...@@ -201,10 +425,10 @@ _Book doctype only_. ...@@ -201,10 +425,10 @@ _Book doctype only_.
|listing-number |listing-number
|_number_ + |_number_ +
(0) (`0`)
|{n} |{n}
|{n} |{n}
|Sets the seed value for the listing number sequence.^[<<fn-number,1>>]^ |Sets the seed value for the listing number sequence.^[<<note-number,1>>]^
|manname-title |manname-title
|_any_ + |_any_ +
...@@ -263,10 +487,10 @@ _Book doctype only_. ...@@ -263,10 +487,10 @@ _Book doctype only_.
|table-number |table-number
|_number_ + |_number_ +
(0) (`0`)
|{n} |{n}
|{n} |{n}
|Sets the seed value for the table number sequence.^[<<fn-number,1>>]^ |Sets the seed value for the table number sequence.^[<<note-number,1>>]^
|tip-caption |tip-caption
|_any_ + |_any_ +
...@@ -451,7 +675,7 @@ See xref:sections:id-prefix-and-separator.adoc#separator[Change the ID word sepa ...@@ -451,7 +675,7 @@ See xref:sections:id-prefix-and-separator.adoc#separator[Change the ID word sepa
|{startsb}+-{endsb}0{endash}5 |{startsb}+-{endsb}0{endash}5
|{n} |{n}
|{n} |{n}
|Increases or decreases level of headings in include files. |Increases or decreases level of headings below assignment.
A leading + or - makes the value relative. A leading + or - makes the value relative.
//<<include-partitioning>> //<<include-partitioning>>
...@@ -459,7 +683,8 @@ A leading + or - makes the value relative. ...@@ -459,7 +683,8 @@ A leading + or - makes the value relative.
|_empty_ |_empty_
|{n} |{n}
|{n} |{n}
|See xref:sections:part-numbers-and-labels.adoc#partnums[Part numbers]. |Enables numbering of parts.
See xref:sections:part-numbers-and-labels.adoc#partnums[Number book parts].
_Book doctype only_. _Book doctype only_.
|sectanchors |sectanchors
...@@ -490,7 +715,7 @@ See xref:sections:ids.adoc#disable[Disable ID generation]. ...@@ -490,7 +715,7 @@ See xref:sections:ids.adoc#disable[Disable ID generation].
|sectnumlevels |sectnumlevels
|0{endash}5 + |0{endash}5 +
(3) (`3`)
|{n} |{n}
|{n} |{n}
|xref:sections:numbers.adoc#numlevels[Controls depth of section numbering]. |xref:sections:numbers.adoc#numlevels[Controls depth of section numbering].
...@@ -514,7 +739,7 @@ See xref:sections:ids.adoc#disable[Disable ID generation]. ...@@ -514,7 +739,7 @@ See xref:sections:ids.adoc#disable[Disable ID generation].
|toclevels |toclevels
|1{endash}5 + |1{endash}5 +
(2) (`2`)
|{n} |{n}
|{y} |{y}
|xref:toc:section-depth.adoc[Maximum section level to display]. |xref:toc:section-depth.adoc[Maximum section level to display].
...@@ -568,11 +793,11 @@ See xref:sections:ids.adoc#disable[Disable ID generation]. ...@@ -568,11 +793,11 @@ See xref:sections:ids.adoc#disable[Disable ID generation].
//<<naming-docinfo-files>> //<<naming-docinfo-files>>
|docinfodir |docinfodir
|_directory_ + |_directory path_
(base directory)
|{n} |{n}
|{y} |{y}
|Location of docinfo files. |Location of docinfo files.
Defaults to directory of source file if not specified.
//<<locating-docinfo-files>> //<<locating-docinfo-files>>
|docinfosubs |docinfosubs
...@@ -655,7 +880,8 @@ _PDF converter only_. ...@@ -655,7 +880,8 @@ _PDF converter only_.
Mutually exclusive with the `showtitle` attribute. Mutually exclusive with the `showtitle` attribute.
|outfilesuffix |outfilesuffix
|*_file extension_* |*_file extension_* +
_ex._ .html
|{y} |{y}
|{y} |{y}
|File extension of output file, including dot (`.`), such as `.html`. |File extension of output file, including dot (`.`), such as `.html`.
...@@ -663,7 +889,7 @@ Mutually exclusive with the `showtitle` attribute. ...@@ -663,7 +889,7 @@ Mutually exclusive with the `showtitle` attribute.
|pagewidth |pagewidth
|_integer_ + |_integer_ +
(425) (`425`)
|{n} |{n}
|{y} |{y}
|Page width used to calculate the absolute width of tables in the DocBook output. |Page width used to calculate the absolute width of tables in the DocBook output.
...@@ -678,7 +904,8 @@ _path segment_ ...@@ -678,7 +904,8 @@ _path segment_
|relfilesuffix |relfilesuffix
|*_file extension_* + |*_file extension_* +
_path segment_ _path segment_ +
_ex._ .html
|{y} |{y}
|{n} |{n}
|The path suffix (e.g., file extension) to add to relative xrefs. |The path suffix (e.g., file extension) to add to relative xrefs.
...@@ -718,7 +945,7 @@ Mutually exclusive with the `notitle` attribute. ...@@ -718,7 +945,7 @@ Mutually exclusive with the `notitle` attribute.
|*_empty_* |*_empty_*
|{y} |{y}
|{y} |{y}
|Control whether webfonts are loaded, and which ones, when using the default stylesheet. |Control whether webfonts are loaded when using the default stylesheet.
When set to empty, uses the default font collection from Google Fonts. When set to empty, uses the default font collection from Google Fonts.
A non-empty value replaces the `family` query string parameter in the Google Fonts URL. A non-empty value replaces the `family` query string parameter in the Google Fonts URL.
//<<applying-a-theme>> and {url-org}/asciidoctor.org/issues/410[issue #410^] //<<applying-a-theme>> and {url-org}/asciidoctor.org/issues/410[issue #410^]
...@@ -772,12 +999,13 @@ Only relevant used when value of `icons` attribute is `font`. ...@@ -772,12 +999,13 @@ Only relevant used when value of `icons` attribute is `font`.
Any other value is assumed to be an icontype and sets the value to empty (image-based icons). Any other value is assumed to be an icontype and sets the value to empty (image-based icons).
|iconsdir |iconsdir
|_directory_ + |_directory path_ +
_url_ _url_ +
_ex._ ./images/icons
|{y} |{y}
|{n} |{n}
|Location of non-font-based image icons. |Location of non-font-based image icons.
Points to the _icons_ folder under `imagesdir` by default. Defaults to the _icons_ folder under `imagesdir` if `imagesdir` is specified and `iconsdir` is not specified.
|icontype |icontype
|`jpg` + |`jpg` +
...@@ -790,9 +1018,9 @@ Points to the _icons_ folder under `imagesdir` by default. ...@@ -790,9 +1018,9 @@ Points to the _icons_ folder under `imagesdir` by default.
Only relevant when using image-based icons. Only relevant when using image-based icons.
|imagesdir |imagesdir
|_directory_ + |*_empty_* +
_url_ + _directory path_ +
*_empty_* _url_
|{y} |{y}
|{n} |{n}
|Location of image files. |Location of image files.
...@@ -825,7 +1053,7 @@ _url_ + ...@@ -825,7 +1053,7 @@ _url_ +
|Tells processor not to load CodeRay. |Tells processor not to load CodeRay.
|highlightjsdir |highlightjsdir
|_directory_ + |_directory path_ +
_url_ + _url_ +
(default CDN URL) (default CDN URL)
|{n} |{n}
...@@ -840,7 +1068,7 @@ _url_ + ...@@ -840,7 +1068,7 @@ _url_ +
|Name of theme used by highlight.js. |Name of theme used by highlight.js.
|prettifydir |prettifydir
|_directory_ + |_directory path_ +
_url_ + _url_ +
(default CDN URL) (default CDN URL)
|{n} |{n}
...@@ -905,7 +1133,7 @@ Any other value is permitted, but must be supported by a custom syntax highlight ...@@ -905,7 +1133,7 @@ Any other value is permitted, but must be supported by a custom syntax highlight
//<<normalize-block-indentation>> //<<normalize-block-indentation>>
|source-language |source-language
|_Source code language name_ |_source code language name_
|{n} |{n}
|{n} |{n}
|xref:verbatim:source-highlighter.adoc[Default language for source code blocks]. |xref:verbatim:source-highlighter.adoc[Default language for source code blocks].
...@@ -926,7 +1154,7 @@ Any other value is permitted, but must be supported by a custom syntax highlight ...@@ -926,7 +1154,7 @@ Any other value is permitted, but must be supported by a custom syntax highlight
|copycss |copycss
|*_empty_* + |*_empty_* +
_path_ _file path_
|{y} |{y}
|{y} |{y}
|Copy CSS files to output. |Copy CSS files to output.
...@@ -957,9 +1185,9 @@ Can't be unset in SECURE mode. ...@@ -957,9 +1185,9 @@ Can't be unset in SECURE mode.
Use CSS stylesheet instead.* Use CSS stylesheet instead.*
|stylesdir |stylesdir
|`*.*` + |_directory path_ +
_directory_ + _url_ +
_url_ `*.*`
|{y} |{y}
|{y} |{y}
|Location of CSS stylesheets. |Location of CSS stylesheets.
...@@ -1059,7 +1287,7 @@ Since these attributes deal with security, they can only be set from the API or ...@@ -1059,7 +1287,7 @@ Since these attributes deal with security, they can only be set from the API or