Include Content Selected by Lines or Tags
The include directive supports selecting only portions of the document to include.
tags attribute (or
tag attribute for the singular case), you can select lines that fall between regions marked with user-defined tags.
lines attribute, you can include ranges of line numbers.
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. Using the semi-colon as the data separator eliminates this requirement.
Tags are useful when you want to display specific regions of content from an include file instead of all of its content.
You can select regions of content between tag/end directives using the
The example below shows how you tag a region of content inside a file containing multiple code examples.
if timings timings.record :read timings.start :parse end doc = (options[:parse] == false ? (Document.new lines, options) : (Document.new lines,options).parse) timings.record :parse if timings doc
|1||To indicate the start of a tagged region, insert a comment line in the code.|
|2||Assign a unique name to the
|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
|5||This is the start a tagged snippet named parse.|
|6||This is the end of the tagged snippet named parse.|
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
In the next example, the tagged region named parse is selected by the
[source,ruby] ---- include::core.rb[tag=parse] (1) ----
|1||In the directive’s brackets, set the
You can include multiple tags from the same file.
[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:
The following lines will be selected and displayed:
snippet a snippet b
Notice that none of the lines with the tag directives are displayed.
The previous section showed how to select tagged regions explicitly, but you can also use wildcards and exclusions:
Select all tagged regions.
Select all the lines in the document.
Negate the match.
The wildcards are applied first, then the exclusions are applied. Technically, the order you list them doesn’t matter, but it’s customary to list them in this order.
Here are some of the permutations that you can use:
Selects all the lines in the document; matches the default behavior of the include directive.
Selects all tagged regions in the document.
Selects all the lines outside and inside of tagged regions, but not the lines containing a tag directive.
Selects regions tagged foo, but excludes any nested regions tagged bar.
Selects all tagged regions, but excludes any regions tagged foo (nested or otherwise).
Selects all the lines of the document except for regions tagged foo.
Selects only the regions of the document outside of tags (i.e., non-tagged regions).
There are also some shorthands if only exclusions are specified:
**;!foo; an exclusion without an inclusion implicitly starts by selecting all the lines.
**;!*; only selects regions that are not tagged.
To include content by line range, assign a starting line number and an ending line number separated by a pair of dots (e.g.,
lines=1..5) to the
You can specify multiple ranges by separating each range by a comma. Since commas are normally used to separate individual attributes, you must quote the comma-separated list of ranges.
To avoid having to quote the list of ranges, you can instead separate them using semi-colons.
If you don’t know the number of lines in the document, or you don’t want to couple the range to the length of the file, you can refer to the last line of the document using the value -1.