X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12646a5ae2b43a1954c8bd962328268ae564f1f6..5e7ea8ebb259cf4a96f35e77abdd334c01327010:/docs/tech/tn0003.txt

diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt
index 7aab63066f..a1fa46e997 100644
--- a/docs/tech/tn0003.txt
+++ b/docs/tech/tn0003.txt
@@ -9,12 +9,15 @@ 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.
+See http://www.wxwindows.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
@@ -45,10 +48,20 @@ 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 wxWindows 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.
+wxWindows 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
@@ -75,6 +88,17 @@ DO:
   format and running through the Windows help compiler to check
   for missing labels, etc.
 
+- quote all '_' 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 '-checkcurleybrace' 
+  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.
@@ -89,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.
@@ -112,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 '-checkcurleybraces' 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
 ========================
 
@@ -203,3 +255,18 @@ 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}
+