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.

157 lines
4.3 KiB

4 years ago
////
Included in:
- user-manual appendix B attribute calatog
////
[#env-attributes]
= Environment Attributes
Asciidoctor automatically assigns values to various document attributes whenever a document is loaded or converted.
These attributes, termed [.term]_environment attributes_, provide information about the runtime environment, such as how, where and when the document is being processed.
Like other document attributes, environment attributes can be referenced whereever attribute references are permitted.
It's recommended that you treat these attributes as read only.
[#env-attributes-table]
// tag::table[]
.Environment attributes
[cols="1m,2,1m"]
|===
|Attribute |Description |Example Value
|asciidoctor
|Set if the current processor is Asciidoctor.
|{asciidoctor}
|asciidoctor-version
|Asciidoctor version.
|{asciidoctor-version}
|backend
|Backend used to create the output file.
|html5
|basebackend
|The backend value minus any trailing numbers.
For example, if the backend is `docbook5`, the basebackend is `docbook`.
|html
|docdate
|Last modified date of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|2019-01-04
|docdatetime
|Last modified date and time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|2019-01-04 19:26:06 UTC
|docdir
|Full path of the directory that contains the source document.
|/home/user/docs
|docfile
|Full path of the source document.
|/home/user/docs/userguide.adoc
|docfilesuffix
|File extension of the source document, including the leading period.
_Introduced in 1.5.6._
|.adoc
|docname
|Root name of the source document (no leading path or file extension).
|userguide
|doctime
|Last modified time of the source document.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|19:26:06 UTC
|doctype
|Document type (article, book or manpage).
|article
|docyear
|Year that the document was last modified.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|2018
|embedded
|Set if content is being converted to an embeddable document (body only).
|
|filetype
|File extension of the output file name (without leading period).
|html
|htmlsyntax
|Syntax used when generating the HTML output (html or xhtml).
|html
|localdate
|Date when the document was converted.^[<<note_sourcedateepoch,2>>]^
|2019-02-17
|localdatetime
|Date and time when the document was converted.^[<<note_sourcedateepoch,2>>]^
|2019-02-17 19:31:05 UTC
|localtime
|Time when the document was converted.^[<<note_sourcedateepoch,2>>]^
|19:31:05 UTC
|localyear
|Year when the document was converted.^[<<note_sourcedateepoch,2>>]^
|2018
|outdir
|Full path of the output directory.
|/home/user/docs/dist
|outfile
|Full path of the output file.
|/home/user/docs/dist/userguide.html
|outfilesuffix
|File extension of the output file (starting with a period) as determined by the backend (`.html` for `html`, `.xml` for `docbook`, etc.).
(The value is not updated to match the file extension of the output file when one is specified explicitly).
_Safe to modify._
|.html
|safe-mode-level
|Numeric value of the safe mode setting.
(UNSAFE=0, SAFE=10, SERVER=10, SECURE=20).
|20
|safe-mode-name
|Textual value of the safe mode setting.
|SERVER
|safe-mode-unsafe
|Set if the safe mode is UNSAFE.
|
|safe-mode-safe
|Set if the safe mode is SAFE.
|
|safe-mode-server
|Set if the safe mode is SERVER.
|
|safe-mode-secure
|Set if the safe mode is SECURE.
|
|user-home
|Home directory of the current user.
Resolves to `.` if the safe mode is SERVER or greater.
|/home/user
|===
[[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 https://reproducible-builds.org/specs/source-date-epoch/ 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.
// end::table[]