From a1520ab5f6d26caee34d715f52bcf1afa699e4b9 Mon Sep 17 00:00:00 2001 From: Martin Mattel <github@diemattels.at> Date: Sun, 27 Oct 2024 13:09:08 +0100 Subject: [PATCH 1/3] Add another tagging example to highlight tag-filtering capabilities --- .../pages/include-tagged-regions.adoc | 52 +++++++++++++++++-- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/docs/modules/directives/pages/include-tagged-regions.adoc b/docs/modules/directives/pages/include-tagged-regions.adoc index 6bcca5c..202f528 100644 --- a/docs/modules/directives/pages/include-tagged-regions.adoc +++ b/docs/modules/directives/pages/include-tagged-regions.adoc @@ -61,8 +61,11 @@ include::example$include.adoc[tag=target-co-multiple] It is also possible to have fine-grained tagged regions inside larger tagged regions. -For example, if your include file has the following content: - +For example, if your include file has the following content:: ++ +-- +In this example, the tagged regions are defined via comments. + +Notice that by using comments, none of the lines with the tag directives are displayed. ---- // tag::snippets[] // tag::snippet-a[] @@ -88,8 +91,51 @@ snippet a snippet b .... +-- + +This example is another way defining tag directives:: ++ +-- +Note that in this examples, tag directives are not defined via comments. Includes must then use in case xref:tag-filtering[tag filtering]. + +---- +text a + +tag::snippet-b[] +snippet b +end::snippet-b[] + +text c +---- + +If you only include the tagged region of the file, use the following include directive, same as before: + +---- +\include::file-with-snippets.adoc[tag=snippet-b] +---- + +The following lines will be selected and displayed: + +.... +snippet b +.... + +But if you include the whole file including the tagged region, use the following include directive: + +---- +\include::file-with-snippets.adoc[tag=**] +---- + +The following lines will be selected and displayed: + +.... +text a +snippet b +text c +.... -Notice that none of the lines with the tag directives are displayed. +If not using tag filtering, tag directives like `tag::snippet-b[]` will be printed too. For details on tag filtering, see the next setion. +-- [#tag-filtering] == Tag filtering -- GitLab From ad23066214f7e043f867384891c243c4eb68e926 Mon Sep 17 00:00:00 2001 From: Martin Mattel <github@diemattels.at> Date: Thu, 31 Oct 2024 10:32:38 +0100 Subject: [PATCH 2/3] incorporate suggestions --- .../directives/pages/include-tagged-regions.adoc | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/modules/directives/pages/include-tagged-regions.adoc b/docs/modules/directives/pages/include-tagged-regions.adoc index 202f528..9c10d15 100644 --- a/docs/modules/directives/pages/include-tagged-regions.adoc +++ b/docs/modules/directives/pages/include-tagged-regions.adoc @@ -61,11 +61,10 @@ include::example$include.adoc[tag=target-co-multiple] It is also possible to have fine-grained tagged regions inside larger tagged regions. -For example, if your include file has the following content:: +Example 1, tagged regions are defined behind line comments:: + -- -In this example, the tagged regions are defined via comments. + -Notice that by using comments, none of the lines with the tag directives are displayed. +Notice that by using comments, none of the lines with tag directives are displayed in the rendered document. ---- // tag::snippets[] // tag::snippet-a[] @@ -78,7 +77,7 @@ snippet b // end::snippets[] ---- -And you include this file using the following include directive: +You include this file using the following include directive: ---- \include::file-with-snippets.adoc[tag=snippets] @@ -93,10 +92,10 @@ snippet b .... -- -This example is another way defining tag directives:: +Example 2, tags are not defined behind line comments:: + -- -Note that in this examples, tag directives are not defined via comments. Includes must then use in case xref:tag-filtering[tag filtering]. +Note that if tags are not defined behind line comments in AsciiDoc, you need to ensure xref:tag-filtering[tag filtering] is being used or else they will end up in the rendered document. ---- text a -- GitLab From 2f77fce91c23fff94f78eca5a7685154d2c9de9f Mon Sep 17 00:00:00 2001 From: Dan Allen <dan@opendevise.com> Date: Thu, 12 Dec 2024 14:30:22 -0700 Subject: [PATCH 3/3] revise tag filtering examples --- .../pages/include-tagged-regions.adoc | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/modules/directives/pages/include-tagged-regions.adoc b/docs/modules/directives/pages/include-tagged-regions.adoc index 9c10d15..3e5e49a 100644 --- a/docs/modules/directives/pages/include-tagged-regions.adoc +++ b/docs/modules/directives/pages/include-tagged-regions.adoc @@ -59,12 +59,11 @@ You can include multiple tags from the same file. include::example$include.adoc[tag=target-co-multiple] .... -It is also possible to have fine-grained tagged regions inside larger tagged regions. +It's also possible to have fine-grained tagged regions inside larger tagged regions. + +In the next example, tagged regions are defined behind line comments. +By putting each tag behind a line comment, regardless of how the content is included, you don't have to worry about those lines appearing in the rendered document. -Example 1, tagged regions are defined behind line comments:: -+ --- -Notice that by using comments, none of the lines with tag directives are displayed in the rendered document. ---- // tag::snippets[] // tag::snippet-a[] @@ -77,7 +76,7 @@ snippet b // end::snippets[] ---- -You include this file using the following include directive: +Let's assume you include this file using the following include directive: ---- \include::file-with-snippets.adoc[tag=snippets] @@ -90,12 +89,15 @@ snippet a snippet b .... --- -Example 2, tags are not defined behind line comments:: -+ --- -Note that if tags are not defined behind line comments in AsciiDoc, you need to ensure xref:tag-filtering[tag filtering] is being used or else they will end up in the rendered document. +You could also include the whole file without worry that the tags will be rendered: + +---- +\include::file-with-snippets.adoc[] +---- + +Now let's consider the case when the tags are not placed behind line comments. +In this case, you need to ensure that xref:tag-filtering[tag filtering] is being used or else those tags will be visible in the rendered document. ---- text a @@ -107,7 +109,7 @@ end::snippet-b[] text c ---- -If you only include the tagged region of the file, use the following include directive, same as before: +If you only want to include a specific tagged region of the file, use the following include directive: ---- \include::file-with-snippets.adoc[tag=snippet-b] @@ -119,7 +121,7 @@ The following lines will be selected and displayed: snippet b .... -But if you include the whole file including the tagged region, use the following include directive: +If you want to include the whole file, but also filter out any include tags, use the following include directive: ---- \include::file-with-snippets.adoc[tag=**] @@ -133,8 +135,8 @@ snippet b text c .... -If not using tag filtering, tag directives like `tag::snippet-b[]` will be printed too. For details on tag filtering, see the next setion. --- +If you did not specify g filtering, tag directives that aren't behind a line comment (e.g., `tag::snippet-b[]`) will also be printed too. +Tag filtering is explaied in more detail in the next section. [#tag-filtering] == Tag filtering -- GitLab