Merge pull request #8501 from albert-github/feature/bug_docu_improv

Some documentation improvements

3 files changed, 56 insertions, 13 deletions

diff --git a/doc/commands.doc b/doc/commands.doc
index eff2f42..e88c68a 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -2502,7 +2502,13 @@ Commands for displaying examples
   Files or directories that doxygen should look for can be specified using the
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
-  \sa section \ref cmdhtmlonly "\\htmlonly".
+  \sa section \ref cmdhtmlonly "\\htmlonly",
+  \ref cmdlatexinclude "\\latexinclude",
+  \ref cmdrtfinclude "\\rtfinclude",
+  \ref cmdmaninclude "\\maninclude",
+  \ref cmddocbookinclude "\\docbookinclude" and
+  \ref cmdxmlinclude "\\xmlinclude".
+
 <hr>
 
 \section cmdlatexinclude \\latexinclude <file-name>
@@ -2517,7 +2523,13 @@ Commands for displaying examples
   Files or directories that doxygen should look for can be specified using the
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
-  \sa section \ref cmdlatexonly "\\latexonly".
+  \sa section \ref cmdlatexonly "\\latexonly",
+  \ref cmdhtmlinclude "\\htmlinclude",
+  \ref cmdrtfinclude "\\rtfinclude",
+  \ref cmdmaninclude "\\maninclude",
+  \ref cmddocbookinclude "\\docbookinclude" and
+  \ref cmdxmlinclude "\\xmlinclude".
+
 <hr>
 
 \section cmdrtfinclude \\rtfinclude <file-name>
@@ -2532,7 +2544,13 @@ Commands for displaying examples
   Files or directories that doxygen should look for can be specified using the
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
-  \sa section \ref cmdrtfonly "\\rtfonly".
+  \sa section \ref cmdrtfonly "\\rtfonly",
+  \ref cmdhtmlinclude "\\htmlinclude",
+  \ref cmdlatexinclude "\\latexinclude",
+  \ref cmdmaninclude "\\maninclude",
+  \ref cmddocbookinclude "\\docbookinclude" and
+  \ref cmdxmlinclude "\\xmlinclude".
+
 <hr>
 
 \section cmdmaninclude \\maninclude <file-name>
@@ -2547,7 +2565,13 @@ Commands for displaying examples
   Files or directories that doxygen should look for can be specified using the
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
-  \sa section \ref cmdmanonly "\\manonly".
+  \sa section \ref cmdmanonly "\\manonly",
+  \ref cmdhtmlinclude "\\htmlinclude",
+  \ref cmdlatexinclude "\\latexinclude",
+  \ref cmdrtfinclude "\\rtfinclude",
+  \ref cmddocbookinclude "\\docbookinclude" and
+  \ref cmdxmlinclude "\\xmlinclude".
+
 <hr>
 
 \section cmddocbookinclude \\docbookinclude <file-name>
@@ -2562,7 +2586,13 @@ Commands for displaying examples
   Files or directories that doxygen should look for can be specified using the
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
-  \sa section \ref cmddocbookonly "\\docbookonly".
+  \sa section \ref cmddocbookonly "\\docbookonly",
+  \ref cmdhtmlinclude "\\htmlinclude",
+  \ref cmdlatexinclude "\\latexinclude",
+  \ref cmdrtfinclude "\\rtfinclude",
+  \ref cmdmaninclude "\\maninclude" and
+  \ref cmdxmlinclude "\\xmlinclude".
+
 <hr>
 
 \section cmdxmlinclude \\xmlinclude <file-name>
@@ -2576,7 +2606,13 @@ Commands for displaying examples
   Files or directories that doxygen should look for can be specified using the
   \ref cfg_example_path "EXAMPLE_PATH" tag of doxygen's configuration file.
 
-  \sa section \ref cmdxmlonly "\\xmlonly".
+  \sa section \ref cmdxmlonly "\\xmlonly",
+  \ref cmdhtmlinclude "\\htmlinclude",
+  \ref cmdlatexinclude "\\latexinclude",
+  \ref cmdrtfinclude "\\rtfinclude",
+  \ref cmdmaninclude "\\maninclude" and
+  \ref cmddocbookinclude "\\docbookinclude".
+
 <hr>
 
 \htmlonly</p><center><p>\endhtmlonly
