120 lines
4.9 KiB
Plaintext
120 lines
4.9 KiB
Plaintext
/******************************************************************************
|
|
*
|
|
*
|
|
*
|
|
* Copyright (C) 1997-2015 by Dimitri van Heesch.
|
|
*
|
|
* Permission to use, copy, modify, and distribute this software and its
|
|
* documentation under the terms of the GNU General Public License is hereby
|
|
* granted. No representations are made about the suitability of this software
|
|
* for any purpose. It is provided "as is" without express or implied warranty.
|
|
* See the GNU General Public License for more details.
|
|
*
|
|
* Documents produced by analyze are derivative works derived from the
|
|
* input used in their production; they are not affected by this license.
|
|
*
|
|
*/
|
|
/*! \page analyze_usage analyze usage
|
|
|
|
analyze is a command line based utility. Calling \c analyze with the
|
|
`--help` option at the command line will give you a brief description of the
|
|
usage of the program.
|
|
|
|
All options consist of a leading character <tt>-</tt>,
|
|
followed by one character and one or more arguments depending on the option.
|
|
|
|
To generate a manual for your project you typically
|
|
need to follow these steps:
|
|
<ol>
|
|
<li> You document your source code with
|
|
special documentation blocks (see section \ref specialblock).
|
|
<li> You generate a configuration file (see section \ref config) by
|
|
calling analyze with the \c -g option:
|
|
\verbatim
|
|
analyze -g <config_file>
|
|
\endverbatim
|
|
<li> You edit the configuration file so it matches your project.
|
|
In the configuration file you can specify the input files and
|
|
a lot of optional information.
|
|
<li> You let analyze generate the documentation, based on the settings in the
|
|
configuration file:
|
|
\verbatim
|
|
analyze <config_file>
|
|
\endverbatim
|
|
</ol>
|
|
|
|
If you have a configuration file generated with an older version of
|
|
analyze, you can upgrade it to the current version by running analyze
|
|
with the -u option.
|
|
\verbatim
|
|
analyze -u <config_file>
|
|
\endverbatim
|
|
All configuration settings in the original configuration file will be copied
|
|
to the new configuration file. Any new options will have their default value.
|
|
Note that comments that you may have added in the original configuration file
|
|
will be lost.
|
|
|
|
\section analyze_finetune Fine-tuning the output
|
|
If you want to fine-tune the way the output looks, analyze allows you
|
|
generate default style sheet, header, and footer files that you can edit
|
|
afterwards:
|
|
<ul>
|
|
<li>For HTML output, you can generate the default header file
|
|
(see \ref cfg_html_header "HTML_HEADER"), the default footer
|
|
(see \ref cfg_html_footer "HTML_FOOTER"), and the default style
|
|
sheet (see \ref cfg_html_stylesheet "HTML_STYLESHEET"), using the
|
|
following command:
|
|
\verbatim
|
|
analyze -w html header.html footer.html stylesheet.css <config_file>
|
|
\endverbatim
|
|
The `config_file` is optional. When omitted analyze will search for
|
|
a file named `analzfile` and process that. When this is also not found it
|
|
will used the default settings.
|
|
|
|
<li>For \LaTeX output, you can generate the first and last part of \c refman.tex
|
|
(see \ref cfg_latex_header "LATEX_HEADER" and
|
|
\ref cfg_latex_footer "LATEX_FOOTER") and the style sheet included
|
|
by that header (normally <code>analyze.sty</code>), using the following
|
|
command:
|
|
\verbatim
|
|
analyze -w latex header.tex footer.tex analyze.sty <config_file>
|
|
\endverbatim
|
|
If you need non-default options (for instance to use extra \LaTeX packages)
|
|
you need to make a configuration file with those options set correctly and then specify
|
|
that configuration file after the generated files (make a backup of the configuration
|
|
file first so you don't loose it in case you forget to specify one of the
|
|
output files).
|
|
<li>For RTF output, you can generate the default style sheet file (see
|
|
\ref cfg_rtf_stylesheet_file "RTF_STYLESHEET_FILE") using:
|
|
\verbatim
|
|
analyze -w rtf rtfstyle.cfg
|
|
\endverbatim
|
|
</ul>
|
|
\warning When using a custom header you are responsible
|
|
for the proper inclusion of any scripts and style sheets that analyze
|
|
needs, which is dependent on the configuration options and may change
|
|
when upgrading to a new analyze release.
|
|
|
|
\note
|
|
<ul>
|
|
<li> If you do not want documentation for each item inside the configuration
|
|
file then you can use the optional \c -s option. This can use be
|
|
used in combination with the \c -u option, to add or strip the
|
|
documentation from an existing configuration file.
|
|
To get a minimal configuration file use the \c -x or \-x_noenv option to
|
|
show only the differences from the default analyze configuration file.
|
|
Please use the \c -s or \c -x or \c -x_noenv option if you send me a
|
|
configuration file as part of a bug report or post an issue on GitHub!
|
|
(see also: \ref bug_reports "How to report a bug")
|
|
<li> To make analyze read/write to standard input/output instead of from/to
|
|
a file, use \c - for the file name.
|
|
</ul>
|
|
|
|
|
|
\htmlonly
|
|
Go to the <a href="analzwizard_usage.html">next</a> section or return to the
|
|
<a href="index.html">index</a>.
|
|
\endhtmlonly
|
|
|
|
*/
|