diff --git a/contributing_to_docs/doc_guidelines.adoc b/contributing_to_docs/doc_guidelines.adoc index 6ee790a358..5ae97383ec 100644 --- a/contributing_to_docs/doc_guidelines.adoc +++ b/contributing_to_docs/doc_guidelines.adoc @@ -419,56 +419,6 @@ 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::[] and end::[]) 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