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><pre class="fragment"></b> syntax needs to be 00021 * found and implemented so that <b><code></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