chore: update text on recompile-xml

author/topics/collections/configuration.adoc

@@ -172,9 +172,10 @@ This is automatically included when `sectionsplit` is set in the
 Metanorma file, to break a single document up into multiple HTML files.
 
 `recompile-xml`:::
-If a file is specified as being `*.adoc`, force it to be recompiled to XML, whether or not
-a corresponding XML file is already there. Used to refresh XML files; normally Asciidoc is
-not recompiled to XML to save time [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6].
+If a file is specified as being `*.adoc`, always recompile it into XML, whether
+or not a corresponding XML file is already there. This document attribute is
+only used to refresh XML files: by default, the last AsciiDoc-generated XML is
+cached for time savings [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6].
 
 `format`::
 Specifies the possible output formats for the collection as a list,
@@ -225,23 +226,30 @@ Gives the title of the current level of the manifest.
 manifest entries.
 +
 --
-* The documents are expected to be Metanorma Semantic XML documents;
-they can also be Metanorma Presentation XML documents, attachments (see below),
-YAML files, or AsciiDoc documents.
-
-* If a document is a AsciiDoc documents, it is compiled to a Metanorma
-Semantic XML document in preprocessing [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].
-The document is *not* recompiled to a Metanorma Semantic XML document if a corresponding XML 
-document has already been generated in the same directory [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6];
-this is because compiling documents is so time consuming. The document *is* recompiled to  a Metanorma Semantic XML document,
-even if a corresponding XML document has already been generated, provided the directive `recompile-xml`
-is present.
+* The documents are expected to be Metanorma Semantic XML documents (`*.xml`),
+Metanorma Presentation XML documents (`*.xml`), attachments (see below),
+YAML files (`*.yml`, `*.yaml`), or AsciiDoc source files (`*.adoc`).
+
+* If the file is in AsciiDoc format:
+
+** The file is compiled to a Metanorma Semantic XML document in
+preprocessing [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].
+
+** By default, for caching reasons, the document is *not* recompiled to a
+Metanorma Semantic XML document if a corresponding XML document has already been
+generated in the same directory [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6].
+
+** If the document attribute of `recompile-xml` is set, The document *is always*
+recompiled to a Metanorma Semantic XML document, even if a corresponding XML
+document has already been generated.
 
 * If a document is a YAML file, it is assumed to be a collection manifest itself,
 and its manifest is recursively read into the current manifest at that point of the
-entry [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0]. This allows manifests
-to include other manifests. If the YAML file is in a different directory, the file locations of any files
-it references are updated to be relative to the current manifest.
+entry [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.0].
+
+** This allows manifests to include other manifests. If the YAML file is in a
+different directory, the file locations of any files it references are updated
+to be relative to the current manifest.
 
 * A manifest can have both files and nested manifests as its
 children [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.7].