Merge pull request #76375 from skrthomas/tagging-update

adding disclaimer to tagged region includes

Author: skrthomas

contributing_to_docs/doc_guidelines.adoc

@@ -419,16 +419,6 @@ include::modules/module-filename.adoc[leveloffset=+1] <1>
 ----
 <1> `[leveloffset=]` link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/#manipulate-heading-levels-with-leveloffset[is relative], and changes the header level of included content.
 
-You can use `tag` attributes to link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions[define regions of a file and include by tag instead of the whole file.] This enables you to make conditional modifications to existing modules instead of duplicating content. When creating a tag, use a tag name that makes it easy to understand where the content defined will be included.
-
-.Tagged module include syntax
-[source,text]
-====
-\include::modules/module-with-tags-filename.adoc[leveloffset=+1,tag=TagName]
-====
-
-You can filter out the regions defined by a `tag` attribute by using link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/#tag-filtering[expressions] in place of or in conjunction with the tag name. If you add tag defined conditional content to a module with no existing tags, you must update existing includes of the file you are changing to exclude your content.
-
 [IMPORTANT]
 ====
 Including link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-lines/[lines by content ranges] can lead to content errors when the included file is subsequently updated and is not permitted.
@@ -446,6 +436,56 @@ When using the "Prerequisites", "Next steps", or "Additional resources" headings
 Only use `.` formatting (`.Additional resources`) to follow a module in an assembly. Because you cannot use the xrefs in modules, this functions as a _trailing include_ at the assembly level, where the `.` formatting of the `include` statement indicates that the resource applies specifically to the module and not to the assembly.
 ====
 
+=== Including by tags
+You can use `tag` attributes to link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions[define regions of a file and include by tag instead of the whole file.] This enables you to make conditional modifications to existing modules instead of duplicating content. When creating a tag, use a tag name that makes it easy to understand where the content defined will be included.
+
+* In assembly files, use the `tags` (plural) attribute when there is more than one tag specified. Use the `tag` (singular) attribute when there is only one tag. For example:
++
+.Singular tagged module include syntax
+[source,text]
+====
+\include::modules/module-with-tag-filename.adoc[leveloffset=+1,tag=TagName]
+====
++
+.Plural tagged module include syntax
+[source,text]
+====
+\include::modules/module-with-tags-filename.adoc[leveloffset=+1,tags=TagName;Mode1;!Mode2]
+====
+
+* In the module files, use `//` before the tag directives in asciidoc text and a `#` before tag directives in YAML. For example:
++
+.Included file tag directives
+[source,text]
+----
+// tag::TagName[]
+== 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.
+
+In the included file, the tag directives (e.g., tag::<tag_name>[] and end::<tag_name>[]) must follow a word boundary and precede a space character or the end of line. The tag name must not be empty and must consist exclusively of non-space characters.
+
+.Example CR
+[source,yaml]
+--
+spec:
+# tag::Mode1[]
+    mode: openshift
+# end::Mode1[]
+# tag::Mode2[]
+    mode: openshift-network
+# end::Mode2[]
+--
+// end::TagName[]
+----
++
+[WARNING]
+====
+The use of a wildcard (`*`) is not fully supported by PV1. Verify that access.redhat.com builds and docs.openshift.com builds are including or excluding content as expected if you try to use them.
+====
+
+You can filter out the regions defined by a `tag` attribute by using link:https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/#tag-filtering[expressions] in place of or in conjunction with the tag name. If you add tag defined conditional content to a module with no existing tags, you must update existing includes of the file you are changing to exclude your content.
+
 == Writing concepts
 A _concept_ contains information to support the tasks that users want to do and
 must not include task information like commands or numbered steps. In most