ifdef-ifndef.adoc 3.48 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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
72
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
= ifdef and ifndef Directives

[#ifdef]
== ifdef directive

Content between the `ifdef` and `endif` directives gets included if the specified attribute is set:

.ifdef example
[source]
----
\ifdef::env-github[]
This content is for GitHub only.
\endif::[]
----

The syntax of the start directive is `ifdef::<attribute>[]`, where `<attribute>` is the name of an attribute.

Keep in mind that the content is not limited to a single line.
You can have any amount of content between the `ifdef` and `endif` directives.

If you have a large amount of content inside the `ifdef` directive, you may find it more readable to use the long-form version of the directive, in which the attribute (aka condition) is referenced again in the `endif` directive.

.ifdef long-form example
[source]
----
\ifdef::env-github[]
This content is for GitHub only.

So much content in this section, I'd get confused reading the source without the closing `ifdef` directive.

It isn't necessary for short blocks, but if you are conditionally including a section it may be something worth considering.

Other readers reviewing your docs source code may go cross-eyed when reading your source docs if you don't.
\endif::env-github[]
----

If you're only dealing with a single line of text, you can put the content directly inside the square brackets and drop the `endif` directive.

.ifdef single line example
[source]
----
\ifdef::revnumber[This document has a version number of {revnumber}.]
----

The single-line block above is equivalent to this formal `ifdef` directive:

[source]
----
\ifdef::revnumber[]
This document has a version number of {revnumber}.
\endif::[]
----

[#ifndef]
== ifndef directive

`ifndef` is the logical opposite of `ifdef`.
Content between `ifndef` and `endif` gets included only if the specified attribute is _not_ set:

.ifndef example
[source]
----
\ifndef::env-github[]
This content is not shown on GitHub.
\endif::[]
----

The syntax of the start directive is `ifndef::<attribute>[]`, where `<attribute>` is the name of an attribute.

The `ifndef` directive supports the same single-line and long-form variants as `ifdef`.

== Checking multiple attributes

Both the `ifdef` and `ifndef` directives accept multiple attribute names.
The combinator can be "`and`" or "`or`".

Any attribute (or)::
Multiple comma-separated (`,`) directive names evaluate to true, allowing the content to be included, if one or more of the directives is defined.
Otherwise the content is not included.
+
.Any attribute example
[source]
----
\ifdef::backend-html5,backend-docbook5[Only shown when converting to HTML5 or DocBook 5.]
----

All attributes (and)::
Multiple plus-separated (`+`) directive names evaluate to true, allowing the content to be included, if all of the directives are defined.
Otherwise the content is not included.
+
.All attributes example
[source]
----
\ifdef::env-github+backend-html5[Only shown when converting to HTML5 on GitHub.]
----

The `ifndef` directive negates the results of the expression.

////
Move this to changelog

102
WARNING: Starting in Asciidoctor 1.5.6, the operator logic in the `ifndef` directive changed to align with the behavior of AsciiDoc.py.
103
104
105
106
Specifically, when attributes are separated by commas, content is only included if none of the attributes are defined.
When attributes are separated by pluses, content is included if at least one of the attributes is undefined.
See https://github.com/asciidoctor/asciidoctor/issues/1983[issue #1983] to find the discussion about this behavior and the rationale for the change.
////