@@ -2784,8 +2820,9 @@ only copy the detailed documentation, not the brief description.
   \sa section \ref cmdmanonly "\\manonly",
               \ref cmdlatexonly "\\latexonly",
               \ref cmdrtfonly "\\rtfonly",
-              \ref cmdxmlonly "\\xmlonly", and
-              \ref cmdhtmlonly "\\htmlonly".
+              \ref cmdxmlonly "\\xmlonly",
+              \ref cmdhtmlonly "\\htmlonly" and
+              \ref cmddocbookinclude "\\docbookinclude".
 
 <hr>
 \section cmddot \\dot ["caption"] [<sizeindication>=<size>]
@@ -3363,8 +3400,9 @@ class Receiver
   \sa sections \ref cmdhtmlonly "\\htmlonly",
                \ref cmdxmlonly "\\xmlonly",
                \ref cmdrtfonly "\\rtfonly",
-               \ref cmdlatexonly "\\latexonly", and
-               \ref cmddocbookonly "\\docbookonly".
+               \ref cmdlatexonly "\\latexonly",
+               \ref cmddocbookonly "\\docbookonly" and
+               \ref cmdmaninclude "\\maninclude".
 
 <hr>
 \section cmdli \\li { item-description }
@@ -3442,8 +3480,9 @@ class Receiver
   \sa sections \ref cmdmanonly "\\manonly",
                \ref cmdxmlonly "\\xmlonly",
                \ref cmdlatexonly "\\latexonly",
-               \ref cmdhtmlonly "\\htmlonly", and
-               \ref cmddocbookonly "\\docbookonly".
+               \ref cmdhtmlonly "\\htmlonly",
+               \ref cmddocbookonly "\\docbookonly" and
+               \ref cmdrtfinclude "\\rtfinclude".
 
 <hr>
 \section cmdverbatim \\verbatim
diff --git a/src/config.xml b/src/config.xml
index f3f4e5c..be890c3 100644
--- a/src/config.xml
+++ b/src/config.xml
@@ -1249,6 +1249,7 @@ FILE_VERSION_FILTER = "cleartool desc -fmt \%Vn"
  doxygen's defaults, run doxygen with the `-l` option. You can optionally specify a
  file name after the option, if omitted \c DoxygenLayout.xml will be used as the name
  of the layout file.
+ See also section \ref layout for information.
  <br>Note that if you run doxygen from a directory containing
  a file called \c DoxygenLayout.xml, doxygen will parse it automatically even if
  the \c LAYOUT_FILE tag is left empty.
@@ -2379,7 +2380,7 @@ The \c DOCSET_PUBLISHER_NAME tag identifies the documentation publisher.
  Windows users are probably better off using the HTML help feature.
 
  Via custom style sheets (see \ref cfg_html_extra_stylesheet "HTML_EXTRA_STYLESHEET")
- one can further \ref doxygen_finetune "fine-tune" the look of the index.
+ one can further fine tune the look of the index (see \ref doxygen_finetune).
  As an example, the default style sheet generated by doxygen has an
  example that shows how to put an image at the root of the tree instead of
  the \ref cfg_project_name "PROJECT_NAME".
diff --git a/src/configgen.py b/src/configgen.py
index d3b9137..5c4c39a 100755
--- a/src/configgen.py
+++ b/src/configgen.py
@@ -56,8 +56,11 @@ def transformDocs(doc):
 	doc = re.sub('\\\\ref +doxygen_usage', '"Doxygen usage"', doc)
 	doc = re.sub('\\\\ref +extsearch', '"External Indexing and Searching"',
 				 doc)
+	doc = re.sub('\\\\ref +layout', '"Changing the layout of pages"', doc)
 	doc = re.sub('\\\\ref +external', '"Linking to external documentation"',
 				 doc)
+	doc = re.sub('\\\\ref +doxygen_finetune', '"Fine-tuning the output"',
+				 doc)
 	doc = re.sub('\\\\ref +formulas', '"Including formulas"', doc)
 	# fallback for not handled
 	doc = re.sub('\\\\ref', '', doc)