\documentstyle[12pt,psfig,html,a4,parskip]{article}
\setcounter{secnumdepth}{2}
\begin{document}
\author{Jesper K. Pedersen}
\title{{\hbox{\psfig{figure=logo.ps}}\ \\\ \\dotdot files}}
\maketitle
\begin{rawhtml}
  A <a href="dotdotfiles.ps">postscript</a> version is also available
  (640k)<br>
  And as <a href="dotdotfiles.ps.gz">gziped</a>(135k) and <a href="dotdotfiles.ps.Z">compressed</a>(206k)
\end{rawhtml}
\tableofcontents

%
% macro's
%
\newcommand{\pict}[1]{
  \centerline{\hbox{\psfig{figure=#1.ps}}}
  \html{\\\\}
}
\newcommand{\elmTable}[1]{
  \begin{center}
    \begin{tabular}{|l|l l|} \hline
    Name & Tk Element & \\\hline\hline
    #1
    \end{tabular}
  \end{center}
}

%%%
%%%
%%% What is the dotfile generator
%%%
%%%
\section{What is the Dotfile Generator}
The dotfile generator is a program which {\em translates\/} information
from checkboxes, entries, menus etc.\ to some sort of code (eg.\ Lisp, C,
the configuration language for the fvwm window manager, or any other
textual code). This transformation is {\em coded\/} in modules, where the
{\em programmer\/} tells which elements are to be shown (a checkbutton, listbox,
etc.) and gives some help on each element. But he doesn't have to worry
about how to make a listbox, how to make the help available, or how to
bind keys.
The following diagram should help explain the idea:

\pict{diagram}

%%%
%%%
%%% Syntax of the dotdot files
%%%
%%%
\section{Syntax of dotdot files}
A single module for the Dotfile Generator consists of several
configuration pages, each being implemented as a procedure in Tcl.

The first line in the procedure must be the path (in the menu tree) as
a Tcl comment. The path components are separated by slashes.\\
\# menu1 / menu2 / menuname \\
If the menu name is omitted, it defaults to the name of the procedure.

The {\em Desc\/} procedure is the one which sets the overall
description.

The {\em ShortDesc\/} procedure is the one which sets the title for the
output file.

The {\em Change\/} procedure is called each time something changes (a
letters is typed, a checkbutton is selected/deselected).

The {\em Init\/} procedure is called the very first time the menupage is
created.

The {\em PageEnd\/} procedure is called each time a menupage is left. 

%
%
%%% Element on a configuration page
%
%
\section{Element on a configuration page}
Here is a complete list of element which may appear at the configuration
page, and which arguments they take.

\subsection{Syntax and Variables}
All the elements on the configuration page have the same syntax, which is as
follows:\\
{\em element name [-option value [value ..]] ..} All the values for a
single option will then be concatenated, which makes it easier to write
beautiful code like this: \\
\begin{verbatim}
checkbox save -text save on exit -default 1 -help "This options" \
     "let you tell ..." (etc etc)
\end{verbatim}
Insert an extra dash, if a value starts with a dash,  (No Tk option
starts with two dashes, so this is safe.) The extra dash you inserted
will be removed before the value is used.

Ex: {\tt -font -*-helvetica-medium-r-*-*-18-* will be specified}\\
as: {\tt -font --*-helvetica-medium-r-*-*-18-*}\\
\begin{latexonly}
\verb+         ^+----- This is the dash.\\
\end{latexonly}
{\bf Note:} It is not recommended to refrain from using quotation marks
in the {\em Desc\/} field and to the help option, because every word
will then be checked to see if it is an option, in contrast to the
quotation mark situation where everything between the quotation marks is
considered as one word.

The {\em Link to Variable} section tells how the information is
available in the {\em Save, Change, Init\/} and {\em PageEnd\/}
\hyperref{procedure.}{procedure. (See dection }{)}{specialFunc}
\\

All the places where the default value for the option (the value which
it is set to, if it isn't specified) is nonempty, it is
specified like this: {\tt default:} {\em value\/}
  
\subsection{CheckBox}
\pict{checkbox}

A CheckBox is for Yes/No like answers. You can select it, or deselect it.
\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the text which will be in the checkbox.
  \item[-default] This is the default value for the checkbox, it must
    be either 0 for deselected or 1 for selected. (default value if not set: 0)
  \item[-help] This is the help for the checkbox.
\end{description}

\subsubsection{Link to Variables}
A CheckBox links to a variable of the same name as the CheckBox.

\subsection{Radio}
\pict{radio}
A Radio is used to select one out of several, where each element is visible.
\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the title for the element.
  \item[-default] This is the default value of the menu. This can be
    specified in two ways.
    \begin{enumerate}
      \item The entry as text eg. ``first option''
      \item the index of the entry
    \end{enumerate}
    If an element could be both an index and a menu entry, it is
    considered as an index. (default value if not set: 0)
  \item[-entries] This is a list of the element which are the entries you
    can select.
  \item[-count] This tells how many columns you want.(default: 5)
  \item[-entryhelp] This is a list {\tt \{"element 1" "help
    for element 1" "element 2" "help for element 2" ...}.\\
    If this is given, the {\em -entries} option is ignored.
  \item[-help] This is help for the overall Radio element.
\end{description}

\subsubsection{Link to Variables}
A Radio links to an associative array with the same name as the Radio,
and with the following keys:
\begin{description}
  \item[name] This is the text which is selected
  \item[index] This is the index of the selected element.
\end{description}

      
\subsection{Entry, Int, Float}
\pict{entry}
An Entry is for single lined text input. Int and Float are specialized
Entries which will only allow integers and reals, respectively.

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the text before the entry.
  \item[-textafter] This is the text after the entry.
  \item[-default] This is the default value.
  \item[-help] This is the help for the entry.
\end{description}

\subsubsection{Link to Variables}
Entry, Int, Float links to a variable of the same name as the element.
  
\subsection{Menu}
\pict{menu}
A Menu element is a pull down menu, from which you can select a single
element.

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the text before the Menu.
  \item[-textafter] This is the text after the Menu.
  \item[-default] This is the default value for the Menu. This can be
    specified in two ways.
    \begin{enumerate}
      \item The menu entry as text eg. ``first option''.
      \item The index of the menu entry.
    \end{enumerate}
    If an element could be either an index or a menu entry, it is
    considered as an index.(default value if not set: 0)
  \item[-entries] This is a list of entries in the menu.
  \item[-entryhelp] This is a list: {\tt \{"element 1" "help
    for element 1" "element 2" "help for element 2" ...\}}.\\
    If this is given, the {\em -entries} option is ignored.
  \item[-help] This is the help for the Menu.
\end{description}

\subsubsection{Link to Variables}
A Menu links to an associative array with the same name as the Menu,
and with the following keys:
\begin{description}
  \item[name] This is the text which is displayed in the Menu.
  \item[index] This is the index into the list of menu entries.
\end{description}
  
\subsection{ListBox}
\pict{listbox}
A listbox is an element where you can select a number of elements from a
fixed set.

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the title of the ListBox.
  \item[-default] This is a list of default values for the ListBox.
    See Menu above for a description of how to specify these.
  \item[entries] This is a list of entries in the menu.
  \item[-entryhelp] This is a list : {\tt \{"element 1" "help
    for element 1" "element 2" "help for element 2" ...\}}.\\
    If this is given, the {\em -entries} option is ignored.
  \item[-help] This is the help for the Menu.
\end{description}

\subsubsection{Link to Variables}
A ListBox links to an associative array with the same name as the ListBox,
and with the following keys:
\begin{description}
  \item[name] This is a list of the text which is selected.
  \item[index] This is a list of those indexes into the list of entries,
    which are selected.
\end{description}
  
\subsection{TextBox}
\pict{textbox}
This is a textbox for multiline text.

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the title of the TextBox.
  \item[-default] This is the default text.
  \item[-help] This is the help for the TextBox.
\end{description}

\subsubsection{Link to Variables}
TextBox links to a variable with the same name as the TextBox.
  
\subsection{Header}
\pict{header}
This makes a header for a subsection of the configuration page.

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the actual header.
  \item[-help] This is help for the subsection which the header covers.
\end{description}
  
\subsection{Line}
\pict{line}
This is just a line to split the configuration page.
  
\subsection{Frame}
A Frame is just like a frame in Tk. It is used to group things together
side by side, instead of the default, on top of each other. Ie.\ if you
have two ListBox's which you want side by side, then you can use {\em
Frame}

\subsubsection{Standard Options}
\begin{description}
  \item[-entries] This is the element which shall be located in the
    frame
  \item[-orient] This is the orientation which things are pack {\bf in} the
    frame. {\em Note:} This is different from Tk. Ie. if you say {\tt -orient
    left}, things are pack side by side in the frame, and {\tt -orient
    top} means: pack things on top of each other in the frame.(default: left)
  \item[-default] This is the default values to the elements in the frame.
\end{description}

\subsubsection{Link to Variables}
The frame, doesn't link to any variables itself, and the element in
the frame, link to variables, as if they were not in a frame. But
default values have to go through the frame:\\
Ex.:\\
{\tt CheckBox cb1 -text "checkbox 1"\\
Entry e1 -text "Entry 1"\\
Frame f1 -entries cb1 e1 -default \{1 "This is for the entry"\}
}

\subsection{FillOut / FillOutElm}
\label{fillout}
\pict{fillout}
FillOut's are for configuration of strings, which may have some
tokens mixed with some ordinary text, in any order. Eg prompt in the
shell, where the tokens may be the current directory, the username, the
date etc. And the text may be any text you like.

Each token may have some options, which are configured on a
separate configuration page which comes up when the element is selected.

\subsection{FillOutElm}
This is one element in the FillOut listbox. In the example with the
prompt, this might eg. be the ``current working directory''

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the text which is printed in the listbox
  \item[-save] This is a function which generates the part of the string
    this element represents. The result must be generated with the {\em print\/}
    function.(default: print \$name, where \$name refers to the name of
    the FillOutElm)
  \item[-show] This is the string which is shown in the entry. The
    result must be generated with the {\em print\/} function. (default:
    -print \verb!\![\$name\verb!\!], where \$name refers to the name of
    the FillOutElm)
  \item[-entries] If the element has any options, then they might be
    configured as ordinary elements (CheckBox, Entry etc.). This is a
    list of elements which belong to this FillOutElm.
  \item[-help] This is help for the FillOutElm.
  \item[-change] This is a \hyperref{{\em change function\/}}{{\em
    change function\/} (see section }{)}{Change} for the elements which
    are specified with {\em -entries}. 
  \item[-init] This is an \hyperref{{\em Init function\/}}{{\em Init
    function\/} (see section }{)}{Init} for the elements which
    are specified with {\em -entries}.
  \item[-pageEnd] This is a \hyperref{{\em PageEnd function\/}}{{\em
    PageEnd function\/} (see section }{)}{PageEnd} for the elements which
    are specified with {\em -entries}.
\end{description}

\subsubsection{Link to Variables}
The elements specified with {\em -entries\/} links to variables as
usual in the save function (specified with {\em -save\/}),the
show function (specified with {\em -show}), the pageend function
(specified with {\em -pageEnd\/}) and the init function (specified with {\em -init}.)

\subsubsection{Example 1}
First let's see a simple case:\\
\begin{verbatim}
  FillOutElm prompt \
    -text "The current working directory"\
    -show {print <cwd>} \
    -save {print %c} \
    -help "This will expand to the current working directory."
\end{verbatim}
This will put an element in the checkbox with the text {\em The
current working directory}, when that element is selected, the text
{\em $<$cwd$>$\/} will show up in the entry, and finally when the FillOut is
saved, then {\em \%c\/} will be inserted in the final string in the
placed where the listbox element was selected.

\subsubsection{Example 2}
And now for a case, where there are options to the element:
\begin{verbatim}
  CheckBox useTilde \
    -text "Use tilde substitution"
  CheckBox trailing \
    -text "Show only the trailing part of the path"
  CheckBox showSkipped \
    -text "Show number of skipped elements" 
  Int dirs \
    -text "Number of directories to see in the path"

  FillOutElm cwd \
    -text "current working directory" \
    -entries useTilde line1 trailing showSkipped dirs\
    -show {print \[cwd\]}\
    -save {
      if {$trailing} {
        print "[pick $useTidte {%c} {%C}][pick $showSkipped {0} {}]$dirs"
      } else {
        print [pick $useTidte "%~" "%/"]
      }
    } \
    -change {
      if {$trailing} {
        Enable showSkipped dirs
      } else {
        Disable showSkipped dirs
      }
    } 
\end{verbatim}
Here there are four options to the current working directory:
\begin{enumerate}
  \item Use of tilde expansion or not
  \item cut the directory, so only some part of it is shown
  \item show the number of skipped elements if case 2 is selected.
  \item number of directories to show in case 2.
\end{enumerate}
The save function takes care of converting the information from the
selection to the right format.\\
{\em showSkipped\/} and {\em dirs\/} will be disabled if {\em
trailing\/} isn't selected, and  that's what the change function takes
care of.\\
When the FillOut element is selected, the following page will show up:\\\\
\pict{filloutelm}
Here you can configure the four options to the FillOutElm.

\subsection{FillOut}
The FillOut collects all FillOutElm together to \hyperref{a whole
widget}{a whole widget as shown in sec}{}{fillout}
\begin{description}
  \item[-text] This is the title of the fillout
  \item[-entries] This is a list of {\em FillOutElm\/}'s which makes up
    the fillout
  \item[-help] This is general help for the overall fillout
  \item[default] This is the default string, with the following
    syntax:
    \begin{itemize}
      \item elements without options are type like this: {\em
        \%elementname\%}. Ie with percent signs before and after the
        element name.
      \item element with options are type like this : {\em
        \%elementname\%opt1\%opt2\%}. Ie. First a percent sign, then the name,
        then a percent sign, then the first option, a percent sign, next option
        etc, and at last a percent sign.
      \item ordinary text is just typed.
      \item percent signs are escaped with a backslash: {\em \verb!\!\%}.
      \item and finally a backslash is escaped if it is supposed to be
      inserted literally: \verb!\\!
    \end{itemize}
    {\bf Note:} You should always give the default values within a pair of
    braces, otherwise the slashes will be expanded one time to many: {\tt
    -default \{\%elm\%\verb!\!\%\}}
\end{description}

\subsubsection{Example:}
Here's an example which should illustrate the use of {\em FillOut\/}:
\begin{verbatim}
  FillOutElm cwd ...
  FillOutElm user ...
  FillOutElm host ...

  FillOut prompt \
    -text "The user prompt"\
    -entries cwd user date \
    -default {(%user%@%host%) %cwd%} \
    -help "This is the default prompt for the shell..."
\end{verbatim}
Here are three fillOutElm's which is used in the FillOut. The default
value is: first a parenthesis ``(`` then the username, an
``@'', the hostname etc..
    
\subsection{Label}
Label is just a label which can be changed from the {\em change\/}
function, but noy from the interface.

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the text before the label
  \item[-textafter] this is the text after the label
  \item[-default] This is the default value for the label.
  \item[-help] help for the given label
\end{description}

\subsubsection{Link to Variables}
The label cannot be set by the end user, but only be changed in the
{\em Change}, {\em Init} and {\em PageEnd\/} functions. It links to a
variable with the same name as the Label.\\
\hyperref{Here's an example on an}{See section }{ for }{ExtEntry} another use of label.
  
\subsection{ExtEntry}
\label{ExtEntry}
\pict{extentry}
An ExtEntry is an element, which is extendable. It consists of one or
more of the elements above (CheckBox, Entry, Menu ...)

\subsubsection{Standard Options}
\begin{description}
  \item[-text] This is the title for the ExtEntry.
  \item[-help] This is help for the ExtEntry.
  \item[-entries] This is a list of names of elements which the
    ExtEntry consists of.
  \item[-count] This is the number of repeated elements to be shown in the
    ExtEntry.(default: 3)
  \item[-maxentries] This option sets a maximum on the number of
    tuples which might be inserted. This is very usefull together with
    {\em Label\/}. See the example below.(default: infinity)
  \item[-orient] This option takes either {\em left} or {\em top} as an
    argument. It tells in which direction the ExtEntry should be packed.
    If you select left, then the subelements will be packed side by
    side, otherwise they will be packed on top of each other.(default: left)
  \item[-default] This is a list of default values for the elements, each
    element in the list will be one tuple in the ExtEntry.\\
    {\bf Note} that line and header shall not have default values.\\
    EX. ExtEntry ee -entries entry line checkbox -default \{\{text1 1\}
    \{text2 0\}\}\\
    In this example the line is ignored when giving default values.
\end{description}
  
\subsubsection{Link to Variables}
To run through the elements in an ExtEntry, you have to use the command
{\em forevery} which takes two arguments
\begin{enumerate}
  \item The name of the ExtEntry.
  \item A script to be evaluated for every tuple of data.
\end{enumerate}
For each of these tuples the element of the ExtEntry links to
variables like usual. Eg.\ a CheckBox will link to a variable with the
same name as itself etc. {\em Forevery} works recursively ie. if an ExtEntry
is inside  another ExtEntry then you have to do a {\em forevery} on
the outer before you can do it on the inner one. Like this:\\
\begin{verbatim}
  forevery outer {
    forevery inner {
      # here are the variables
    }
  }
\end{verbatim}

\subsubsection{Example with Label and ExtEntry}
\begin{verbatim}
  Label text
  Entry color
  ExtEntry colors \
    -text "Here you can configure three colors" \
    -default {
      {"foreground" ""}
      {"background" ""}
      {"hilight" ""}
    } \
    -maxentries 3
\end{verbatim}
Here we have three elements in the ExtEntry, and no more, they each
have a {\em Label\/} which indicate the color, and it is not posible
to insert extra elements, or change the label (from the endusers point
of view)
  
%%%
%%%
%%% Tk Options
%%%
%%%
\section{Tk options}
All the elements have the possibility to add additional Tk options. 
Eg.\ {\tt -height 5} to tell a ListBox how many elements to show. All
widgets have a default element, eg.\ a CheckBox configures the
checkbutton as default. The other elements (including packing of these)
can be configured with the name as prefix. Eg the packing of the
checkbutton is configured with {\tt -pack:}{\em option value}.

To see a list of options to each Tk element, see the man page for the
element, or try a \htmladdnormallinkfoot{reference
card}{http://www.imada.ou.dk/Technical/Refcards/index.html}

To get some ideas, please refer to the demo module.

In the following you can see how each element can be configured. The
element marked with a star is the default, and therefore needs no
prefix.

\subsection{CheckBox}
\elmTable{
  checkbutton & configures the CheckButton & *\\\hline
  pack & packing of {\em checkbutton\/} &\\\hline
}

\subsection{Radio}
\pict{tk_radio}
\vspace{1cm}
\elmTable{
  frame & configures the frame around the whole Radio &\\\hline
  packFrame & packing of {\em frame\/} &\\\hline
  label & configuration of the title &\\\hline
  packLabel & packing of {\em label\/} &\\\hline
  subFrame & configuration of each subframe &\\\hline
  packSubFrame & packing of {\em subFrame\/} &\\\hline
  radio & configuration of each radio button & *\\\hline
  packRadio &  packing of {\em radio\/} &\\\hline
}

\subsection{Entry}
\pict{tk_entry}
\elmTable{
  frame & configures the frame around the whole Entry &\\\hline
  packFrame & packing of {\em frame\/} &\\\hline
  labelBefore & configures the label before the entry &\\\hline
  frameRight & configures the frame in which the entry and the
    labelAfter are located &\\\hline
  packFrameRight & packing of {\em frameRight\/} &\\\hline
  entry & configures the entry & *\\\hline
  labelAfter & configures the label after the entry &\\\hline
  packLeft & packing of labelBefore &\\\hline
  packRight & packing of frameRight &\\\hline
}

\subsection{Menu}
\pict{tk_menu}
\elmTable{
  frame & configures the frame around all the elements &\\\hline
  packFrame & packing of {\em frame} &\\\hline
  labelBefore & configures the label before the menu& \\\hline
  menubutton & configure the menubutton & *\\\hline
  labelAfter & configure the label after the menu &\\\hline
  packMenubutton & packing of {\em labelBefore} {\em menubutton} and
  {\em labelAfter} into {\em frame} &\\\hline
  menu & this configures the menu. Ie. each element in the dropdown
    menu. &\\\hline
}

\subsection{ListBox}
\pict{tk_listbox}
\elmTable {
  frame & configures the frame around the whole element &\\\hline
  packFrame & packing of {\em frame\/} &\\\hline
  label & configures the title &\\\hline
  packLabel & packing of {\em label\/} &\\\hline
  listboxFrame & configures the frame around the listbox and the
  scrollbar &\\\hline
  packListboxFrame & packing of {\em listboxFrame\/} &\\\hline
  listbox & configures the listbox & *\\\hline
  scrollbar & configures the scrollbar &\\\hline
  packListbox & packing of {\em text\/} and {\em scrollbar\/} in {\em listboxFrame\/}&\\\hline
}

\subsection{TextBox}
\pict{tk_textbox}
\vspace{1cm}
\elmTable{
  frame & configures the frame around the whole element &\\\hline
  packFrame & packing of {\em frame\/} &\\\hline
  label & configures the title &\\\hline
  packLabel & packing of {\em label\/} &\\\hline
  textFrame & configures the frame in which the textbox and the
  scrollbar lies &\\\hline
  packTextFrame & packing of {\em textFrame\/} &\\\hline
  text & configures the tk element {\em text\/} & *\\\hline
  scrollbar & configures the scrollbar &\\\hline
  packText & packing of {\em text\/} and {\em scrollbar\/} in {\em
  textFrame\/} & \\\hline
}

\subsection{Line}
\elmTable {
  frame & configures the frame which makes the line & * \\\hline
  pack  & packing {\em frame\/} & \\\hline
}

\subsection{Header}
\elmTable{
  frame & configures the frame around the whole element &\\\hline
  packFrame & packing {\em frame\/} &\\\hline
  label & configures the label with the title & *\\\hline
  packLabel & packing {\em label\/} &\\\hline
}

\subsection{Label}
\pict{tk_label}
\vspace{1cm}
\elmTable {
  frame & configures the frame around the whole element &\\\hline
  packFrame & packing {\em frame\/} &\\\hline
  labelBefore & configures the label before &\\\hline
  label & configures the label & * \\\hline
  labelAfter & configures the label after &\\\hline
  packLabel & packing of {\em labelBefore}, {\em label\/} and {\em
  labelAfter\/} &\\\hline
}

\subsection{ExtEntry}
\pict{tk_extentry}
\vspace{1cm}
\elmTable{
  frame & configures the frame around the whole element & *\\\hline
  packFrame & packing of {\em frame\/} &\\\hline
  label & configures the title &\\\hline
  packLabel & packing of {\em label\/} &\\\hline
  scrollbar & configures the scrollbar &\\\hline
  packScrollbar & packing of {\em scrollbar\/} &\\\hline
  subFrame & configures each of the subframe &\\\hline
  packSubFrame & packing of each of {\em subFrame\/} &\\\hline
}

\subsection{Frame}
\elmTable {
  frame & configure the {\em frame} & *\\\hline
  packFrame & packing of {\em frame\/} &\\\hline
}

\subsection{FillOut}
\pict{tk_fillout}
\vspace{1cm}
\elmTable{
  frame & configures the frame around the whole element &\\\hline
  packFrame & packing of {\em frame\/} &\\\hline
  label & configures the title &\\\hline
  packLabel & packing {\em label\/} &\\\hline
  entry & configures the entry & * \\\hline
  packEntry & packing {\em entry\/} &\\\hline
  scrollEntry & configures the scrollbar for the entry &\\\hline
  packScrollEntry & packing {\em scrollEntry\/} &\\\hline
  listbox & configures the listbox &\\\hline
  scrollbar & configures the scrollbar & \\\hline
  packListbox & packing {\em listbox\/} and {\em scrollbar\/} &\\\hline
}

%%%
%%%
%%% Enable / Disable
%%%
%%%
\section{The {\em Change}, {\em Init\/} and {\em PageEnd\/} functions}
\label{specialFunc}
You have the possibility to get some commands executed each time
something changes on the menupage (a checkbutton is pressed or released,
a letter is inserted or deleted in a TextBox etc.) This can be used to
force some restrictions on the element, or to disable/enable them due to
the event.  This is done with the {\em Change\/} functions.\\

You also have the possibility to get some commands executed when the
page is entered for the very first time. This can be used to disable
specific elements from the start. This is done with the {\em Init\/}
function \\

You also have the possibility to get some commands executed when the
pages are left or generated. This can be very useful to check eg.\ that
the text in an entry matches a speciel pattern, two checkboxes aren't
checked at the same time etc. This is done with the {\em pageEnd\/}
function.\\

All three functions are called on the menupage just like CheckBox, Entry,
Save etc. They take one argument which is a script to be evaluated on
their specific times.

\subsection{The {\em Change\/} function}
\label{Change}
Each time this script is evaluated the variable {\em changeElm\/} is set
to the name of the element which has been changed. This gives you the
opportunity to evaluate specific code for each element. All variables
which are \hyperref{``visual''}{(see section }{)}{visiable} are linked as
described above.  This function may also be called the very first time
the page is entered. \hyperref{(see also the {\em Init\/} function)}{(see section }{)}{Init}

\subsection{The {\em Init\/} function}
\label{Init}
When the configuration page is visited the very first time, the init script (the
argument to the {\em Init\/} function) is evaluated if it exists. If it
doesn't, the change script will be called with the {{\em changedElm\/}
variable set for each element on the page including each element of
\mbox{ExtEntries}.\\

If the init script exists, the {\em changedElm\/} variable is set to {\tt
init} and the script is evaluated when the pages are visited the first
time.

If there exist any ExtEntries on the page, the init script will be
called each time a new element appears in the ExtEntry, with the {\em
changedElm\/} variable set to the name of the ExtEntry.
\footnote{This is done so it is possible to disable elements in
the ExtEntry as default.}

\subsection{The {\em PageEnd\/} function}
\label{PageEnd}
This function is called each time the page is left or the generate
function is called. If an error is raised a page cannot be
left, and the generation can't be done.

\subsection{Example on Errors}
\begin{verbatim}
  proc AutoModes {} {
    # Errors
    Desc "This is a demo of error handling."
    Entry rexp -text "rexp" \
       -help "regular expression, which start a specific mode"
    Entry mode -text "Mode" -help "mode to start"
    ExtEntry autoModes -entries rexp mode -text "auto-mode-alist" \
    -help "Here you can specify a mode to start, if its filename matches"\
    "the given regular expression"

    PageEnd {
      set line 0
      forevery autoModes {
        incr line
        if {$rexp == "" && $mode == ""} continue
        if {$rexp == "" || $mode == ""} {
          error "Either the rexp or the mode was blank in line $line"
        }
      }
    }
  
    Save {
      forevery autoModes {
        print "a file with regular expression $rexp will start mode $mode"
      }
    }
  }
\end{verbatim}
The PageEnd function ensures that the syntax is correct when the save
function is evaluated.


\subsection{Enable / Disable}
It is possible to enable or disable ``visible'' elements in the {\em
Change\/} function, with the functions {\tt Disable} and {\tt
Enable}. They both take the names of the elements which have to be
disabled/enabled.
{\bf Note\/}: It is possible to disable/enable an extentry, which means
that all the element of the extentry are disabled/enabled.

\subsection{Visual variables}
\label{visiable}
Here are the rules for which elements are visible:
\begin{itemize}
  \item All element which are not in any extentries are always visible
  \item Only one element in an extentry are visible at a time
  \item An extentry only has a visible element if one of its children
    has been selected (including a child of an extentry inside of the
    actual one etc.).
  \item It is possible to make all the element of an extentry visual one
  at a time with the {\em forevery\/} function.
\end{itemize}

This gives the following rules, which you must always obey in the Change
function:
\begin{itemize}
  \item From one tuple in an extentry you may not refer to another tuple
  \item You may never refer down into a sub extentry, but it's ok to
  refer up.
\end{itemize}

\subsection{Example}
Let's try to see the following page:
\begin{verbatim}
  CheckBox cb1 -text cb1
  CheckBox cb2 -text cb2
  CheckBox cb3 -text cb3
  CheckBox cb4 -text cb4
  
  ExtEntry ee1 -entries cb1 -count 2
  ExtEntry ee2 -entries cb2 cb3 ee1 -count 2 \
      -subFrame:bd 1 -subFrame:relief sunken
\end{verbatim}
This looks like this:

\pict{change}

The following is then true:
\begin{itemize}
  \item {\em cb4\/} is always visible
  \item only one of each element in the extentries is visible at a
  time. Ie. both {\em 
    cb2\/}'s can not be visible at the same time (Only one tuple of the
    outer extentry can be visible at a time)
  \item {\em cb2\/} is only visible if it, {\em cb3\/} or one of
    the {\em cb1\/} has been selected.
  \item It's ok to refer to {\em cb2\/} or {\em cb4\/} when {\em cb1\/}
  is the active element, but not to {\em cb1\/} when {\em cb2\/} is the
  active element.
\end{itemize}

The Change function may look like this:
\begin{verbatim}
  switch $changeElm {
    cb4 {
      [pick $cb4 Enable Disable] ee2
    }
    cb2 {
      forevery ee1 {
        set cb1 $cb2  
      }
     }
    cb1 {
      if {$cb1 == 1} {
        set cb3 1
      }
    }
  }
\end{verbatim}
This is a quite complicated function, but let's see what happens for each
element. The switch function selects one of the following based on which
element is the one changed:
\begin{description}
  \item[cb4] If {\em cb4\/} is the changed element, then the following line is
    evaluated: {\tt [pick \$cb4 Enable Disable] ee2}. The first part just
    selects {\tt Enable} if \$cb4 is true and {\tt Disable} if it is
    false. The whole line enables {\em ee2\/} if {\em cb4\/} is
    checked, otherwise it disables {\em ee2\/} (This is an example of how
    you can enable/disable an extentry.)
  \item[cb2] If {\em cb2\/} is selected then all the {\em cb1\/}'s are
    set according to {\em cb2\/} (This is an example of the use of
    {\em forevery\/} in the {\em Change\/} function.)
  \item[cb1] If one of the {\em cb1\/} is checked then {\em cb2\/} is
    also checked. Note: This is ok since I must reference up, but it was
    not ok in the previous, since this would have been a refence down,
    and that's not allowed!
\end{description}

{\bf Note:} This example is included in the demo packages.

%%%
%%%
%%% Save funktion
%%%
%%%
\section{The {\em Save} funktion}
The {\em Save} funktion takes one argument, which is a Tcl script to be
evaluated when the configuration page is saved.

When this script is evaluated, only elements which are not in an
extentry are linked, the others must be accesed with {\em forevery\/}.

\subsection{print}
{\em print} is the most important function in the {\em Save} function. {\em
print} takes a variable number of argument's, and concatenates all its
arguments into one string. This string is then either saved in the
dotfile and/or displayed in the dialog box.

If the first argument to print is {\tt -file} then the next argument
must be a token given in the \hyperref{{\tt setup(dotfile)}
variable}{{\tt setup(dotfile)} variable (see section }{)}{setup}. The
output is then directed to the file specified in the 
{\tt setup(dotfile)} variable.

\subsection{Default Values}
In many cases there exists a default value for different things. In
these cases the user can specify whether he 
wants to generate defaults too or just those things which are different from
the default values.

This has to be programmed in the dotdotfiles, and is done very
easily. A flag called {\em generateDefault} exists, which is 1 if default
values are to be generated, and 0 if not. In the {\em Save\/} function, you
then test whether the object (Checkbox, Entry ...) is in its default state or
not, and whether to generate on default or not. This is done like this:\\
\begin{latexonly}
if \{({\em not default state}) \verb!||! \$generateDefault\} \{\\
\verb!  !{\em generate code for option}\\
\}
\end{latexonly}
\begin{rawhtml}
<pre>
if {(not default state || $saveDefault} {
   save code for option
}
</pre>
\end{rawhtml}

\subsection{Example}
\begin{verbatim}
proc test {} {
  # just a demo
  CheckBox save -text save on exit
  Menu -text number of retries -entries 0 1 2 3 inf -default inf
  Save {
    if {$save || generateDefault} {
      print "(setq save-on-exit $save)"
    }
    if {$number(name) != "inf" || $generateDefault} {
      if {$number(name) == "inf"} {
        print "(setq number-of-retries t)"
      } else {
        print "(setq number-of-reties $number(name))"
      }
    }
  }
}
\end{verbatim}
In this {\em savefunktion}, ``{\bf (setq save-on-exit 0)}'' or ``{\bf
(setq save-on-exit 1)}'' is printed if {\em \$save} if true (ie.\ 1) or {\em
\$generateDefault} is true. This is done because (in this example) the default is ``not to save on exit''. Then
if the user doesn't want default values (\$generateDefault is false) it will
only generate if it is {\bf not} the default value which is chosen (ie.\ to save
on exit.)

The second example is analogous to the first one, in this case the defualt
is {\em inf}, and the variable is an associative array.


%%%
%%%
%%%
%%% Initialization of dotdotfiles.
%%%
%%%
\section{Initialization of dotdotfiles}
The script, which will be generated from the dotdotfile you create
should be called like this:\\
{\tt wish {\em main\_dotdotfile dotfile\_generator\_path module\_path}}

{\em main\_dotdotfile} is the name of the main dotdotfile, which has a
somewhat special syntax, described in the following.\\
{\em dotfile\_generator\_path} is the path for the dotfile generator
files.\\
{\em module\_path} is the path for the module files, ie.\ your
dotdotfiles.

\subsection{The main dotdotfile}
The main dotdotfile is a dotdotfile like any other, the only special thing
about it is that it configures the dotfile generator. You have the following
optional associative arrays, which you can set in this file:

\subsubsection{setup}
\label{setup}
An associative array called {\tt setup} with the following keys:
\begin{description}
  \item[dotfile] This is a list of list, where the index's elements have
  the following meanings:
  \begin{enumerate}
    \item A token to be used in {\em print\/}
    \item A text to be show in the setup menu
    \item The name of the file to connect with this token
    \item Comment character for this file.
  \end{enumerate}
  An example:
  \begin{verbatim}
    set setup(dotfile) {
      {access "Configuration file for access control" access.conf \#}
      {httpd "General configuration file" httpd.conf \#}
      {mime "Mime types'' mime.types \#}
    }
  \end{verbatim}
  \item[print] Boolean flag indicating whether to print on generate.
  \item[file] Boolean flag indicating whether to save to file on generate.
  \item[onePage] Boolean flag indicating whether to generate one page at a
    time or multiple pages.
  \item[generateDefault] Boolean flag indicating whether default shall be
    generated or not.
  \item[saveOnGenerate] Boolean flag indicating whether save shall be
    done on generate.
\end{description}

\vspace{1 cm}

\subsubsection{module}
And in the associative array {\em module}
\begin{description}
  \item[creator] This is your name.
  \item[version] This is the version of your module.
  \item[name] This is the name of the program, which your module
    configures.
  \item[overAllDesc] This is the description, which will be placed at
    the top of the output file. A variable named {\tt commentChar} will
    have the value of the comment character for the specific file. You
    have to insert that yourself at the beginning of each line.
\end{description}

\subsubsection{Special Lines}
Setting the above variables has to be done first in the main dotfile,
and after that you should put this line:\\
{\bf source [lindex \$argv 0]/start}\\
And in the very last line of the main dotdotfile, you write the
following line:\\
{\bf source [lindex \$argv 0]/dotfile.tcl}
The rest of the file is just a dotfile like any other.

\subsection{import}
Dotdotfiles can be split over several files, with the command
{\em import}. {\em Import} tells the dotfile generator that it has to search in
these files for code too. The syntax is very simple:\\
{\bf import {\em filename}}\\
The file will be found in the {\em module\_path}.

{\bf Note} If you want any special utility functions, you need to put
these in separate files, and source them with {\em source}, NOT {\em
import}, since the dotfile generator will search for the {\em \# path}
construction in every procedure it finds in every file which is
imported, but not in files which are sourced. The source command has to
be as follows:\\ {\tt source [lindex \$argv 1]/{\em filename\/}}

%%%
%%%
%%% Help.data
%%%
%%%
\section{Help for the whole module}
You have the opportunity to insert some help which is general to the
whole module in the help page. To do this create a file in your directory,
which you call "help.data", with the following syntax:

\subsection{Syntax of the help file}
Headers are on lines for themselves, and are enclosed in ``[`` and ``]''\\
Things which are in boldface are enclosed in ``$<$'' and ``$>$''\\
Things which are in italic are enclosed in
``\verb!"!`` and ``\verb!"!``\\
The three types may not be mixed, ie. things which are bold cannot be
italic at the same time, and headers can't be italic or bold.

\subsection{Compiling the help file}
To improve performance, the help file must be compiled. This is done with the
following command:\\
{\tt tclsh makeHelp.tcl {\em path}/help.data > {\em
path}/generatedHelp}. Note the file must be called generatedHelp!

%%%
%%%
%%% Examples
%%%
%%%
\section{Examples}
For examples see the files in the {\em demo} directory. These demos
will be started by typing ./config\_demo in the source
directory, or just config\_demo when the Dotfile Generator has been installed.

%%%
%%%
%%% Odds and ends
%%%
%%%
\section{Odds and Ends}
In this section I will itemize some of the caveats of the dotdotfiles.
\begin{itemize}
  \item Procedure names of the configuration pages and elements (like CheckBox)
    may not include double underscore in their names:\\
    wrong: Entry Test\_\_1
  \item You may not enable an element of an ExtEntry which has been
  disabled. 
\end{itemize}

\end{document}
