--- /dev/null
+\documentstyle[a4,makeidx,verbatim,texhelp,fancyhea,mysober,mytitle]{report}%
+\twocolwidtha{4cm}%
+\definecolour{black}{0}{0}{0}%
+\definecolour{cyan}{0}{255}{255}%
+\definecolour{green}{0}{255}{0}%
+\definecolour{magenta}{255}{0}{255}%
+\definecolour{red}{255}{0}{0}%
+\definecolour{blue}{0}{0}{200}%
+\definecolour{yellow}{255}{255}{0}%
+\definecolour{white}{255}{255}{255}%
+%\input{psbox.tex}
+\newcommand{\commandref}[2]{\helpref{{\tt $\backslash$#1}}{#2}}%
+\newcommand{\commandrefn}[2]{\helprefn{{\tt $\backslash$#1}}{#2}\index{#1}}%
+\newcommand{\commandpageref}[2]{\latexignore{\helprefn{{\tt $\backslash$#1}}{#2}}\latexonly{{\tt $\backslash$#1} {\it page \pageref{#2}}}\index{#1}}%
+\newcommand{\indexit}[1]{#1\index{#1}}%
+\newcommand{\inioption}[1]{{\tt #1}\index{#1}}%
+\parskip=10pt%
+\parindent=0pt%
+\title{\cttitle}%
+\author{(c) Julian Smart, 2003}%
+\makeindex%
+\begin{document}%
+%\maketitle%
+\begin{center}
+\image{}{logo.gif}
+
+{\large {\bf Version \ctversion}}
+
+(c) Julian Smart
+\end{center}
+
+\pagestyle{fancyplain}%
+\bibliographystyle{plain}%
+\pagenumbering{arabic}%
+\setheader{{\it CONTENTS}}{}{}{}{}{{\it CONTENTS}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+\tableofcontents%
+
+
+\chapter{Welcome to \ctshortname}%
+\setheader{{\it Welcome}}{}{}{}{}{{\it Welcome}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+Welcome to \ctname, the easy way to configure wxWindows.
+Instead of tweaking a setup.h file, or typing a long configure
+command, you can now check and uncheck options in a convenient
+GUI tool, read the relevant reference document for each
+option, and save the setup.h file or configure command file.
+
+\begin{itemize}\itemsep=0pt
+\item For release information, please see \helpref{Release Notes}{releasenotes}.
+\item For a tour of the main windows in \ctshortname, please see the \helpref{User Interface}{documentui} section.
+%\item For a quick tutorial, go straight to \helpref{Getting Started}{gettingstarted}.
+\item For tips and troubleshooting, see the \helpref{How To}{howto} section.
+\end{itemize}
+
+\chapter{Contacts}%
+\setheader{{\it Contacts}}{}{}{}{}{{\it Contacts}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+The \ctname home page is at:
+
+{\tt \cturl}
+
+For help with \ctshortname or to report bugs,
+please go to the wxWindows web site.
+
+\section{Credits}
+
+\begin{center}
+{\bf (c) 2003 Julian Smart, Anthemion Software}\hrule
+
+{\it Designed by}
+
+{\bf Julian Smart}
+
+{\it Programmed by}
+
+{\bf Julian Smart}
+
+{\it Additional programming by}
+
+{\bf The wxWindows development team}
+
+\end{center}
+
+\chapter{Installation}%
+\setheader{{\it Installation}}{}{}{}{}{{\it Installation}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+{\bf On Windows:}
+
+Please run the installation program. This will create a program
+folder called \ctname (or other name if you have chosen a different name). This
+folder can be accessed via the Start menu under Programs. The
+folder contains shortcuts to the program, help file, and Uninstall program.
+
+You can uninstall \ctshortname either by double-clicking the Uninstall \ctshortname icon
+in the \ctname group, or by invoking the Windows Control Panel,
+double-clicking on Add/Remove Programs, and then choosing the \ctshortname item.
+
+{\bf On Linux:}
+
+Unarchive wxconfigtool-x.xx.tar.gz to a suitable location
+in your filesystem. A directory of the form wxconfigtool-x.xx
+(where x.xx is the version number) will be created.
+
+Add the location to your PATH and run the application with
+'wxconfigtool'. You may wish to set the environment variable
+WXCONFIGTOOLDIR so that wxWindows Configuration Tool can find its data files.
+
+For example:
+
+\begin{verbatim}
+ % cd ~
+ % tar xvfz wxconfigtool-1.01.tar.gz
+ % export WXCONFIGTOOLDIR=`pwd`/wxconfigtool-1.01
+ % export PATH=$PATH:$WXCONFIGTOOLDIR
+ % wxconfigtool
+\end{verbatim}
+
+If you don't want to change your PATH, you could place a
+script in a location already on your PATH, such as
+/usr/local/bin. For example:
+
+\begin{verbatim}
+ #!/bin/sh
+ # Invokes wxWindows Configuration Tool
+ export WXCONFIGTOOLDIR=/home/mydir/wxconfigtool-1.01
+ $WXCONFIGTOOLDIR/wxconfigtool $*
+\end{verbatim}
+
+{\bf On Mac:}
+
+Download and unarchive the HQX file, and drag the wxWindows Configuration Tool folder to an appropriate location
+on your hard disk. Then double-click on the 'wxconfigtool' executable.
+
+\chapter{Release notes}\label{releasenotes}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+For licencing information, please see
+the licence files in the installation directory:
+
+\begin{itemize}\itemsep=0pt
+\item licendoc.txt
+\item gpl.txt
+\item lgpl.txt
+\item preamble.txt
+\end{itemize}
+
+\section{What's New?}\label{whatsnew}
+
+{\bf Version 1.0, June 11th 2003}
+
+\begin{itemize}\itemsep=10pt
+\item Initial version.
+\end{itemize}
+
+\section{Known issues}\label{knownissues}
+
+The following problems are known to exist:
+
+\begin{itemize}\itemsep=10pt
+\item No issues as yet.
+\end{itemize}
+
+\section{To Do}\label{todo}
+
+There are many things that could be done to make
+this tool more useful, including the following.
+
+\begin{itemize}\itemsep=10pt
+\item Allow full platform-specific dependency specification
+as mentioned in \helpref{How to specify platform-specific dependencies}{platformdependencies}.
+\item Allow \ctshortname to invoke configure and make, with an output
+window showing build status.
+\item Distinguish between template files and settings file; allow
+application of template files to settings files, and vice versa.
+\item Implement support for string, integer, float settings.
+\item Write a configuration browser.
+\item Add description, date and author information to the settings file.
+\item Command-line mode with ability to change settings from
+the command-line. Just like configure :-)
+\item Decide on standard location for settings files.
+\item Integrate with new (and old?) build systems.
+\item Allow customization of font and colour.
+\item Show all calculated dependencies for each config item.
+\item Add a search facility.
+\end{itemize}
+
+\section{Differences between Windows, Linux and Mac versions}\label{platformdifferences}
+
+Although every effort has been made to make wxWindows Configuration Tool work
+the same way on different environments, some small differences
+are inevitable.
+
+\begin{itemize}\itemsep=10pt
+\item Screenshots illustrate the Windows version; the Linux
+and Mac windows and dialogs will be slightly different, but with equivalent
+functionality.
+\item Dialogs under Windows often have a '?' button on the title
+bar, for context-sensitive help. Under Linux, this button is
+on the dialog itself, usually near the OK or Close button.
+On the Mac, context-sensitive help is not yet supported.
+\item Under Linux, online help invoked from the {\bf Help} button
+in modal dialogs is itself modal. That is, you have to quit
+the help window to return to the dialog. On Windows, you can
+switch back to the dialog without quitting the help viewer.
+\item On Windows and Linux, context menus are invoked with
+right-click. On Mac, use control-click.
+\end{itemize}
+
+\chapter{\ctshortname user interface}\label{documentui}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+This section describes the main elements of the \ctname user interface.
+
+The \ctshortname main window looks like this:
+
+\begin{center}
+\image{}{screen01.png}
+\end{center}
+
+\section{Menubar}
+
+%\image{}{menubar.gif}
+
+The \helpref{menubar}{menubarcommands} allows you to perform many functions
+such as loading and saving files, creating new configuration items,
+undo/redo, invoking help, and so on. Try to remember the keyboard shortcuts that are
+displayed next to the menu item labels - they can save you a lot of time
+and make your \ctshortname experience more natural and enjoyable.
+
+\section{Main toolbar}
+
+%\image{}{toolbar.gif}
+
+The main toolbar gives quick access to commonly-used commands.
+If you hold your mouse pointer over the toolbar buttons, a tooltip pops up with a short description
+of the button's function.
+
+You can choose to hide the toolbar altogether
+using the {\bf View | Show Toolbar} menu command.
+
+You can find out more about in the \helpref{toolbar commands}{toolbarcommands} topic.
+
+\section{Configuration window}
+
+%\image{}{configwindow.gif}
+
+The biggest area of \ctshortname is taken up by the configuration window.
+
+On the left is a hierarchy of settings that can be customized.
+You can check and uncheck most settings, but you will find that
+many settings are disabled because they depend on other settings
+being enabled (or disabled).
+
+As an end user, you will probably only want to enable or disable
+options, but it's possible you may wish to update the structure
+of the settings file itself. In which case you can use the
+{\bf Edit} menu to add, remove, or rename items; and you can
+add custom properties to an item, but this is usually only
+useful for a developer of the tool to do.
+
+Undo/Redo can be applied to most editing commands, but (currently) not
+enabling and disabling operations.
+
+There are three tabs in the main window: {\bf Properties}, {\bf Setup.h},
+and {\bf Configure}. The Properties tab contains the properties
+for the selected option. Setup.h shows the setup file,
+and there are buttons to allow you to copy the file to the clipboard
+and regenerate the file. Similarly, the Configure tab shows
+the script that will invoke configure.
+
+The property editor allows you to show detailed information
+about the option. A description for each property is shown
+when you click on the property. You can also edit property values,
+either by clicking and typing, or by double-clicking or clicking
+on the {\bf Edit...} button. If a special editor is defined for
+the property type, it will be shown.
+
+You can invoke help for the selected option, by clicking
+on the question mark toolbar button or the {\bf Help | Configuration Item Help} menu
+item. If there is a help topic defined for the option, the
+wxWindows reference manual will be opened at that topic.
+
+\begin{comment}
+\chapter{Getting started: a step-by-step guide}\label{gettingstarted}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+This section will quickly get you up and running with \ctshortname. Click
+on \helpref{Step 1}{step1} to start. If you are
+using a Mac, please interpret 'left-click' to mean 'click', and
+'right-click' to mean 'control-click'.
+
+\section{Step 1: creating a new configuration}\label{step1}
+
+When you run \ctshortname for the first time, you are presented with an
+empty configuration window.
+
+Go to \helpref{Step 2}{step2} to learn how to do the next thing.
+
+\section{Step 2: doing something else}\label{step2}
+
+Go to \helpref{Step 3}{step3} to learn how to do a third thing.
+
+\section{Step 3: a third thing}\label{step3}
+
+Go to \helpref{Step 4}{step4} to learn about saving your document and reloading it.
+
+\section{Step 4: saving and loading documents}\label{step4}
+
+You may wish to save a document, so you can come back to it later. Click on {\bf File | Save} or
+the \image{}{save.png} toolbar button. The first time you save the file, you will be prompted
+for a filename: you can accept the default one provided, or choose another.
+
+To reload the document, click on {\bf File | Open...} or the \image{}{open.gif} toolbar button.
+If you are working on another document, you will be prompted to save it first.
+
+Go to \helpref{Step 5: generating configurations}{step5}
+
+\section{Step 5: generating configurations}\label{step5}
+
+Todo.
+
+Go to \helpref{Step 6: where next?}{step6}
+
+\section{Step 6: where next?}\label{step6}
+
+Congratulations! You have learnt how to create, edit, save, and load configuration
+files.
+
+To get to know \ctshortname more thoroughly, here are some further things you
+can do.
+
+\begin{itemize}
+\item Read the \helpref{How To}{howto} section.
+\item Use the help facilities: most dialogs have a {\bf Help} button for a general description, and they
+also have a {\bf "?"} button for getting information on individual controls on a dialog.
+\item Explore the menubar and the menus that appear when you right-click over
+the window background and individual cards.
+\end{itemize}
+
+\end{comment}
+
+\chapter{Using menubar commands}\label{menubarcommands}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+%\image{}{menubar.gif}
+
+This section describes the menubar commands. Commands
+that are not available in the current context are disabled (shown in grey).
+
+\section{File menu}
+
+The File menu shows commands that are mostly related to working
+with files.
+
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf New...} (Ctrl+N)}{Creates a new \ctshortname document.}
+\twocolitem{{\bf Open...} (Ctrl+O)}{Opens an existing document.}
+\twocolitem{{\bf Close} (Ctrl+W)}{Closes the current document.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Save} (Ctrl+S)}{Saves the current document.}
+\twocolitem{{\bf Save As...}}{Saves the current document under a new name.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Save Setup.h...} (Ctrl+H)}{Saves the generated setup.h file in the specified location.}
+\twocolitem{{\bf Save Configure Script...} (Ctrl+G)}{Saves the generated script containing a configure command in the specified location.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Exit} (Alt+F4)}{Exits the program.}
+\end{twocollist}
+
+\section{Edit menu}
+
+The Edit menu shows commands that are related to editing
+document elements.
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf Undo} (Ctrl+Z)}{Undoes the last undoable action.}
+\twocolitem{{\bf Redo} (Ctrl+Y)}{Redoes the last redoable action.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Cut} (Ctrl+T)}{Cuts the selected option and places it on the clipboard.}
+\twocolitem{{\bf Copy} (Ctrl+C)}{Copies the selected option.}
+\twocolitem{{\bf Paste} (Ctrl+V)}{Pastes an option from the clipboard to the position. Whether the
+option is pasted as a child or sibling of the selection is determined by whether
+the selection is a folder or not. If you want finer control, right-click on the
+item in the tree control and select one of the paste commands.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Add Option}}{Shows a menu for adding one of several option types.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Custom Property}}{Shows a menu for adding, editing or deleting a custom option property.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Delete Option}}{Deletes the selected option.}
+\twocolitem{{\bf Rename Option}}{Shows a dialog for renaming the selected option.}
+\end{twocollist}
+
+\section{View menu}
+
+The View menu gives you commands related to showing or hiding windows
+and various other preferences.
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf Show Toolbar}}{Shows or hides the toolbar, beneath the menubar.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Settings...} (Ctrl+T)}{Shows the \helpref{Settings Dialog}{settingsdialog}, which
+relate to application-wide settings.}
+\end{twocollist}
+
+\section{Help menu}
+
+The Help menu gives you commands related to getting help.
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf Contents}}{Invokes the on-line help, showing the contents page.}
+\twocolitem{{\bf wxWindows Help Contents}}{Invokes the on-line wxWindows reference manual, showing the contents page.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf Configuration Option Help} (F1)}{Invokes the on-line wxWindows reference manual at the topic for the selected option (if a topic
+is defined).}
+\twocolitem{{\bf What's This?}}{Click to get help on a window or configuration option.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf About...}}{Displays a dialog giving a brief description of the program.}
+\end{twocollist}
+
+\chapter{Using context menu commands}\label{contextmenucommands}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+This section describes the context menu commands available when you right-click.
+On the Mac, this is achieved with control-click.
+
+\section{Configuration tree context menu}
+
+This menu is shown when you right-click over the configuration tree window background.
+On the Mac, this is achieved with control-click.
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf Paste before this option}}{Pastes the clipboard option before the clicked-on option.}
+\twocolitem{{\bf Paste after this option}}{Pastes the clipboard option after the clicked-on option.}
+\twocolitem{{\bf Paste as child of this option}}{Pastes the clipboard option as a child of the clicked-on option,
+if it is a group option.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{{\bf C&opy}}{Copies the clicked-on option to the internal clipboard.}
+\twocolitem{{\bf Cu&t}}{Copies the clicked-on option to the internal clipboard, and
+deletes the option from the tree.}
+\end{twocollist}
+
+\chapter{Using toolbar commands}\label{toolbarcommands}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+This section describes the toolbar commands.
+
+%\image{}{toolbar.gif}
+
+The toolbar provides quick access to commonly-used
+commands.
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{\image{}{new.png}{\bf New Document}}{Creates a new document.}
+\twocolitem{\image{}{open.png}{\bf Open Document}}{Opens an existing document, closing the currently open document.}
+\twocolitem{\image{}{save.png}{\bf Save Document}}{Saves the current document.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{\image{}{undo.png}{\bf Undo}}{Undoes the last command.}
+\twocolitem{\image{}{redo.png}{\bf Redo}}{Redoes the last command.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{\image{}{copy.png}{\bf Copy}}{Copies the selected option to an internal clipboard.}
+\twocolitem{\image{}{cut.png}{\bf Cut}}{Cuts the selected option and copies it to the internal clipboard..}
+\twocolitem{\image{}{paste.png}{\bf Paste}}{Pastes the option from the clipboard to the configuration tree.}
+\twocolitem{\hrule}{\htmlonly{\hrule}}
+\twocolitem{\image{}{help.png}{\bf Help}}{Shows the wxWindows manual topic for the
+\twocolitem{\image{}{helpcs.png}{\bf Context Help}}{Shows a context-sensitive help
+cursor; click on a window to show brief help about that window.}
+selected configuration item.}
+\end{twocollist}
+
+\chapter{Using dialogs}\label{dialogs}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+Most dialogs have a {\bf "?"} button on their caption to provide context-sensitive help.
+Click on this and then on a control
+in a dialog to get quick help on that control. You can also click on the {\bf Help} button
+for more detailed help on the dialog.
+
+\section{Settings dialog}\label{settingsdialog}
+
+This dialog has a number of tabs to allow you to
+edit different categories of settings that are applicable
+to the application as a whole.
+
+\subsection{General settings dialog}\label{generalapplicationsettingsdialog}
+
+The General Settings Dialog allows you to set a variety of \ctshortname options.
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf Load last document on startup}}{If checked, the last viewed document will
+be reloaded when \ctshortname starts up.}
+% If the application terminated abnormally, this
+%option will be switched off the next time \ctshortname runs in case there was a problem with
+%the document file.}
+%\twocolitem{{\bf Auto-save document}}{If checked, \ctshortname will regularly
+%save the document to a temporary file. If \ctshortname or the operating system
+%should terminate abnormally, the next time \ctshortname is run it will
+%check for an auto-save file and ask if you wish to open that file.}
+%\twocolitem{{\bf Show welcome dialog on startup}}{If checked, the \helpref{Welcome Dialog}{welcomedialog} will
+%be shown on startup.}
+\twocolitem{{\bf Show tooltips}}{If checked, tooltips will be shown in most dialogs, when you hover
+the mouse pointer over a control.}
+\end{twocollist}
+
+\subsection{Location settings dialog}\label{locationsettingsdialog}
+
+The Location Settings Dialog allows you to choose various locations.
+
+\twocolwidtha{5cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf wxWindows hierarchy}}{This determines where \ctshortname will look
+when prompting for filenames.}
+\twocolitem{{\bf Use WXWIN environment variable}}{Check this to use
+the value of the WXWIN variable instead of the path entered in the text field.}
+\end{twocollist}
+
+\chapter{Using keyboard shortcuts}\label{keyboardshortcuts}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+You can make your \ctshortname experience even smoother by
+using handy keyboard shortcuts. Note that some shortcuts are
+dependent on context: that is, which control has the focus.
+
+\twocolwidtha{3cm}
+\begin{twocollist}\itemsep=0pt
+\twocolitem{{\bf Ctrl + C}}{Copies the selected option to the clipboard.}
+\twocolitem{{\bf Ctrl + H}}{Saves the setup.h file.}
+\twocolitem{{\bf Ctrl + G}}{Saves the configure script file.}
+\twocolitem{{\bf Ctrl + N}}{Creates a new \ctshortname file.}
+\twocolitem{{\bf Ctrl + O}}{Opens a \ctshortname file.}
+\twocolitem{{\bf Ctrl + S}}{Saves the current \ctshortname document.}
+\twocolitem{{\bf Ctrl + T}}{Shows the \helpref{Settings Dialog}{settingsdialog}.}
+\twocolitem{{\bf Ctrl + V}}{Pastes the option on the clipboard (if any) to the configuration tree.}
+\twocolitem{{\bf Ctrl + W}}{Closes the current \ctshortname document.}
+\twocolitem{{\bf Ctrl + X}}{Cuts the selected option and copies it to the clipboard.}
+\twocolitem{{\bf Ctrl + Y}}{Redoes the previously undone edit.}
+\twocolitem{{\bf Ctrl + Z}}{Undoes the previous edit.}
+\twocolitem{{\bf F1}}{Shows the online help for the selected item.}
+\twocolitem{{\bf Alt + F4}}{Closes \ctshortname.}
+\end{twocollist}
+
+\chapter{Reference}\label{reference}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+\section{The dependency evaluation algorithm}
+
+\ctshortname pre-calculates a list of all dependencies
+for each option -- this is a kind of reverse-pointer version
+of all the dependencies associated with each item. So
+if option {\bf a} has a {\bf requires} option specifying
+{\bf b}, then {\bf b} will end up with a dependency list
+containing {\bf a} and any other options that refer to it.
+
+When the user enables or disables an option ({\bf b}),
+the list of dependencies for that option is visited,
+and for each mentioned option ({\bf a}), all its dependency information
+is evaluated. This may result in the option {\bf a} being
+(de)selected and perhaps deactivated (made insensitive).
+
+The results of this change are propagated to dependents of
+{\bf a}, recursively, so several options may flip state
+as the result of checking the original option.
+
+The parent-child relationship of a check or radio
+group and its children is considered to be a virtual
+'requires' dependency. Mutual exclusivity is also
+taken into account if the option is a radio option
+or group. For each radio option, all other mutually
+exclusive options need to be listed. See the
+{\bf Platform} group for an example of this.
+
+\section{How \ctshortname generates the configure commands}
+
+If the {\bf configure} property isn't empty,
+\ctshortname will output the string as a parameter
+to configure.
+
+The configure command is taken to be the command to
+use if the option is checked. If the option is
+unchecked, the 'enable' or 'with' is replaced with
+'disable' or 'without'.
+
+TODO: should we distinguish between the case
+where a setting is not passed to configure (using
+the default), versus the case where it's specified but disabled?
+It's probably a good idea to make all the options
+explicit, but on the other hand it makes for a very long
+command line.
+
+\ctshortname checks for the presence of a
+{\bf builtin} custom boolean property and appends 'builtin' or
+'sys' to the configure command depending on where
+the {\bf builtin} setting is checked or unchecked.
+We also allow for passing strings, e.g. for --with-rpath=DIR,
+by using the {\bf value} custom string property.
+
+\section{How \ctshortname generates the setup.h file}
+
+The {\bf Platforms} group is ignored. In all other
+cases, if the setting is prefixed by wxUSE_...
+and it's a boolean setting, \ctshortname will
+output 1 or 0 depending on the setting state.
+
+A few settings that don't have the wxUSE_...
+convention are also checked for and processed.
+
+
+\chapter{How To...}\label{howto}%
+\setheader{{\it CHAPTER \thechapter}}{}{}{}{}{{\it CHAPTER \thechapter}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+
+A variety of topics to help you get the best from \ctshortname.
+
+\section{How to specify dependencies}\label{dependencies}
+
+To ensure consistency throughout the configuration,
+\ctshortname allows specification of dependencies, essentially
+a list of option names that should be considered in evaluating
+whether an option should be enabled or disabled. In addition,
+if the option is constrained to always be disabled
+or enabled in the current context, then it is greyed out
+(deactivated) to prevent the user from changing the state.
+
+There are four kinds of dependencies: requires, precludes,
+enabled-if, and enabled-if-not. Each one represents a
+relationship between the current option (a) and one
+or more named options (b). For the sake of argument
+we will consider only one other option, but multiple
+options are taken to mean (b1 or b2 or b3 or ...)
+Below the allowed combined states of a and b are
+listed for each kind of dependency.
+
+1. a {\bf requires} b
+
+For example, wxUSE_DRAG_AND_DROP requires wxUSE_OLE.
+
+\begin{verbatim}
+ a b
+
+ 1 1
+ 0 1
+ 0 0
+\end{verbatim}
+
+2. a {\bf precludes} b
+
+For example, wxUSE_ODBC precludes wxUSE_UNICODE.
+
+\begin{verbatim}
+ a b
+
+ 1 0
+ 0 0
+ 0 1
+\end{verbatim}
+
+
+3. a {\bf enabled-if} b
+
+For example, __WXUNIVERSAL__ enabled-if X11 or MGL
+
+\begin{verbatim}
+ a b
+
+ 1 1
+ 1 0
+ 0 0
+\end{verbatim}
+
+4. a {\bf enabled-if-not} b
+
+For example, wxUSE_TOOLBAR_SIMPLE enabled-if-not wxUSE_TOOLBAR_NATIVE.
+
+\begin{verbatim}
+ a b
+
+ 1 0
+ 0 1
+ 1 1
+\end{verbatim}
+
+\section{How to specify platform-specific dependencies}\label{platformdependencies}
+
+You can associate one or more options as part of the
+option's {\bf context}. In the case of wxUSE_OLE,
+the context contains __WXMSW__, because it's a Windows-specific
+option. This is used when calculating dependencies, as
+follows. If either option involved in a dependency
+relationship is not part of the current context, that
+is, none of the options in its {\bf context} property is currently
+enabled, then it is ignored in the dependency calculation.
+
+This allows the dependency 'wxUSE_DRAG_AND_DROP requires wxUSE_OLE'
+to only be evaluated when __WXMSW__ is enabled.
+
+It doesn't quite cover all bases, however, because
+it cannot express that the {\it dependency} itself
+is platform specific. You might have a platform-specific
+dependency that exists between two options that are
+perfectly valid for any platform. For example, we
+can't capture the notion that wxUSE_LISTBOX
+should be required if wxUSE_COMBOBOX is set,
+but only for __WXUNIVERSAL__. We could do it
+by complicating the dependency syntax, for example:
+
+wxUSE_COMBOBOX requires wxUSE_LISTBOX:__WXUNIVERSAL__
+
+This means that the dependency should only be
+evaluated if __WXUNIVERSAL__ is enabled.
+This has not been implemented yet.
+
+\section{How to specify custom properties}\label{customproperties}
+
+You can add custom properties to any option, but
+currently only {\bf option} and {\bf value} are
+recognised by \ctshortname.
+
+\ctshortname checks for the presence of a
+{\bf builtin} boolean custom property and appends 'builtin' or
+'sys' to the configure command depending on where
+the {\bf builtin} setting is checked or unchecked.
+We also allow for passing strings, e.g. for --with-rpath=DIR,
+by using the {\bf value} string custom property.
+
+\begin{comment}
+
+\begin{helpglossary}
+
+\gloss{thing}\label{thing}
+
+A glossary entry.
+
+\end{helpglossary}
+\end{comment}
+
+\rtfonly{%
+\addcontentsline{toc}{chapter}{Index}
+\printindex%
+\setheader{{\it INDEX}}{}{}{}{}{{\it INDEX}}%
+\setfooter{\thepage}{}{}{}{}{\thepage}%
+}
+\winhelponly{
+\chapter{Popups}\label{popups}
+
+} % WinHelp only
+
+\end{document}
projects / wxWidgets.git / blobdiff