Added tech note on adding class documentation.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@6648 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/tech/index.txt

@@ -1,4 +1,5 @@
 TN0001   How to add a new sample
 TN0002   wxWindows translator guide
+TN0003   Adding wxWindows class documentation
 
 Version: $Id$

docs/tech/tn0003.txt

@@ -0,0 +1,205 @@
+                     Adding wxWindows class documentation
+                     ====================================
+
+This note is aimed at people wishing to add documentation for a
+class to either the main wxWindows manual, or to their own
+manual.
+
+wxWindows uses Tex2RTF to process Latex-like input files (.tex)
+and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided
+in the wxWindows distribution and in the CVS archive, under
+utils/tex2rtf. Please start by perusing the Tex2RTF manual.
+
+If adding to the existing manual in docs/latex/wx, you need to
+create a new .tex file, e.g. myclass.tex, and add it to the
+list of classes in classes.tex (in strict alphabetical order).
+You may also want to write a separate topic file, e.g. tmyclass.tex,
+and add the entry to topics.tex.
+
+If compiling a separate manual, copy an existing set of files from the
+wxWindows manual or a contribution. Contribution documentation
+normally goes in the contrib/docs hierarchy, with the source
+going in a latex/mycontrib subdirectory.
+
+You can generate a first pass at the myclass.tex file by
+compiling and running HelpGen (utils/helpgen).
+
+Running Tex2RTF
+===============
+
+See the Tex2RTF documentation, but here are some forms:
+
+For HTML:
+
+  tex2rtf manual.tex manual.htm -html -twice
+
+Use of -twice allows Tex2RTF to resolve references. Note that
+if both filenames are given (first two parameters on the command
+line) then Tex2RTF will run in non-interactive mode.
+
+For WinHelp RTF:
+
+  tex2rtf manual.tex manual.rtf -winhelp -twice
+
+For Word RTF:
+
+  tex2rtf manual.tex manual.rtf -rtf -twice
+
+If you wish to generate documentation for wxHTML Help Viewer
+(or Windows HTML Help), set htmlWorkshopFiles to true in your
+tex2rtf.ini file. See also the wxHTML Notes section in the
+wxWindows manual.
+
+src/msw/makefile.vc contains targets for generating various
+formats of documentation. You may like to do something similar if
+writing your own manual.
+
+Important Dos and Don'ts
+========================
+
+DO:
+
+- put a space (or \rtfsp) at the end of a line or start of a line where
+  a command ends or starts the line. Otherwise, spaces will be
+  omitted in Word or WinHelp RTF. For example:
+
+  See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp
+  for a list of possible values.
+
+- leave a blank line at the end of the class file. This is
+  important, or the Word RTF table of contents will be messed up.
+
+- leave a blank line between a heading and the next paragraph.
+
+- test your changes, preferably converting the manual to WinHelp
+  format and running through the Windows help compiler to check
+  for missing labels, etc.
+
+DON'T:
+
+- use jargon, such as 'gonna', or omit the definite article.
+  The manual is intended to be a fluent, English document and
+  not a collection of rough notes.
+
+- use non-alphanumeric characters in labels.
+
+- use incompatible Latex syntax, such as {\it \bf word} (use a pair
+  of braces for each formatting command).
+
+- leave multiple consecutive blank lines, or blank lines between
+  \items in a list.
+
+Troubleshooting
+===============
+
+Please see the troubleshooting section in the Tex2RTF manual, but
+here is one important tip:
+
+  If you get a "Macro not found: \end{document}" error,
+   this is a spurious side-effect of an earlier error, usually an
+   incorrect number of arguments to a command. The location of the
+   true error is then anywhere in the document.
+
+   To home in on the error, try putting \begin{comment}...\end{comment}
+   around much of the document, and then move the \begin{comment}
+   line down until the error manifests itself again. Note that
+   you can abort Tex2RTF after the syntax error stage by clicking
+   on the close button, so you don't have to wait while the whole
+   document is processed.
+
+   Before looking at a file in detail, you can comment out the
+   \input{myclass.tex} line in classes.tex using the single
+   line comment character (%) to see whether it was that file that
+   caused the problem.
+
+Elements in a class file
+========================
+
+Start off with:
+
+\section{\class{wxMyClass}}\label{wxmyclass}
+
+(note that labels can only go on sections such as \chapter,
+\section, \subsection, \membersection, but not on \wxheading, for
+example.)
+
+Describe the class briefly.
+
+Then there are several \wxheading sections:
+
+\wxheading{Derived from}
+
+List the base classes, with line breaks following each one (\\)
+except the last.
+
+\wxheading{Include files}
+
+List the relevant include files, for example:
+
+<wx/myclass.h>
+
+\wxheading{Predefined objects}
+
+List any predefined objects, such as:
+
+{\bf wxNullMyClass}
+
+\wxheading{See also}
+
+List any relevant classes or topics, using \helpref.
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+This generates the required heading for the member definitions.
+Put the constructors first, then in alphabetical order, the other
+members.
+
+Here's an example of documentation for a member function:
+
+         --------------------:x-----------------------
+
+\membersection{wxBitmap::Create}\label{wxbitmapcreate}
+
+\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height},
+ \param{int}{ depth = -1}}
+
+Creates a fresh bitmap. If the final argument is omitted, the display depth of
+the screen is used.
+
+\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type},
+ \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
+
+Creates a bitmap from the given data, which can be of arbitrary type.
+
+\wxheading{Parameters}
+
+\docparam{width}{The width of the bitmap in pixels.}
+
+\docparam{height}{The height of the bitmap in pixels.}
+
+\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.}
+
+\docparam{data}{Data whose type depends on the value of {\it type}.}
+
+\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list
+of possible values.}
+
+\wxheading{Return value}
+
+TRUE if the call succeeded, FALSE otherwise.
+
+\wxheading{Remarks}
+
+The first form works on all platforms. The portability of the second form depends on the
+type of data.
+
+\wxheading{See also}
+
+\helpref{wxBitmap::wxBitmap}{wxbitmapconstr}
+
+         --------------------:x-----------------------
+
+Note the use of \docparam to document parameters; and the fact
+that several overloaded forms of the same member function are
+documented within the same \membersection.
+