1 Adding wxWidgets class documentation 2 ==================================== 3 4This note is aimed at people wishing to add documentation for a 5class to either the main wxWidgets manual, or to their own 6manual. 7 8wxWidgets uses Tex2RTF to process Latex-like input files (.tex) 9and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided 10in the wxWidgets distribution and in the CVS archive, under 11utils/tex2rtf. Please start by perusing the Tex2RTF manual. 12See http://www.wxwidgets.org/tex2rtf/index.htm for a browseable 13manual and binaries for specific platforms. 14 15If adding to the existing manual in docs/latex/wx, you need to 16create a new .tex file, e.g. myclass.tex, and add it to the 17list of classes in classes.tex (in strict alphabetical order). 18You may also want to write a separate topic file, e.g. tmyclass.tex, 19and add the entry to topics.tex. If applicable, also add an entry 20to category.tex. 21 22If compiling a separate manual, copy an existing set of files from the 23wxWidgets manual or a contribution. Contribution documentation 24normally goes in the contrib/docs hierarchy, with the source 25going in a latex/mycontrib subdirectory. 26 27You can generate a first pass at the myclass.tex file by 28compiling and running HelpGen (utils/helpgen). 29 30Running Tex2RTF 31=============== 32 33See the Tex2RTF documentation, but here are some forms: 34 35For HTML: 36 37 tex2rtf manual.tex manual.htm -html -twice 38 39Use of -twice allows Tex2RTF to resolve references. Note that 40if both filenames are given (first two parameters on the command 41line) then Tex2RTF will run in non-interactive mode. 42 43For WinHelp RTF: 44 45 tex2rtf manual.tex manual.rtf -winhelp -twice 46 47For Word RTF: 48 49 tex2rtf manual.tex manual.rtf -rtf -twice 50 51If you wish to have a GUI display show the status of what is happening 52as the conversion is happening, use the '-interactive' command line 53parameter, and then choose FILE|GO from the menu. For example: 54 55 tex2rtf manual.tex manual.rtf -rtf -twice -interactive 56 57NOTE: You must be using the latest tex2rtf which was released with 58v2.2.0 of wxWidgets to use the -interactive switch 59 60If you wish to generate documentation for wxHTML Help Viewer 61(or Windows HTML Help), set htmlWorkshopFiles to true in your 62tex2rtf.ini file. See also the wxHTML Notes section in the 63wxWidgets manual. To further speed-up HTML help books loading 64in your application, you may use hhp2cached (utils/hhp2cached). 65 66src/msw/makefile.vc contains targets for generating various 67formats of documentation. You may like to do something similar if 68writing your own manual. 69 70Important Dos and Don'ts 71======================== 72 73DO: 74 75- put a space (or \rtfsp) at the end of a line or start of a line where 76 a command ends or starts the line. Otherwise, spaces will be 77 omitted in Word or WinHelp RTF. For example: 78 79 See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp 80 for a list of possible values. 81 82- leave a blank line at the end of the class file. This is 83 important, or the Word RTF table of contents will be messed up. 84 85- leave a blank line between a heading and the next paragraph. 86 87- test your changes, preferably converting the manual to WinHelp 88 format and running through the Windows help compiler to check 89 for missing labels, etc. 90 91- quote all '_' and '&' characters with a '\' character (e.g. "MY\_PROGRAM" 92 unless the '_' is inside a comment or a \begin{verbatim} ... 93 \end{verbatim} block 94 95- check that your changes/additions to any TEX documentation 96 compiles before checking it in! Use the '-checkcurlybraces' 97 and '-checksyntax' commandline parameters (or the OPTIONS menu 98 if running in GUI mode) to check for some of the more common 99 mistakes. See TROUBLESHOOTING below for more details 100 101 102DON'T: 103 104- use jargon, such as 'gonna', or omit the definite article. 105 The manual is intended to be a fluent, English document and 106 not a collection of rough notes. 107 108- use non-alphanumeric characters in labels. 109 110- use incompatible Latex syntax, such as {\it \bf word} (use a pair 111 of braces for each formatting command). 112 113- leave multiple consecutive blank lines, or blank lines between 114 \items in a list. 115 116- use \verb$....$ syntax. Instead use \tt{....} syntax 117 118- add the following tokens anywhere except on a line by themselves: 119 \begin{verbatim} 120 \begin{toocomplex} 121 \end{verbatim} 122 \end{toocomplex} 123 \verb 124 \begin{comment} 125 \end{comment} 126 \verbatiminput 127 \par 128 \input 129 \helpinput 130 \include 131 132 133Troubleshooting 134=============== 135 136Please see the troubleshooting section in the Tex2RTF manual, but 137here is one important tip: 138 139 If you get a "Macro not found: \end{document}" error, 140 this is a spurious side-effect of an earlier error, usually an 141 incorrect number of arguments to a command. The location of the 142 true error is then anywhere in the document. 143 144 To home in on the error, try putting \begin{comment}...\end{comment} 145 around much of the document, and then move the \begin{comment} 146 line down until the error manifests itself again. Note that 147 you can abort Tex2RTF after the syntax error stage by clicking 148 on the close button, so you don't have to wait while the whole 149 document is processed. 150 151 Before looking at a file in detail, you can comment out the 152 \input{myclass.tex} line in classes.tex using the single 153 line comment character (%) to see whether it was that file that 154 caused the problem. 155 156 When making changes/additions to the documentation, always use 157 the '-checkcurlybraces' and '-checksyntax' commandline parameters 158 (or turn these options on in the GUI version via the OPTIONS menu 159 choice), BEFORE checking in your changes. These two debugging 160 options will catch many of the more common mistakes that are made 161 while writing documents, plus they will catch some of the uses 162 of TeX that are correct syntax-wise, but that tex2rtf cannot 163 handle properly, and report the problems (usually along with 164 a filename and line number that they occur in!) in the programs 165 output window (GUI mode). 166 167Elements in a class file 168======================== 169 170Start off with: 171 172\section{\class{wxMyClass}}\label{wxmyclass} 173 174(note that labels can only go on sections such as \chapter, 175\section, \subsection, \membersection, but not on \wxheading, for 176example.) 177 178Describe the class briefly. 179 180Then there are several \wxheading sections: 181 182\wxheading{Derived from} 183 184List the base classes, with line breaks following each one (\\) 185except the last. 186 187\wxheading{Include files} 188 189List the relevant include files, for example: 190 191<wx/myclass.h> 192 193\wxheading{Predefined objects} 194 195List any predefined objects, such as: 196 197{\bf wxNullMyClass} 198 199\wxheading{See also} 200 201List any relevant classes or topics, using \helpref. 202 203\latexignore{\rtfignore{\wxheading{Members}}} 204 205This generates the required heading for the member definitions. 206Put the constructors first, then in alphabetical order, the other 207members. 208 209Here's an example of documentation for a member function: 210 211 --------------------:x----------------------- 212 213\membersection{wxBitmap::Create}\label{wxbitmapcreate} 214 215\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, 216 \param{int}{ depth = -1}} 217 218Creates a fresh bitmap. If the final argument is omitted, the display depth of 219the screen is used. 220 221\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type}, 222 \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = $-1$}} 223 224Creates a bitmap from the given data, which can be of arbitrary type. 225 226\wxheading{Parameters} 227 228\docparam{width}{The width of the bitmap in pixels.} 229 230\docparam{height}{The height of the bitmap in pixels.} 231 232\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.} 233 234\docparam{data}{Data whose type depends on the value of {\it type}.} 235 236\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list 237of possible values.} 238 239\wxheading{Return value} 240 241\true if the call succeeded, \false otherwise. 242 243\wxheading{Remarks} 244 245The first form works on all platforms. The portability of the second form depends on the 246type of data. 247 248\wxheading{See also} 249 250\helpref{wxBitmap::wxBitmap}{wxbitmapconstr} 251 252 --------------------:x----------------------- 253 254Note the use of \docparam to document parameters; and the fact 255that several overloaded forms of the same member function are 256documented within the same \membersection. 257 258 259Special forms: 260 261- for a const member function use \constfunc{} instead of \const 262 263- for a function without parameters use \func{...}{Function}{\void} 264 265- but do NOT use \void for functions without return value, just "void" 266 267- for a virtual/static member function use \func{virtual/static ...} 268 269- omit the return type for constructors: \func{}{MyClass}{...} 270 271- use \destruct macro for the destructors \func{}{\destruct{MyClass}}{\void} 272 273- use \true and \false instead of true/TRUE/{\tt true}/... 274 275- use \arg{paramname} to refer to the argument inside of the function 276 description 277