Include Content by Tagged Regions

The include directive enables you to select portions of a file to include instead of including the whole file. Use the lines attribute to include individual lines or a range of lines (by line number). Use the tags attribute (or tag attribute for the singular case) to select lines that fall between regions marked with user-defined tags.

When including multiple line ranges or multiple tags, each entry in the list must be separated by either a comma or a semi-colon. If commas are used, the entire value must be enclosed in quotes. You can eliminate this requirement by using the semi-colon as the data separator instead.

Tagging regions

Tags are useful when you want to identify specific regions of a file to include. You can then select the lines between the boundaries of the include tag/end directives to include using the tags attribute.

Including by tag includes all regions marked with that tag. This makes it possible to include a group of lines from different regions of the document using a single tag.

If the target file has tagged lines, and you just want to ignore those lines, use the tags attribute to filter them out. See Tag filtering for details.

The example below shows how you tag a region of content inside a file containing multiple code examples.

Example 1. Tagged code snippets in a file named core.rb
# tag::timings[] (1) (2)
if timings
  timings.record :read
  timings.start :parse
end
# end::timings[] (3) (4)
# tag::parse[] (5)
doc = (options[:parse] == false ? (Document.new lines, options) :
    (Document.new lines,options).parse)
timings.record :parse if timings
doc
# end::parse[] (6)
1 To indicate the start of a tagged region, insert a comment line in the code.
2 Assign a name to the tag directive. In this example, the tag is named timings.
3 Insert another comment line where you want the tagged region to end.
4 Assign the name of the region you want to terminate to the end directive.
5 This is the start of a tagged snippet named parse.
6 This is the end of the tagged snippet named parse.
The tag::[] and end::[] directives should be placed after a line comment as defined by the language of the source file. The directives must also appear at the end of the line. In the previous example, we choose to prefix the lines with a hash (#) because that’s the start of a line comment in Ruby.
For languages that only have circumfix comments, such as XML, you can enclose the tag and end directives in the respective circumfix comment markers. For example, in XML files, you can use <!-- tag::name[] --> and <!-- end::name[] --> (the spaces around the tag are required).

In the next example, the tagged region named parse is selected by the include directive.

Example 2. Selecting the parse code snippet from a document
[source,ruby]
----
include::core.rb[tag=parse] (1)
----
1 In the directive’s brackets, set the tag attribute and assign it the unique name of the code snippet you tagged in your code file.

You can include multiple tags from the same file.

Example 3. Selecting the timings and the parse code snippets from a document
[source,ruby]
----
include::core.rb[tags=timings;parse]
----

It is also possible to have fine-grained tagged regions inside larger tagged regions.

For example, if your include file has the following content:

// tag::snippets[]
// tag::snippet-a[]
snippet a
// end::snippet-a[]

// tag::snippet-b[]
snippet b
// end::snippet-b[]
// end::snippets[]

And you include this file using the following include directive:

include::file-with-snippets.adoc[tag=snippets]

The following lines will be selected and displayed:

snippet a

snippet b

Notice that none of the lines with the tag directives are displayed.

Tag filtering

The previous section showed how to select tagged regions explicitly, but you can also use wildcards and exclusions. These expressions give you the ability to include or exclude tags in bulk. When tag filtering is used, lines containing a tag directive are always dropped. So even if you’re not including content by tags, you can specify the double wildcard (**) to filter out all lines that contain a tag directive.

The modifiers you can use for filtering are as follows:

*

Select all tagged regions. May only be specified once, whether it’s negated or not.

!

Negate the match. May be applied to the single wildcard or a specific tag name.

**

Select all the lines in the document except for lines that contain a tag directive. Use this symbol if you want to include a file that has tag/end directives, but you want to ignore all those lines. May only be specified once. Cannot be negated.

Wildcards are always applied first, then the inclusions and exclusions are applied. Technically, the wildcards can be placed anywhere in the list, but it’s customary to put them first. Each of the wildcards can only be used once.

Here are some of the permutations you can use:

*

Selects all tagged regions in the document.

**

Selects all the lines in the document except for lines containing a tag directive.

**;*

Selects all the lines in the document except for lines containing a tag directive.

foo;!bar

Only selects regions tagged foo, but excludes any nested regions tagged bar.

*;!foo

Selects all tagged regions, but excludes any regions tagged foo (nested or otherwise).

**;!foo

Selects all the lines in the document except for lines containing a tag directive and regions tagged foo.

**;!*

Selects only the regions in the document outside of tags (i.e., non-tagged regions).

**;!*;foo

Selects the regions in the document outside of tags (i.e., non-tagged regions) and inside regions tagged foo.

There are also some shorthands if only exclusions are specified:

!foo

Equivalent to **;!foo; an exclusion without an inclusion implicitly starts by selecting all the lines that do not contain a tag directive.

!*

Equivalent to **;!*; only selects regions that are not tagged.