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


%
% macro's
%
\newcommand{\pict}[1]{
  \centerline{\hbox{\psfig{figure=#1.ps}}}
  \html{\\\\}
}

%
%
% What is the Dotfile Generator
%
%
\section{What is the Dotfile Generator}
The Dotfile Generator is a program with which you
can write those terrible run code files almost every program 
has (like .tcshrc .emacs etc.). It's not a program which knows about
every program in the world, but a program which has to be `taught' by a
human. Ie. someone has to make a module for it, for the specific
program in mind. So far modules exist for emacs, tcsh (a shell),
fvwm (An X window manager), and soon modules will be created for bash
(the Bourne again shell), and NCSA's WWW server.\\

This document describe the use of the Dotfile Generator, for information
about writing the modules, please refer to the
\htmladdnormallinkfoot{dotdotfile document}{http://www.imada.ou.dk/\~{}blackie/dotfile/dotdotfiles/dotdotfiles.html}.\\

Your configuration process consists of checking check buttons, filling out
entries and selecting elements from pull down menus and list boxes.

%
%
% Online help
%
%
\section{Online help}
All the way there is help for each element, which tells you what the
specific check button, entry etc.\ means. Let's see an example:\\

\pict{userex1}

If you click with the right mouse buttons on this check button, then the
following help text will show up:

{\tt If this option is set, the shell tells you, that a job is finished at
once, otherwise it will wait until the next prompt is shown.}

%
%
% A guided tour
%
%
\section{A guided tour}
This section will take you by the hand and show you how to use the
Dotfile Generator. This will be done with the tcsh module as an example,
but it is not a must that you use tcsh. If you do\ldots well then you're on
your way to configuring it, and if you don't, hopefully you will learn how
to use the Dotfile Generator.

Start with opening the tcsh module. This is done by typing config\_tcsh
if it is installed on your system, and ./config\_tcsh in the directory
containing the Dotfile Generator, if it's not installed. Now you should
get a page like this:

\pict{tour1}

\subsection{Menus}

This is the menu where you can navigate through the different
configuration pages. The six buttons at the bottom will be described
later.

Those buttons with an arrow at the and (-\ -$>$) are references to sub
menus, and those without are references to configuration pages.
Think of it as a directory structure, where you
can have subdirectories which have files and other subdirectories.

First let's try to traverse parts of the menu structure. Press the button labeled
{\tt prompt-\ -$>$}, you should now get a page which looks like this:

\pict{tour2}

On this page there are only references to configuration pages, (the
directory tree is no deeper) and a reference back (like {\tt ..} in the
directory case). Try the reference back.

Now you should be back to the page we started out with.

\subsection{Configuration Pages}
Now it's time to bring up a configuration page. Press the button labeled
{\tt files}, you should now get a Page like this:

\pict{tour3}

On this page you can configure different things about files in
tcsh. Lets try to understand the page, and lets start from the top.

The first thing we see is the name of the configuration page.

\pict{tour4}

This one is called /files. This is actually only the menus we had
traversed to get to this page, including the name of the page. This is
similar to a path name.

Before we continue down the page please note that at the bottom there is a
short description of the overall page:

\pict{tour6}

This box is the standard location for all help along the way.

The next one is a header, it is only included to make the page more
readable, and to allow specific help for some portion of the page.

\pict{tour5}

If you click with the right mouse button on the header you will get the
following help text in the {\em help window\/}:

\pict{tour7}

And now for the configuration part:
First there is a check button, where you can tell whether you want your
output sorted horizontally or not (means vertically). Again try to get the
help which is available for the check button, by pressing the right
mouse button.

As you can see some of the check buttons are selected from the start and
some are deselected. This has been done by the  module programmer, to
give you a smart default start, so if there is some option you don't
know what means or you can't see what would be the smartest then you can
just let it be, and in that way use the dotfile programmer's default
selection.

Now select things the way you want it on the pages.

To save this page we have to select it for saving, this is done
by selecting the radio button {\tt Will be saved} at the bottom of the page.

Toggling from {\tt Will be saved} to {\tt Will not be saved} can be done
with {\tt M-s}.

Now go to the other window (the one we started out with) and find the
button called {\tt Generate} and press it. A new window will now appear.
This is the window with the information for your .tcshrc file. Let's see
what is says:

The first three lines says something like this:

\begin{verbatim}
### This file has been auto generated
### by the tcsh module for the Dotfile Generator
### on Wed Aug  2 11:09:20 MET DST 1995
\end{verbatim}

This is simply a header which tells that the following has been  auto generated
and should not be edited by hand, but only with the Dotfile Generator.

The next nonempty line says:
\begin{verbatim}
### configuration of files
\end{verbatim}
This is the title for the actual configuration page we've just edited,
when more pages are saved simultaneously you will see more titles like this
one.

And finally the tcsh code which configures tcsh just the way you told
on the configuration page. If you count you will see that there are as
many lines as there are options on the configuration page. The reason why
this is so is that every option is generated. Even things, which are the
default if nothing is done, will be generated. This might not be that smart
since this will result in hundreds of lines when all options is generated,
so let us tell the Dotfile Generator only to generate those options which
are not default to tcsh.

\subsection{Save default values}
First destroy the output window by pressing the {\tt OK} button. Then
press the {\tt Setup} button in our first window, the menu window. A
window should now appear which looks like this:

\pict{tour8}

deselect the check button which says {\tt Generate default too}, and press
the {\tt OK} button. The window will disappear again. Now generate the
configuration page, by pressing the {\tt Generate} button, or pressing {\tt
Ctrl-s}. Unless you've been that (un)lucky to select everything as the
``not default'' value, you will see that some of the options have
disappeared. Try to change some of the options and select generate, a couple
of times so you can see how the options appear/disappears.
And finally remove the output window with a press on the {\tt OK} button.

\subsection{Saving of internal states}
Now you might be interested in leaving the Dotfile Generator, but before
you do that, you have to save the options you've selected. If you do
that, you might continue your work on configuring tcsh when you come
back and start the Dotfile Generator the next time. If you don't you
have to start all over again. To save just press the {\tt Save}
button on the menu page. And now you may exit the Dotfile Generator
which you do by pressing the {\em QUIT\/} button.

\subsection{Next session}
Please start the Dotfile Generator again. Now it will ask you whether you
want to load the file you just saved. Please answer {\tt YES} to
this answer. Now select the {\tt files} button again, and verify that
all the elements are selected just the way you did it.

Now we're almost through with this little demonstration of the Dotfile
Generator, the only thing there's left is the configuration of the
Dotfile Generator.

\subsection{Configuration of the Dotfile Generator}
Select the {\tt Setup} button, which will bring up the configuration
page for the Dotfile Generator.

The first option tells the Dotfile Generator which file to generate
information to. Try to list the files in your current directory and you
will find a file of this name.

The next is the character(s) which will be appear in front of comment
in the output which is written from the Dotfile Generator, like {\tt
\#\#\# configuration of files}

Then there is two check buttons which tell where to write output:
\begin{enumerate}
  \item to the file named above
  \item to the screen as we saw earlier
\end{enumerate}

Then there is the configuration of default values as already mentioned.

If you select {\tt Just generate one page at a time}, only the actual page
(the one which is on the screen) will be generated, and none of the
others. This is useful if you just want to see how an option is generated,
let's try that. Select the check button and press the {\tt OK} button.
Now go to the page called {\tt logout}. Now you will see that the radio
buttons at the bottom of the page has disappeared, and changed to a label
saying, {\tt Only this page will be generated}

And if you select {\tt Generate} you will see that the only thing which is
generated is this page, and not the {\tt files} page, which you've already
configured, and chosen {\tt Save this page} on.

Now open the setup window again, so we can finish it.
If the last check button is selected, save is done each time you
generate a page. This is very useful, in case your system (or the Dotfile
Generator) should crash, so you at least have a save file from the
last generate.

\subsection{Before you continue}
Before you continue using the Dotfile Generator it might be a good idea
to read the rest of this manual, so you can learn what the different
widgets look like, and how they works.

%
%
% Widgets
%
%
\section{Widgets}
Now let's see what the different widgets looks like.

%%% checkbuttons
\subsection{check buttons}
A check button has two states, selected or deselected. This
is typically used for Yes/No questions or ``I want/I don't want''
questions. You can see below what it looks like in its two states. The
first one is selected, and the second is deselected.\\

\pict{userex1}
\pict{userex2}

%
%%% entries
%
\subsection{entries}
An entry is used to answer question like ``how many seconds between
backups'', ``what is your email address'' or ``where is your mail file
located''. It looks like this:\\

\pict{userex3}

There exist three different kinds of entries:
\begin{description}
  \item[The general entry] This entry is for all kinds of text
  \item[Integers only] This entry is only for integers
  \item[Floating point numbers only] This entry is only for floating
    point numbers
\end{description}
If you type eg. a letter in an entry for integers, a dialog box will
show up with an error message:\\

\pict{userex4}

This is a general error box, so in this case you just press the {\tt OK}
button, in other cases where this error box appear it is up to you to
decide whether it is an controlled error message from the program to you,
or it's a bug in the program. If it is a bug please send a
\htmladdnormallinkfoot{bug
report}{http://www.imada.ou.dk/\~{}blackie/dotfile/bugs.html} with the
stack trace which you get when you press the button {\tt Stack Trace}


%
%%% menu
%
\subsection{menu}
A menu is for selecting precisely one element from a fixed set. It is used
for questions like: ``Make numbered backup'' with possible answers:
``Always, Only if the files already have numbered backup, Never, just
single''. It looks like this:\\

\pict{userex5}

When you the click on the button (the text which says ``Never just
single'', the following box will shown up, which gives you the
possibility to select another element:\\

\pict{userex6}

If you activate the menu with the right mouse button instead of the left
one, and select an element, then help is show for that particular
element.

%
%%% radiobuttons
%
\subsection{radio buttons}
Radio buttons are almost like menus: precisely one element must be selected
at a time. The only difference is that the radio button shows all the
possibilities at once. It looks like this:\\

\pict{userex7}

The general help for the overall element is found by clicking the right
mouse button on the header, and specific help for each element is found
by clicking the right mouse button on the particular entry.

%
%%% listbox
%
\subsection{list box}
A list box is for selecting one or more elements from a fixed
set. In the list box you can often see a bunch of elements, but not
always all the elements. The list box can be configured so that you can
only select one element at a time, or so that you can select several
elements at a time. To select more than one element, hold down the
control key, and select with the left mouse button. A list box looks like
this:\\

\pict{userex8}

Help for the overall list box is found on the header, while help for each
element is found on them.

%
%%% textbox
%
\subsection{text box}
A text box is for multi line text, like your full address, or commands to
execute after each prompt. The scroll bar on the right side lets you move
up and down through all the elements. It looks like this:\\

\pict{userex9}

%
%%% fillout
%
\subsection{fillout}
A fillout element is a specified entry, where you can insert special
tokens. This might be a prompt where you can insert normal text, and
specified tokens which will expand to eg. the current working directory,
the user name or the time of the day. It looks like this:\\

\pict{userex10}

On the top is the entry, where you can type your normal text, and move
the cursor around. Next there is a scroll bar to scroll the entry. And
last is a list of tokens to insert. If you eg. select ``current
working directory'' the token ``[cwd]'' will be inserted in the
entry.\\

If you move the cursor in the entry each token will be treated like a
single char, ie. if you move to the left of the right end of
``[cwd]'', the cursor will move all the way past it to the left end. If
you click with the left mouse button on a token in the entry, you have
the possibility to configure it, if it is configurable.\\

Help is available for the overall fillout element on the title and on
the entry. Specific help is available for each element in the list.

%
%%% extentry
%
\subsection{extentry}
An extentry (pronounced extended entry) is for elements which might consist
of more than one element. In the following we present some examples
to show what this means.

\subsubsection{example 1}
The path in the shell consists of several directories in which the shell
will  search for programs. This might look like this:\\

\pict{userex11}

This extentry consists of one entry which is repeated three times on the
screen, and as many times you want with the scroll bar.

\subsubsection{example 2}
In the previous example only one element was repeated in the extentry,
here's an example, where two elements are repeated:\\

\pict{userex12}

One pair of user name and tty is called a tuple. You can get as many
tuples as you want by clicking down on the scroll bar on the right side.
Each time you reach the bottom, an extra empty element will appear.\\ 

An extentry may consist of any number of elements, selected from the above,
even of extentries.

\subsubsection{example 3}
The last example is included to avoid a common misunderstanding with
extentries:\\

\pict{userex13}

This extentry consists of four elements which are on top of each
other instead of side by side as in the previous example. This
extentry only shows {\em one\/} element, where the two others each showed three
elements!\\

It is very important that you can see how this works. In the previous two
examples each element will move one location up when the scroll bar is
scrolled down, the element at the top will be scrolled out of the page,
and a new one will appear at the bottom. This is exactly the same in
this example, the only difference is that only one tuple is visible,
so it will scroll out, and a new one will scroll in. The reason why only
one element is visible is that it would be to large on the screen to
show even two.

%
%
%%% Disable / Enable
%
%
\section{Disable /Enable}
Some elements might depend on each other. For that reason it is possible
in the Dotfile Generator to disable some elements. When an element is
disabled it is totally dead, which means that nothing at all works for it.

\end{document}
