- Adding wxWindows class documentation
+ Adding wxWidgets 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
+class to either the main wxWidgets manual, or to their own
manual.
-wxWindows uses Tex2RTF to process Latex-like input files (.tex)
+wxWidgets 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
+in the wxWidgets distribution and in the CVS archive, under
utils/tex2rtf. Please start by perusing the Tex2RTF manual.
+See http://www.wxwidgets.org/tex2rtf/index.htm for a browseable
+manual and binaries for specific platforms.
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.
+and add the entry to topics.tex. If applicable, also add an entry
+to category.tex.
If compiling a separate manual, copy an existing set of files from the
-wxWindows manual or a contribution. Contribution documentation
+wxWidgets manual or a contribution. Contribution documentation
normally goes in the contrib/docs hierarchy, with the source
going in a latex/mycontrib subdirectory.
tex2rtf manual.tex manual.rtf -rtf -twice
+If you wish to have a GUI display show the status of what is happening
+as the conversion is happening, use the '-interactive' command line
+parameter, and then choose FILE|GO from the menu. For example:
+
+ tex2rtf manual.tex manual.rtf -rtf -twice -interactive
+
+NOTE: You must be using the latest tex2rtf which was released with
+v2.2.0 of wxWidgets to use the -interactive switch
+
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.
+wxWidgets manual. To further speed-up HTML help books loading
+in your application, you may use hhp2cached (utils/hhp2cached).
src/msw/makefile.vc contains targets for generating various
formats of documentation. You may like to do something similar if
format and running through the Windows help compiler to check
for missing labels, etc.
+- quote all '_' and '&' characters with a '\' character (e.g. "MY\_PROGRAM"
+ unless the '_' is inside a comment or a \begin{verbatim} ...
+ \end{verbatim} block
+
+- check that your changes/additions to any TEX documentation
+ compiles before checking it in! Use the '-checkcurlybraces'
+ and '-checksyntax' commandline parameters (or the OPTIONS menu
+ if running in GUI mode) to check for some of the more common
+ mistakes. See TROUBLESHOOTING below for more details
+
+
DON'T:
- use jargon, such as 'gonna', or omit the definite article.
- leave multiple consecutive blank lines, or blank lines between
\items in a list.
+- use \verb$....$ syntax. Instead use \tt{....} syntax
+
+- add the following tokens anywhere except on a line by themselves:
+ \begin{verbatim}
+ \begin{toocomplex}
+ \end{verbatim}
+ \end{toocomplex}
+ \verb
+ \begin{comment}
+ \end{comment}
+ \verbatiminput
+ \par
+ \input
+ \helpinput
+ \include
+
+
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,
+ 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.
line comment character (%) to see whether it was that file that
caused the problem.
+ When making changes/additions to the documentation, always use
+ the '-checkcurlybraces' and '-checksyntax' commandline parameters
+ (or turn these options on in the GUI version via the OPTIONS menu
+ choice), BEFORE checking in your changes. These two debugging
+ options will catch many of the more common mistakes that are made
+ while writing documents, plus they will catch some of the uses
+ of TeX that are correct syntax-wise, but that tex2rtf cannot
+ handle properly, and report the problems (usually along with
+ a filename and line number that they occur in!) in the programs
+ output window (GUI mode).
+
Elements in a class file
========================
the screen is used.
\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type},
- \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
+ \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = $-1$}}
Creates a bitmap from the given data, which can be of arbitrary type.
\wxheading{Return value}
-TRUE if the call succeeded, FALSE otherwise.
+\true if the call succeeded, \false otherwise.
\wxheading{Remarks}
that several overloaded forms of the same member function are
documented within the same \membersection.
+
+Special forms:
+
+- for a const member function use \constfunc{} instead of \const
+
+- for a function without parameters use \func{...}{Function}{\void}
+
+- but do NOT use \void for functions without return value, just "void"
+
+- for a virtual/static member function use \func{virtual/static ...}
+
+- omit the return type for constructors: \func{}{MyClass}{...}
+
+- use \destruct macro for the destructors \func{}{\destruct{MyClass}}{\void}
+
+- use \true and \false instead of true/TRUE/{\tt true}/...
+
+- use \arg{paramname} to refer to the argument inside of the function
+ description
projects / wxWidgets.git / blobdiff