X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/12646a5ae2b43a1954c8bd962328268ae564f1f6..8e509c4b0c60bc066958574e4122a3db8ffcf491:/docs/tech/tn0003.txt diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt index 7aab63066f..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,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 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 @@ -75,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. @@ -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 '-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 ======================== @@ -167,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. @@ -186,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} @@ -203,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