docs/tech/tn0003.txt

   1                      Adding wxWindows class documentation
   2                      ====================================
   3
   4 This note is aimed at people wishing to add documentation for a
   5 class to either the main wxWindows manual, or to their own
   6 manual.
   7
   8 wxWindows uses Tex2RTF to process Latex-like input files (.tex)
   9 and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided
  10 in the wxWindows distribution and in the CVS archive, under
  11 utils/tex2rtf. Please start by perusing the Tex2RTF manual.
  12
  13 If adding to the existing manual in docs/latex/wx, you need to
  14 create a new .tex file, e.g. myclass.tex, and add it to the
  15 list of classes in classes.tex (in strict alphabetical order).
  16 You may also want to write a separate topic file, e.g. tmyclass.tex,
  17 and add the entry to topics.tex.
  18
  19 If compiling a separate manual, copy an existing set of files from the
  20 wxWindows manual or a contribution. Contribution documentation
  21 normally goes in the contrib/docs hierarchy, with the source
  22 going in a latex/mycontrib subdirectory.
  23
  24 You can generate a first pass at the myclass.tex file by
  25 compiling and running HelpGen (utils/helpgen).
  26
  27 Running Tex2RTF
  28 ===============
  29
  30 See the Tex2RTF documentation, but here are some forms:
  31
  32 For HTML:
  33
  34   tex2rtf manual.tex manual.htm -html -twice
  35
  36 Use of -twice allows Tex2RTF to resolve references. Note that
  37 if both filenames are given (first two parameters on the command
  38 line) then Tex2RTF will run in non-interactive mode.
  39
  40 For WinHelp RTF:
  41
  42   tex2rtf manual.tex manual.rtf -winhelp -twice
  43
  44 For Word RTF:
  45
  46   tex2rtf manual.tex manual.rtf -rtf -twice
  47
  48 If you wish to have a GUI display show the status of what is happening
  49 as the conversion is happening, use the '-interactive' command line
  50 parameter, and then choose FILE|GO from the menu.  For example:
  51
  52    tex2rtf manual.tex manual.rtf -rtf -twice -interactive
  53
  54 NOTE: You must be using the latest tex2rtf which was released with
  55 v2.2.0 of wxWindowsto use the -interactive switch
  56
  57 If you wish to generate documentation for wxHTML Help Viewer
  58 (or Windows HTML Help), set htmlWorkshopFiles to true in your
  59 tex2rtf.ini file. See also the wxHTML Notes section in the
  60 wxWindows manual. To futher speed-up HTML help books loading
  61 in your application, you may use hhp2cached (utils/hhp2cached).
  62
  63 src/msw/makefile.vc contains targets for generating various
  64 formats of documentation. You may like to do something similar if
  65 writing your own manual.
  66
  67 Important Dos and Don'ts
  68 ========================
  69
  70 DO:
  71
  72 - put a space (or \rtfsp) at the end of a line or start of a line where
  73   a command ends or starts the line. Otherwise, spaces will be
  74   omitted in Word or WinHelp RTF. For example:
  75
  76   See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp
  77   for a list of possible values.
  78
  79 - leave a blank line at the end of the class file. This is
  80   important, or the Word RTF table of contents will be messed up.
  81
  82 - leave a blank line between a heading and the next paragraph.
  83
  84 - test your changes, preferably converting the manual to WinHelp
  85   format and running through the Windows help compiler to check
  86   for missing labels, etc.
  87
  88 DON'T:
  89
  90 - use jargon, such as 'gonna', or omit the definite article.
  91   The manual is intended to be a fluent, English document and
  92   not a collection of rough notes.
  93
  94 - use non-alphanumeric characters in labels.
  95
  96 - use incompatible Latex syntax, such as {\it \bf word} (use a pair
  97   of braces for each formatting command).
  98
  99 - leave multiple consecutive blank lines, or blank lines between
 100   \items in a list.
 101
 102 Troubleshooting
 103 ===============
 104
 105 Please see the troubleshooting section in the Tex2RTF manual, but
 106 here is one important tip:
 107
 108   If you get a "Macro not found: \end{document}" error,
 109    this is a spurious side-effect of an earlier error, usually an
 110    incorrect number of arguments to a command. The location of the
 111    true error is then anywhere in the document.
 112
 113    To home in on the error, try putting \begin{comment}...\end{comment}
 114    around much of the document, and then move the \begin{comment}
 115    line down until the error manifests itself again. Note that
 116    you can abort Tex2RTF after the syntax error stage by clicking
 117    on the close button, so you don't have to wait while the whole
 118    document is processed.
 119
 120    Before looking at a file in detail, you can comment out the
 121    \input{myclass.tex} line in classes.tex using the single
 122    line comment character (%) to see whether it was that file that
 123    caused the problem.
 124
 125 Elements in a class file
 126 ========================
 127
 128 Start off with:
 129
 130 \section{\class{wxMyClass}}\label{wxmyclass}
 131
 132 (note that labels can only go on sections such as \chapter,
 133 \section, \subsection, \membersection, but not on \wxheading, for
 134 example.)
 135
 136 Describe the class briefly.
 137
 138 Then there are several \wxheading sections:
 139
 140 \wxheading{Derived from}
 141
 142 List the base classes, with line breaks following each one (\\)
 143 except the last.
 144
 145 \wxheading{Include files}
 146
 147 List the relevant include files, for example:
 148
 149 <wx/myclass.h>
 150
 151 \wxheading{Predefined objects}
 152
 153 List any predefined objects, such as:
 154
 155 {\bf wxNullMyClass}
 156
 157 \wxheading{See also}
 158
 159 List any relevant classes or topics, using \helpref.
 160
 161 \latexignore{\rtfignore{\wxheading{Members}}}
 162
 163 This generates the required heading for the member definitions.
 164 Put the constructors first, then in alphabetical order, the other
 165 members.
 166
 167 Here's an example of documentation for a member function:
 168
 169          --------------------:x-----------------------
 170
 171 \membersection{wxBitmap::Create}\label{wxbitmapcreate}
 172
 173 \func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height},
 174  \param{int}{ depth = -1}}
 175
 176 Creates a fresh bitmap. If the final argument is omitted, the display depth of
 177 the screen is used.
 178
 179 \func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type},
 180  \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
 181
 182 Creates a bitmap from the given data, which can be of arbitrary type.
 183
 184 \wxheading{Parameters}
 185
 186 \docparam{width}{The width of the bitmap in pixels.}
 187
 188 \docparam{height}{The height of the bitmap in pixels.}
 189
 190 \docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.}
 191
 192 \docparam{data}{Data whose type depends on the value of {\it type}.}
 193
 194 \docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list
 195 of possible values.}
 196
 197 \wxheading{Return value}
 198
 199 TRUE if the call succeeded, FALSE otherwise.
 200
 201 \wxheading{Remarks}
 202
 203 The first form works on all platforms. The portability of the second form depends on the
 204 type of data.
 205
 206 \wxheading{See also}
 207
 208 \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}
 209
 210          --------------------:x-----------------------
 211
 212 Note the use of \docparam to document parameters; and the fact
 213 that several overloaded forms of the same member function are
 214 documented within the same \membersection.
 215