Main Page | Namespace List | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

dox.sh

Go to the documentation of this file.
00001 /*!
00002  * @file ./dox.sh
00003  *
00004  * @brief Create project documentation with @b Doxygen.
00005  *
00006  * Generate @b Doxygen documentation from source code containing
00007  * appropriate documentation tags.  Customize the output to
00008  * to eliminate unwanted warnings.
00009  *
00010  * @note Using GENERATE_RTF=YES seems to cause the spurious
00011  *       message, "QGDict::hashAsciiKey: Invalid null key"
00012  *       on otherwise working and valid documentation.
00013  *       The reasons are not yet known, and it may be that
00014  *       the directive file needs some different settings.
00015  *
00016  * @todo Identify reason for spurious message on RTF output as
00017  *       described above.
00018  *
00019  * @todo A proper solution to old NetScape 4.7X processing the
00020  *       HTML tag <b>&lt;pre class="fragment"&gt;</b> syntax needs to be
00021  *       found and implemented so that <b>&lt;code&gt;</b> and
00022  *       <b>@@verbatim</b> fragments, etc., may be displayed with proper
00023  *       framing @e and with proper newlines and white space.  For the
00024  *       interim solution, see the end of this script.  The problem will
00025  *       probably be solved by adjusting the <b>doxygen.css</b>
00026  *       (the default @b .css file) or supplying one that is customized
00027  *       for the project or perhaps just for old NetScape browsers.
00028  *       The scripts @link ./doxpatch.sh doxpatch.sh@endlink and
00029  *       @link ./doxunpatch.sh doxunpatch.sh@endlink that support
00030  *       the interim solution might also be used in support of the
00031  *       proper solution if an "original" and a "patched" version of
00032  *       the style sheet exists in the HTML output directory.
00033  *       The alternative is to have an original and patched version
00034  *       of the HTML pages, which might be preferable, depending on
00035  *       the actual visual artifacts.  In this case, a patch/unpatch
00036  *       script might either not be such a good idea or would be a bit
00037  *       more complex to implement.  In any event, the correct approach
00038  *       is to find the HTML problem and fix it, probably in the
00039  *       style sheet.
00040  *
00041  * @todo Perhaps the above to-do item should be generalized for the
00042  *       old NetScape 4.7X browser since is seems to have some overall
00043  *       problems with fonts in the default 'doxygen.css' style sheet.
00044  *       Perhaps someone with CSS experience could contribute one or
00045  *       more style sheets for use with different types of browsers so
00046  *       the HTML documents look the same on all of them.
00047  *
00048  * @todo Consider the creation of a <b>.css</b> file that is customized
00049  *       especially for this project.
00050  *
00051  * @todo A Windows .BAT version of this script needs to be written
00052  *
00053  * @bug If the token sequence "@b @c word1 word2..." is used, two
00054  *      words get bolded instead of one (doxygen 1.4.4).  Likewise
00055  *      with "@b @p word1 word2..."  By reversing the sequence,
00056  *      only one word gets bolded.  Is this a "bug" or a "feature"?
00057  *
00058  *
00059  * @section Control
00060  *
00061  * \$URL: https://svn.apache.org/path/name/dox.sh $ \$Id: dox.sh 0 09/28/2005 dlydick $
00062  *
00063  * Copyright 2005 The Apache Software Foundation
00064  * or its licensors, as applicable.
00065  *
00066  * Licensed under the Apache License, Version 2.0 ("the License");
00067  * you may not use this file except in compliance with the License.
00068  * You may obtain a copy of the License at
00069  *
00070  *     http://www.apache.org/licenses/LICENSE-2.0
00071  *
00072  * Unless required by applicable law or agreed to in writing,
00073  * software distributed under the License is distributed on an
00074  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
00075  * either express or implied.
00076  *
00077  * See the License for the specific language governing permissions
00078  * and limitations under the License.
00079  *
00080  * @version \$LastChangedRevision: 0 $
00081  *
00082  * @date \$LastChangedDate: 09/28/2005 $
00083  *
00084  * @author \$LastChangedBy: dlydick $
00085  *         Original code contributed by Daniel Lydick on 09/28/2005.
00086  *
00087  * @section Reference
00088  *
00089  */ /* 
00090  * (Use  #! and #/ with dox_filter.sh to fool Doxygen into
00091  * parsing this non-source text file for the documentation set.
00092  * Use the above open comment to force termination of parsing
00093  * since it is not a Doxygen-style 'C' comment.)
00094  *
00095  *
00096  *#######################################################################
00097  *
00098  * Script setup
00099  *
00100  *#######################################################################
00101  *
00102  * Verify that Doxygen program exists
00103  *
00104  * Text Doxygen program itself
00105  *#######################################################################
00106  *
00107  * Extract some basic values from top-level configuration header file.
00108  * Specifically, CONFIG_WORDWIDTH{32,64}, ARCH_BIG_ENDIAN,
00109  * ARCH_LITTLE_ENDIAN, ARCH_ODD4_ADDRESS_SIGSEGV.
00110  *
00111  *
00112  *
00113  *
00114  *#######################################################################
00115  *
00116  * Warnings about preprocessor symbols that are present only when
00117  * 'config/config.h' or 'jvm/src/arch.h' generate them.
00118  *
00119  *#######################################################################
00120  *
00121  * Mysterious warnings that I dont want to take the time to figure out
00122  * for whatever reason.
00123  *
00124  * MYSTERY1 comes and goes with @c directives in 'classfile.h' and shows
00125  * up in some source files that include it.
00126  *
00127  *#######################################################################
00128  *
00129  * Unnecessary warnings about specific files.
00130  *
00131  *#######################################################################
00132  *
00133  * Unnecessary warnings about shell scripts when INPUT_FILTER= has
00134  * been commented out so as to not properly parse them, yet to
00135  * speed up run time when working with just the source code, not
00136  * with shell scripts also.
00137  *
00138  *#######################################################################
00139  *
00140  * Clean up _all_ former output.  This is important to clear out stale
00141  * results during development and when changing the Doxygen 
00142  * configuration file.
00143  *
00144  * With the exception of effects of changing the configuration file,
00145  * this cleanup step really _could_ be done under the covers by doxygen
00146  * by virtue ofthe fact that new output files overwrite old output files,
00147  * but is done here anyway for the sake of being thorough and only
00148  * generating _exactly_ what the current contents of the configuration
00149  * file say should be generated:
00150  *
00151  *#######################################################################
00152  *
00153  * Construct output directory, clean up its subdirectories for results
00154  *
00155  *#######################################################################
00156  *
00157  * Construct complete filter list-- DO NOT wrap this filter definition!
00158  *
00159  *#######################################################################
00160  *
00161  * Make it happen.  If so configured, adjust <pre class="fragment"> HTML
00162  * tags for NetScape 4.7x so that they effectively ignore the tag.  If
00163  * 4.7x processes them as they stand, there will be no newline characters
00164  * displayed and all white space is condensed into one character in
00165  * these fragments.
00166  *
00167  *#######################################################################
00168  *
00169  * EOF
00170 

Generated on Fri Sep 30 18:59:19 2005 by  doxygen 1.4.4