X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23d38b36f8b53d322af1e692193eaca31ffa4208..bae2dc62af49b5a870bbabd9473a92921736a6f0:/docs/tech/tn0003.txt

diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt
index 57cab689b1..da54afac8d 100644
--- a/docs/tech/tn0003.txt
+++ b/docs/tech/tn0003.txt
@@ -1,23 +1,26 @@
-                     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.
 
@@ -45,10 +48,19 @@ For Word RTF:
 
   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. To futher speed-up HTML help books loading
+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
@@ -76,6 +88,17 @@ DO:
   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.
@@ -90,13 +113,30 @@ DON'T:
 - 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.
@@ -113,6 +153,17 @@ here is one important tip:
    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
 ========================
 
@@ -168,7 +219,7 @@ 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}}
+ \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = $-1$}}
 
 Creates a bitmap from the given data, which can be of arbitrary type.
 
@@ -187,7 +238,7 @@ of possible values.}
 
 \wxheading{Return value}
 
-TRUE if the call succeeded, FALSE otherwise.
+\true if the call succeeded, \false otherwise.
 
 \wxheading{Remarks}
 
@@ -204,3 +255,22 @@ 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.
 
+
+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