Merge pull request #5136 from TimKam/4255-clarify-startdocname-config-param

#4255 clarify documentation of ``startdocname`` parameters.

doc/usage/configuration.rst

@@ -1765,32 +1765,39 @@ macros and environments, see also :doc:`/latex`.
    It must be a list of tuples ``(startdocname, targetname, title, author,
    documentclass, toctree_only)``, where the items are:
 
-   * *startdocname*: document name that is the "root" of the LaTeX file.  All
+   *startdocname*
-     documents referenced by it in TOC trees will be included in the LaTeX file
+     String that specifies the :term:`document name` of the LaTeX file's master
-     too.  (If you want only one LaTeX file, use your :confval:`master_doc`
+     document.  All documents referenced by the *startdoc* document in TOC trees
-     here.)
+     will be included in the LaTeX file.  (If you want to use the default master
-   * *targetname*: file name of the LaTeX file in the output directory.
+     document for your LaTeX build, provide your :confval:`master_doc` here.)
-   * *title*: LaTeX document title.  Can be empty to use the title of the
+
-     *startdoc*.  This is inserted as LaTeX markup, so special characters like a
+   *targetname*
+     File name of the LaTeX file in the output directory.
+
+   *title*
+     LaTeX document title.  Can be empty to use the title of the *startdoc*
+     document.  This is inserted as LaTeX markup, so special characters like a
      backslash or ampersand must be represented by the proper LaTeX commands if
      they are to be inserted literally.
-   * *author*: Author for the LaTeX document.  The same LaTeX markup caveat as
-     for *title* applies.  Use ``\\and`` to separate multiple authors, as in:
-     ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach
-     LaTeX).
-   * *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided
-     by Sphinx and based on ``'report'``, resp. ``'article'``; Japanese
-     documents use ``'jsbook'``, resp. ``'jreport'``.) "howto" (non-Japanese)
-     documents will not get appendices. Also they have a simpler title page.
-     Other document classes can be given. Independently of the document class,
-     the "sphinx" package is always loaded in order to define Sphinx's custom
-     LaTeX commands.
 
-   * *toctree_only*: Must be ``True`` or ``False``.  If true, the *startdoc*
+   *author*
-     document itself is not included in the output, only the documents
+     Author for the LaTeX document.  The same LaTeX markup caveat as for *title*
-     referenced by it via TOC trees.  With this option, you can put extra stuff
+     applies.  Use ``\\and`` to separate multiple authors, as in:
-     in the master document that shows up in the HTML, but not the LaTeX
+     ``'John \\and Sarah'`` (backslashes must be Python-escaped to reach LaTeX).
-     output.
+
+   *documentclass*
+     Normally, one of ``'manual'`` or ``'howto'`` (provided by Sphinx and based
+     on ``'report'``, resp. ``'article'``; Japanese documents use ``'jsbook'``,
+     resp. ``'jreport'``.) "howto" (non-Japanese) documents will not get
+     appendices. Also they have a simpler title page.  Other document classes
+     can be given. Independently of the document class, the "sphinx" package is
+     always loaded in order to define Sphinx's custom LaTeX commands.
+
+   *toctree_only*
+     Must be ``True`` or ``False``.  If true, the *startdoc* document itself is
+     not included in the output, only the documents referenced by it via TOC
+     trees.  With this option, you can put extra stuff in the master document
+     that shows up in the HTML, but not the LaTeX output.
 
    .. versionadded:: 1.2
       In the past including your own document class required you to prepend the
@@ -2264,9 +2271,11 @@ These options influence manual page output.
    section)``, where the items are:
 
    *startdocname*
-     Document name that is the "root" of the manual page.  All documents
+     String that specifies the :term:`document name` of the manual page's master
-     referenced by it in TOC trees will be included in the manual file too.
+     document. All documents referenced by the *startdoc* document in TOC trees
-     (If you want one master manual page, use your :confval:`master_doc` here.)
+     will be included in the manual file.  (If you want to use the default
+     master document for your manual pages build, use your :confval:`master_doc`
+     here.)
 
    *name*
      Name of the manual page.  This should be a short string without spaces or
@@ -2309,17 +2318,19 @@ These options influence Texinfo output.
    are:
 
    *startdocname*
-     Document name that is the "root" of the Texinfo file.  All documents
+     String that specifies the :term:`document name` of the the Texinfo file's
-     referenced by it in TOC trees will be included in the Texinfo file too.
+     master document.  All documents referenced by the *startdoc* document in
-     (If you want only one Texinfo file, use your :confval:`master_doc` here.)
+     TOC trees will be included in the Texinfo file.  (If you want to use the
+     default master document for your Texinfo build, provide your
+     :confval:`master_doc` here.)
 
    *targetname*
      File name (no extension) of the Texinfo file in the output directory.
 
    *title*
-     Texinfo document title.  Can be empty to use the title of the *startdoc*.
+     Texinfo document title.  Can be empty to use the title of the *startdoc*
-     Inserted as Texinfo markup, so special characters like ``@`` and ``{}``
+     document.  Inserted as Texinfo markup, so special characters like ``@`` and
-     will need to be escaped to be inserted literally.
+     ``{}`` will need to be escaped to be inserted literally.
 
    *author*
      Author for the Texinfo document.  Inserted as Texinfo markup.  Use ``@*``