intrinsic-attributes-reference.adoc 5.02 KB
Newer Older
1
= Intrinsic Attributes Reference
2
3
:url-epoch: https://reproducible-builds.org/specs/source-date-epoch

4
5
6
7
The AsciiDoc processor automatically assigns values to various document attributes whenever a document is loaded or converted.
These _intrinsic 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 some information about the user's environment (e.g., `user-home`).
Like all document attributes, the value of an intrinsic attributes can be accessed using an attribute reference.
Many of these attributes are intended to be read only.
8
9

// tag::table[]
10
[#env-attributes-table%autowidth,cols="~m,~,~m"]
11
12
13
|===
|Attribute |Description |Example Value

14
15
16
17
18
19
20
//|asciidoctor
//|Set if the current processor is Asciidoctor.
//|{asciidoctor}
//
//|asciidoctor-version
//|Asciidoctor version.
//|{asciidoctor-version}
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

|backend
|The backend used to select and activate the converter that creates the output file.
Usually named according to the output format (e.g., `html5`)
|html5

|basebackend
|The generic backend on which the backend is based.
Typically the backend value minus any 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`).
|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.
Empty if the safe mode is SERVER or SECURE (to conceal the file's location).
|/home/user/docs

|docfile
|Full path of the source document.
Truncated to the basename if the safe mode is SERVER or SECURE (to conceal the file's location).
|/home/user/docs/userguide.adoc

|docfilesuffix
|File extension of the source document, including the leading period.
|.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, inline, or manpage).
|article

|docyear
|Year that the document was last modified.^[<<note_docdatetime,1>>,<<note_sourcedateepoch,2>>]^
|{docyear}

|embedded
72
|Set if content is being converted to an embedded document (i.e., body of document only).
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|

|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>>]^
|{localyear}

|outdir
|Full path of the output directory.
(Cannot be referenced in the content.
Only available to the API once the document is converted).
|/home/user/docs/dist

|outfile
|Full path of the output file.
(Cannot be referenced in the content.
Only available to the API once the document is converted).
|/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
|Full path of the home directory for the current user.
144
Masked as `.` if the safe mode is SERVER or SECURE.
145
146
147
148
149
150
151
152
153
154
155
156
|/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 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.
// end::table[]