bug 668003 Default LaTeX header misses $-placeholders

Create, analogous to HTML, also for LaTeX default header and footer files.

1 files changed, 172 insertions, 29 deletions

diff --git a/src/config.xml b/src/config.xml
index c0b846a..9c0ccc8 100644
--- a/src/config.xml
+++ b/src/config.xml
@@ -1853,34 +1853,50 @@ doxygen -w html new_header.html new_footer.html new_stylesheet.css YourConfigFil
 <![CDATA[
  The following markers have a special meaning inside the header and footer:
  <dl>
- <dt><code>\$title</code><dd>will be replaced with the title of the page.
- <dt><code>\$datetime</code><dd>will be replaced with current the date and time.
- <dt><code>\$date</code><dd>will be replaced with the current date.
- <dt><code>\$year</code><dd>will be replaces with the current year.
- <dt><code>\$doxygenversion</code><dd>will be replaced with the version of doxygen
- <dt><code>\$projectname</code><dd>will be replaced with the name of
+ <dt><code>$title</code><dd>will be replaced with the title of the page.
+ <dt><code>$datetime</code><dd>will be replaced with current the date and time.
+ <dt><code>$date</code><dd>will be replaced with the current date.
+ <dt><code>$year</code><dd>will be replaces with the current year.
+ <dt><code>$doxygenversion</code><dd>will be replaced with the version of doxygen
+ <dt><code>$projectname</code><dd>will be replaced with the name of
             the project (see \ref cfg_project_name "PROJECT_NAME")
- <dt><code>\$projectnumber</code><dd>will be replaced with the project number
+ <dt><code>$projectnumber</code><dd>will be replaced with the project number
             (see \ref cfg_project_number "PROJECT_NUMBER")
- <dt><code>\$projectbrief</code><dd>will be replaced with the project brief
+ <dt><code>$projectbrief</code><dd>will be replaced with the project brief
             description (see \ref cfg_project_brief "PROJECT_BRIEF")
- <dt><code>\$projectlogo</code><dd>will be replaced with the project logo
+ <dt><code>$projectlogo</code><dd>will be replaced with the project logo
             (see \ref cfg_project_logo "PROJECT_LOGO")
- <dt><code>\$treeview</code><dd>will be replaced with links to
+ <dt><code>$generatedby</code><dd>will be replaced with the output language dependent
+            version of the text "Generated by" or when the
+            \ref cfg_html_timestamp "HTML_TIMESTAMP" is set by the output language
+            dependent version of the text &quot;Generated on `$datetime` for `$projectname` by&quot;.
+ <dt><code>$stylesheet</code><dd>will be replaced with the setting of
+            \ref cfg_html_stylesheet "HTML_STYLESHEET" unless it is empty or the file in which case
+            it is replaced by the default setting `doxygen.css`.
+ <dt><code>$extrastylesheet</code><dd>will be replaced with the setting of
+            \ref cfg_html_extra_stylesheet "HTML_EXTRA_STYLESHEET" including the required
+            HTML tags for each extra stylesheet.
+ <dt><code>$treeview</code><dd>will be replaced with links to
             the javascript and style sheets needed for the navigation tree
             (or an empty string when \ref cfg_generate_treeview "GENERATE_TREEVIEW"
             is disabled).
- <dt><code>\$search</code><dd>will be replaced with a links to
+ <dt><code>$search</code><dd>will be replaced with a links to
             the javascript and style sheets needed for the search engine
             (or an empty string when \ref cfg_searchengine "SEARCHENGINE"
             is disabled).
- <dt><code>\$mathjax</code><dd>will be replaced with a links to
+ <dt><code>$searchbox</code><dd>will be replaced with the HTML code needed for
+            the search box to be shown
+            (or an empty string when \ref cfg_searchengine "SEARCHENGINE"
+            is disabled).
+ <dt><code>$mathjax</code><dd>will be replaced with a links to
             the javascript and style sheets needed for the MathJax feature
             (or an empty string when \ref cfg_use_mathjax "USE_MATHJAX" is disabled).
- <dt><code>\$relpath^</code><dd>
- If \ref cfg_create_subdirs "CREATE_SUBDIRS" is enabled, the command <code>\$relpath^</code> can be
- used to produce a relative path to the root of the HTML output directory,
- e.g. use <code>\$relpath^doxygen.css</code>, to refer to the standard style sheet.
+ <dt><code>$relpath^</code><dd>
+            If \ref cfg_create_subdirs "CREATE_SUBDIRS" is enabled, the command <code>$relpath^</code> can be
+            used to produce a relative path to the root of the HTML output directory,
+            e.g. use <code>$relpath^doxygen.css</code>, to refer to the standard style sheet.
+ <dt><code>$navpath</code><dd>will be replaced with a path as required by
+            \ref cfg_generate_treeview "GENERATE_TREEVIEW"
  </dl>
 
  To cope with differences in the layout of the header and footer that depend on
@@ -2737,38 +2753,165 @@ or
     <option type='string' id='LATEX_HEADER' format='file' defval='' depends='GENERATE_LATEX'>
       <docs>
 <![CDATA[
- The \c LATEX_HEADER tag can be used to specify a personal \f$\mbox{\LaTeX}\f$
+ The \c LATEX_HEADER tag can be used to specify a user-defined \f$\mbox{\LaTeX}\f$
  header for the generated \f$\mbox{\LaTeX}\f$ document.
  The header should contain everything until the first chapter.
-
  If it is left blank doxygen will generate a
- standard header. See section \ref doxygen_usage for information on how to
- let doxygen write the default header to a separate file.
+ standard header.
+
+ It is highly recommended to start with a default header using
+\verbatim
+doxygen -w latex new_header.tex new_footer.tex new_stylesheet.sty
+\endverbatim
+ and then modify the file \c new_header.tex.
+
+ See also section \ref doxygen_usage for information on how to generate
+ the default header that doxygen normally uses.
 
  <br>Note: Only use a user-defined header if you know what you are doing!
 
- The following commands have a special meaning inside the header:
- <code>\$title</code>, <code>\$datetime</code>, <code>\$date</code>,
- <code>\$doxygenversion</code>, <code>\$projectname</code>,
- <code>\$projectnumber</code>, <code>\$projectbrief</code>,
- <code>\$projectlogo</code>.
- Doxygen will replace <code>\$title</code> with the empty string, for the replacement values of the
- other commands the user is referred to \ref cfg_html_header "HTML_HEADER".
+ @note The header is subject to change so you typically
+ have to regenerate the default header when upgrading to a newer version of
+ doxygen.
+ The following commands have a special meaning inside the header (and footer):
+]]>
+      </docs>
+      <docs doxywizard='0' doxyfile='0'>
+<![CDATA[
+ <dl>
+ <dt><code>$title</code><dd>will be replaced with the project name.
+ <dt><code>$datetime</code><dd>will be replaced with current the date and time.
+ <dt><code>$date</code><dd>will be replaced with the current date.
+ <dt><code>$year</code><dd>will be replaces with the current year.
+ <dt><code>$doxygenversion</code><dd>will be replaced with the version of doxygen
+ <dt><code>$projectname</code><dd>will be replaced with the name of
+           the project (see \ref cfg_project_name "PROJECT_NAME")
+ <dt><code>$projectnumber</code><dd>will be replaced with the project number
+           (see \ref cfg_project_number "PROJECT_NUMBER")
+ <dt><code>$projectbrief</code><dd>will be replaced with the project brief
+           description (see \ref cfg_project_brief "PROJECT_BRIEF")
+ <dt><code>$projectlogo</code><dd>will be replaced with the project logo
+           (see \ref cfg_project_logo "PROJECT_LOGO")
+ <dt><code>$latexdocumentpre</code><dd>will be replaced by an output language dependent setting
+           e.g. embed the entire document in a special environment (for Chinese, Japanese etc.)
+           Commonly used together with `$latexdocumentpost` in the footer.
+ <dt><code>$latexdocumentpost</code><dd>will be replaced by an output language dependent setting
+           e.g. embed the entire document in a special environment (for Chinese, Japanese etc.)
+           Commonly used together with `$latexdocumentpre` in the header.
+ <dt><code>$generatedby</code><dd>will be replaced with the output language dependent
+           version of the text "Generated by" or when the
+           \ref cfg_latex_timestamp "LATEX_TIMESTAMP" is set by the output language
+           dependent version of the text &quot;Generated on `$datetime` for `$projectname` by&quot;.
+ <dt><code>$latexcitereference</code><dd>will be replaced by the output language dependent$
+           version of the word "Bibliography".
+           This setting is typically used in combination with the block name `CITATIONS_PRESENT`.
+ <dt><code>$latexbibstyle</code><dd>will be replaced with the latex bib style to be used as
+           as set by \ref cfg_latex_bib_style "LATEX_BIB_STYLE", in case nothing is set the bib style
+           `plain` is used.
+           This setting is typically used in combination with the block name `CITATIONS_PRESENT`.
+ <dt><code>$latexbibfiles</code><dd>will be replaced by the comma separeted list of `bib. files
+           as set by \ref cfg_cite_bib_files "CITE_BIB_FILES" (when necessary a missing `.bib` is
+           automatically added).
+           This setting is typically used in combination with the block name `CITATIONS_PRESENT`.
+ <dt><code>$papertype</code><dd>will be replaced by the paper type as set in
+           \ref cfg_paper_type "PAPER_TYPE" and the word "paper" is directly appended to it to have
+           a correct \f$\mbox{\LaTeX}\f$ paper type.
+ <dt><code>$languagesupport</code><dd>will be replaced by an output language dependent setting
+           of packages required for translating terms of the specified language.
+ <dt><code>$latexfontenc</code><dd>will be replaced by an output language dependent setting
+           of the fontencoding to be used.
+           This setting is typically used in combination with the block name `LATEX_FONTENC`.
+ <dt><code>$latexfont</code><dd>will be replaced by an output language dependent setting
+           of the fonts to be used.
+ <dt><code>$latexemojidirectory</code><dd>will be replaced by the directory as set in
+           \ref cfg_latex_emoji_directory "LATEX_EMOJI_DIRECTORY" with the backslashes replaced by
+           forward slashes (so usable by \f$\mbox{\LaTeX}\f$). In case the
+           \ref cfg_latex_emoji_directory "LATEX_EMOJI_DIRECTORY" is
+           empty, the current directory will be used.
+ <dt><code>$makeindex</code><dd>will be replaced by the command as set in
+           \ref cfg_latex_makeindex_cmd "LATEX_MAKEINDEX_CMD". Then the command doesn't start with
+           a backslash, a backslash is automatically prepended. In case the setting is empty the
+           command `\makeindex` is used.
+ <dt><code>$extralatexpackages</code><dd>will be replaced by commands for usinging the packages set
+           in \ref cfg_extra_packages "EXTRA_PACKAGES".
+ <dt><code>$extralatexstylesheet</code><dd>will be replaced by commands for usinging the packages set
+           in \ref cfg_latex_extra_stylesheet "LATEX_EXTRA_STYLESHEET" (when the extension is the default
+           extension, `.sty`, this extension is stripped for the package name).
+ <dt><code>$latexspecialformulachars</code><dd>will be replaced by the code for some special
+           unicode characters that are commonly used (i.e. superscript minus, superscript 2 and superscript 3)
+ <dt><code>$formulamacrofile</code><dd>will be replaced by the name of the file as set
+           in \ref cfg_formula_macrofile "FORMULA_MACROFILE".
+           This setting is typically used in combination with the block name `FORMULA_MACROFILE`.
+ </dl>
+
+To cope with differences in the layout of the header and footer that depend on
+ configuration settings, the header and footer can also contain special blocks that
+ will be copied to the output or skipped depending on the configuration.
+ Such blocks have the following form:
+\verbatim
+ %%BEGIN BLOCKNAME
+ Some context copied when condition BLOCKNAME holds
+ %%END BLOCKNAME
+ %%BEGIN !BLOCKNAME
+ Some context copied when condition BLOCKNAME does not hold
+ %%END !BLOCKNAME
+\endverbatim
+The following block names are set based on the used settings in the
+ configuration file:
+ <dl>
+ <dt><code>COMPACT_LATEX</code><dd>Content within this block is copied to the output
+     when the \ref cfg_compact_latex "COMPACT_LATEX" option is enabled.
+ <dt><code>PDF_HYPERLINKS</code><dd>Content within this block is copied to the output
+     when the \ref cfg_pdf_hyperlinks "PDF_HYPERLINKS" option is enabled.
+ <dt><code>USE_PDFLATEX</code><dd>Content within this block is copied to the output
+     when the \ref cfg_use_pdflatex "USE_PDFLATEX" option is enabled.
+ <dt><code>LATEX_BATCHMODE</code><dd>Content within this block is copied to the output
+     when the \ref cfg_latex_batchmode "LATEX_BATCHMODE" option is enabled.
+ <dt><code>LATEX_TIMESTAMP</code><dd>Content within this block is copied to the output
+     when the \ref cfg_latex_timestamp "LATEX_TIMESTAMP" option is enabled.
+ </dl>
+The following block names are set based on the fact whether or not the tag has a
+ value in the used configuration file:
+ <dl>
+ <dt><code>LATEX_FONTENC</code><dd>Content within this block is copied to the output
+     when the doxygen latex translator function returns a value for the font encoding
+     to be used. It is to be used in combination with the above mentioned `$latexfontenc`.
+ <dt><code>FORMULA_MACROFILE</code><dd>Content within this block is copied to the output
+     when the \ref cfg_formula_macrofile "FORMULA_MACROFILE" option is not empty. It is
+     to be used in combination with the above mentioned `$formulamacrofile`.
+ </dl>
+The following block name is set based on whether or not a feature is used in the
+ documentation:
+ <dl>
+ <dt><code>CITATIONS_PRESENT</code><dd>Content within this block is copied to the output
+     when in the documentation citations are present and the relevant .. are present.
+     It is to be used in combination with the above mentioned `$latexcitereference`,
+     `$latexbibstyle` and `$latexbibfiles`.
+ </dl>
+]]>
+      </docs>
+      <docs documentation='0'>
+<![CDATA[
+ For a description of the possible markers and block names see the documentation.
 ]]>
       </docs>
     </option>
     <option type='string' id='LATEX_FOOTER' format='file' defval='' depends='GENERATE_LATEX'>
       <docs>
 <![CDATA[
- The \c LATEX_FOOTER tag can be used to specify a personal \f$\mbox{\LaTeX}\f$ footer for
+ The \c LATEX_FOOTER tag can be used to specify a user-defined \f$\mbox{\LaTeX}\f$ footer for
  the generated \f$\mbox{\LaTeX}\f$ document. The footer should contain everything after
  the last chapter. If it is left blank doxygen will generate a
  standard footer.
+
  See \ref cfg_latex_header "LATEX_HEADER" for more information on
  how to generate a default footer and what special commands can be
  used inside the footer.
 
- <br>Note: Only use a user-defined footer if you know what you are doing!
+ See also section \ref doxygen_usage for information on how to generate
+ the default footer that doxygen normally uses.
+
+ Note: Only use a user-defined footer if you know what you are doing!
 ]]>
       </docs>
     </option>