doc/doxygen_usage.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2012 by Dimitri van Heesch.
   6  *
   7  * Permission to use, copy, modify, and distribute this software and its
   8  * documentation under the terms of the GNU General Public License is hereby
   9  * granted. No representations are made about the suitability of this software
  10  * for any purpose. It is provided "as is" without express or implied warranty.
  11  * See the GNU General Public License for more details.
  12  *
  13  * Documents produced by Doxygen are derivative works derived from the
  14  * input used in their production; they are not affected by this license.
  15  *
  16  */
  17 /*! \page doxygen_usage Doxygen usage
  18
  19 Doxygen is a command line based utility.  Calling \c doxygen with the
  20 \c --help option at the command line will give you a brief description of the
  21 usage of the program.
  22
  23 All options consist of a leading character <tt>-</tt>,
  24 followed by one character and one or more arguments depending on the option.
  25
  26 To generate a manual for your project you typically
  27 need to follow these steps:
  28 <ol>
  29 <li> You document your source code with
  30      special documentation blocks (see section \ref specialblock).
  31 <li> You generate a configuration file (see section \ref config) by
  32      calling doxygen with the \c -g option:
  33 \verbatim
  34 doxygen -g <config_file>
  35 \endverbatim
  36 <li> You edit the configuration file so it matches your project.
  37      In the configuration file you can specify the input files and
  38      a lot of optional information.
  39 <li> You let doxygen generate the documentation, based on the settings in the
  40      configuration file:
  41 \verbatim
  42 doxygen <config_file>
  43 \endverbatim
  44 </ol>
  45
  46 If you have a configuration file generated with an older version of
  47 doxygen, you can upgrade it to the current version by running doxygen
  48 with the -u option.
  49 \verbatim
  50 doxygen -u <config_file>
  51 \endverbatim
  52 All configuration settings in the original configuration file will be copied
  53 to the new configuration file. Any new options will have their default value.
  54 Note that comments that you may have added in the original configuration file
  55 will be lost.
  56
  57 \section doxygen_finetune Fine-tuning the output
  58 If you want to fine-tune the way the output looks, doxygen allows you
  59 generate default style sheet, header, and footer files that you can edit
  60 afterwards:
  61 <ul>
  62 <li>For HTML output, you can generate the default header file
  63     (see \ref cfg_html_header "HTML_HEADER"), the default footer
  64     (see \ref cfg_html_footer "HTML_FOOTER"), and the default style
  65     sheet (see \ref cfg_html_stylesheet "HTML_STYLESHEET"), using the
  66     following command:
  67 \verbatim
  68 doxygen -w html header.html footer.html stylesheet.css <config_file>
  69 \endverbatim
  70   The config_file is optional. When omitted doxygen will search for
  71   a file named Doxyfile and process that. When this is also not found it
  72   will used the default settings.
  73
  74 <li>For LaTeX output, you can generate the first part of \c refman.tex
  75     (see \ref cfg_latex_header "LATEX_HEADER") and the style sheet included
  76     by that header (normally <code>doxygen.sty</code>), using:
  77 \verbatim
  78 doxygen -w latex header.tex doxygen.sty
  79 \endverbatim
  80 If you need non-default options (for instance to use pdflatex) you need
  81 to make a config file with those options set correctly and then specify
  82 that config file as the third argument.
  83 <li>For RTF output, you can generate the default style sheet file (see
  84     \ref cfg_rtf_stylesheet_file "RTF_STYLESHEET_FILE") using:
  85 \verbatim
  86 doxygen -w rtf rtfstyle.cfg
  87 \endverbatim
  88 </ul>
  89 \warning When using a custom header you are responsible
  90   for the proper inclusion of any scripts and style sheets that doxygen
  91   needs, which is dependent on the configuration options and may changes
  92   when upgrading to a new doxygen release.
  93
  94 \note
  95 <ul>
  96 <li> If you do not want documentation for each item inside the configuration
  97      file then you can use the optional \c -s option. This can use be
  98      used in combination with the \c -u option, to add or strip the
  99      documentation from an existing configuration file.
 100      Please use the \c -s option if you send me a configuration file
 101      as part of a bug report!
 102 <li> To make doxygen read/write to standard input/output instead of from/to
 103      a file, use \c - for the file name.
 104 </ul>
 105
 106 */