<h1>How to use this help page</h1>
In the Dotfile Generators help page you will find information
about the Dotfile Generator, and it's behavior. Furthermore the modules may
insert text, which will describe complicated features, which is difficult
to describe on a single <a href="#configpage">configuration page</a>.

<h2>Help page layout</h2>
In the following list you'll see the different parts of the help page.
<dl>
  <dt> Index list
  <dd> In the index list you can see all the section headers in the help text.

  <dt> Help text
  <dd> The help text is of course the box showing the actual help text.

  <dt> Left and Right arrows
  <dd> These two buttons let you travel back and forth in your <i>history
       list</i>. This is just like you know them from you favorite web browser.

  <dt> Search String
  <dd> In the entry at the bottom of the page you can can search for a
       string in the help text. The search is case insensitive and it will
       search from the current position in the help text.

  <dt> Up and Down arrows
  <dd> These two arrows will bring you to the previous/next match in your
       search. 
</dl>


<b>Note</b>: This help file is also available via <a href="http://www.imada.sdu.dk/~blackie/dotfile/help.html">WWW</a>


<h1>Introduction</h1>
The Dotfile Generator is a configuration tool, which let you configure
those awful dotfiles almost every unix program has. For the Dotfile
Generator to configure a given program, it needs a module. To see which
modules are installed on your system, type <i>dotfile</i> without any
arguments in your shell.<p>

To configure a program you will start the Dotfile Generator with the
given module name as argument (as you already did).

This will most likely bring up a <a href="#loadpage">load page</a>, where
you can select a predefined setup to load. When you've selected one, The Dotfile Generator
will show a menu structure, which resembles a directory browser. This menu
structure represent several <a href="#configpage">configuration
pages</a>. The pages contains the actual configuration options, and when
you've configured all to your hearts content, you will <a
href="#menu_generate">generate</a>, which will result in a configuration
file for the given program.<p>

The most important thing to know about The Dotfile Generator is that help
is available all the time, just press the right mouse button over the
element you wish to know more about, and help will
be shown either in the <i>help region</i> at the button of the <a
href="#configpage">configuration page</a> or in the help browser you are
looking at.





<h1><a name="navigating">Navigating The Dotfile Generator</a></h1>

In this section a description can be found on the different elements/pages
of The Dotfile Generator. If you read this continually, please bear in mind
that the help description is written so it is self contained and can be
referenced to from the different pages and menus in The Dotfile Generator.


<h2><a name="loadpage">The load page</a></h2>

The load page, is the one which is shown, when you start The Dotfile
Generator, or when you select <i>Reload</i> in the <i>File</i> menu.<p>

This page lets you (re)load a given setup, either one you have created
yourself, one that came with The Dotfile Generator, or sometimes even the
one which is located in your original dotfile.<p>

You may chose to load only some of the <a href="#configpage">configuration
pages</a> or all the pages in the module. To select only some of the pages,
click the <a href="#load_detail">Details</a> button.<p>

If you came to this page, from the <i>Reload</i> menu, you may also choose
to reset some of the pages, which means that all configuration on the given
page(s) will be deleted. This is equivalent to pressing the <i>Cancel</i>
button at startup.

<h3><a name="load_detail">The detail page</a></h3>

On the Detail page, you can select which <a
href="#configpage">configuration pages</a> to load, reload or reset. For <a
href="#menu_export">export files</a> you may choose either to <i>merge</i>
the existing page with the one shown in the item, or you may
<i>overwrite</i> the exiting page, with the one in the item.<p>

Merge means that elements of <a href="#extentry">ExtEntries</a>, will be
merged, ie. the elements will be added to the elements of the ExtEntry.<p>

Overwrite means that the existing page will be totally overwritten.

Both menu items and configuration pages are shown, and when selecting a
menu item, you will (de)select all the items below this menu item.

<h2><a name="configpage">The configuration page</a></h2>

The configuration pages are the places where you configure your program. Only
one page is visible at a time, though this page may have several <a
href="#window">Window widgets</a>.

<h3>Layout</h3>
In the title bar of the window you can see which page you are configuring,
this is very useful when you travel all the pages of the module.<p>

At the bottom of the page you can see which pages will be generated. See
<a href="#menu_setup">the setup menu</a> for the different possibilities.<p>

Above this, you will see some text. This is the help region. All help for
the configuration page is located there. When you enter the page, general
information about the page is located there. Later when you press the right
mouse button on one of the elements of the page, you will see the help
associated with this element in the help region.<p>

The rest of the page is configuration options. These are built from
entries, check buttons, pull down menus, combo boxes and list boxes. For
further information on these elements, please refer to <a
href="#manuals">the user manual</a>.<p>

There are a few extra elements, however, which are specific for The Dotfile
Generator, and they will be described below.<p>

<h2><a name="extentry">The ExtEntry</a></h2>

The ExtEntry is an element, which repeats other elements several times. It
is used for configurations, which the user may have zero, one or many
of. Your search path in the shell is a good example of this sort of
information. You may have a number of directories, in which the shell may
search for executables.

<h3><a name="extentry_newElm">Adding elements</a></h3>

To add a new tuple to an extentry, you have to press the button, which look
like this: <img src="Generator/bitmaps/new.xbm"><p> This will also locate
the new element in the <i>view</i> of the ExtEntry.<p>

<h3><a name="scissors">Cut Copy and Paste</a></h3>

The tuples in the ExtEntry may be treated just like they were basic
elements. Under the icon which look like this: <img
src="Generator/bitmaps/scissors.xbm"> is located a pull down menu with the
following items:

<dl>
  <dt> Cut
  <dd> This will copy the tuple to the clipboard, and remove it from the
       ExtEntry.
  <dt> Copy
  <dd> This will copy the tuple to the clipboard, and leave it in the ExtEntry.
  <dt> Paste
  <dd> This will copy the tuple from the clipboard into the ExtEntry, just
       before the one in which the scissors was invoked.
  <dt> Insert Blank
  <dd> This will insert an <i>empty</i> tuple, just before the one in which
       the scissors was invoked.
</dl>

<h3><a name="extentry_index">Index element</a></h3>

An ExtEntry may be arbitraryly big, by that reason some of them have an index
element. This index element is used to travel to an other tuple in the
ExtEntry, without having to scroll all the way to it.<p>

If an ExtEntry has an index element, a button which look like this: <img
src="Generator/bitmaps/idx.xbm"><br> is located next to it. If you press
this button a listbox will show up, and in it you can select the index
element associated with the tuple you want to go to. When you've selected
one, The Dotfile Generator will scroll the ExtEntry to this tuple.


<h2>FillOut</h2>
The FillOut widget is used to <i>type</i> some text, which is built from
tokens and ordinary text. An example of this is the prompt in your shell.<p>

It is composed by a listbox and an entry. In the entry you can type
ordinary text and insert tokens from the listbox within this text. The
elements of the listbox may either be a basic token, or may be a
configurable one. The configuration is, of course, done with basic Dotfile
Generator widgets.

<h2><a name="window">Window</a></h2>

The configurations on one configuration page, may be located in several
windows. This is especially useful, inside <a
href="#extentry">ExtEntries</a>.<p>

A window widget is just a button, which brings up the window when it's
pressed.

<h2><a name="command">Command</a></h2>

In addition to The Dotfile Generator's standard widget, there may be added
some additional widgets, which all bring up a configuration page. At this
moment the following widgets exists:

<dl>
  <dt> Color Widget
  <dd> This widget will let you select a color, either by name or by
       dragging three scales representing the three basic colors: red,
       green and blue.
  <dt> Font Widget
  <dd> Here you select a font, either by name or by it's basic attributes
       (font name, font size etc.)
  <dt> File/Directory Browser
  <dd> This is an ordinary browser, which you surely know from other
       applications. 
</dl>


<h1><a name="menus"></a>Menus</h1>
At the top of the main window, there is located three pull down menus. These
contain links to different actions, configuration pages and help pages. The
menus may be torn off, which is done by selecting the dashes at the top of
the pull down menu.

<h2><a name="menu_file">File</a></h2>

<h3><a name="menu_generate">Generate</a></h3>

This is the most important function in The Dotfile Generator. This is the
one which converts your configurations to the code of the program you are
configuring. The code will be shown in a window and written to
file(s). This can however be configured in the <a href="#menu_setup">setup
menu</a>. To see how to use the output, please refer to <a
href="#howToUse">the section below</a>

<h3><a name="menu_regenerate">Regenerate</a></h3>

To generate a large module may take awhile. This delay will be
annoying, if you <i>play around</i> with the different options on a page. To
avoid this, you can regenerate the single page you are working on, and let
the other part of the configuration file be. To do this you have to
generate the whole module first!

<h3><a name="menu_save">Save</a></h3>

This will save your configuration in a file, which lets you continue your
configuration in a later Dotfile Generator session.<p>

You can (re)load the save files from the <a href="#loadpage">load menu</a><p>

This format is version dependent (both The Dotfile Generator version and
module version). It is however very fast compared to the <a
href="#menu_export">export format</a>.

<h3><a name="menu_saveas">Save As</a></h3>
This will <a href="#menu_save">save</a> your configuration to the file you
specify.

<h3><a name="menu_export">Export</a></h3>
This will export your configuration to an export format. This format is
version independent. However it is very slow to import from. So this format
should only be used, if you want to upgrade your Dotfile Generator, or give
your configuration to someone who uses The Dotfile Generator. (ver 2.0 or
later.)<p>

The export format is also used if the module has a filter, which can
convert from the original dotfile to configuration in The Dotfile Generator.

<h3><a name="menu_reload">Reload</a></h3>
This will let you <a href="#loadpage">reload</a>/reset one or more <a
href="#configpage">configuration pages</a>.

<h3><a name="menu_quit">Quit</a></h3>
This will quit The Dotfile Generator. If you have any unsaved changes, you
will be offered to save these.

<h2><a name="menu_setup">Setup</a></h2>
<h3><a name="menu_options">Options</a></h3>

In the options menu you can configure how The Dotfile Generator behaves. It
contains the following options:

<dl>
  <dt> Name of the file(s) to generate to.
  <dd> At the top of the setup window you can specify which file(s) to
       generate to, and the comment character for the given file.

  <dt> What to generate.
  <dd> Next you can select where you want the generated code to go:
       Either in file(s), in window(s) on the screen, or both.
  <dt> How much to generate.
  <dd> You can specify how many pages you which to generate:
       <dl>
         <dt> One page.
         <dd> The Dotfile Generator will only generate the current visible
	      configuration page. This is useful, if you experiment with
	      The Dotfile Generator, to see what it generates for the
	      different widgets.
         <dt> Selected pages.
         <dd> The Dotfile Generator will only generated the pages, which
	      you select. The selection is done at the bottom of the <a
              href="#configpage">configuration page</a>.
         <dt> All pages.
         <dd> All the configuration pages are generated.
       </dl>
  <dt> Generate Defaults?
  <dd> Some of the programs configured by The Dotfile Generator has default
       values, which is set when the option is not specified at all in the
       configuration file. If you append the output from The Dotfile
       Generator to the original configuration file, then this is useful
       to ensure that the settings in The Dotfile Generator will overwrite
       the original, which may be located in your configuration file.
  <dt> Save when Generating.
  <dd> When you generate your module, you'll often want to <a
       href="#menu_save">save</a> too. Here you can tell The Dotfile
       Generator to do this for you automatically.
  <dt> Place windows.
  <dd> If your window manager asks you to place the windows, you may tell
       The Dotfile Generator that it shall place them for you. This may be
       useful...
</dl>

<h3><a name="menu_manage">Manage Save/Export Files</a></h3>
This will let you configure the header and description on the save- and
export files.

<h2><a name="menu_mail">Mail</a></h2>
You can mail either a suggestion/comment, a bug report, or a postcard from
The Dotfile Generator.<p>

The postcard is only for encouraging the programmers to make their job even
better, after all... if no one is using our product, we may not want to
spend so much time on it.


<h2><a name="menu_help">Help</a></h2>
<h3><a name="menu_about">About</a></h3>
This will bring up a window with version information about The Dotfile
Generator and the current module.

<h3><a name="menu_helppage">Help Page</a></h3>
This will bring up this help page.

<h3><a name="menu_howToUse">How to use the output</a></h3>
This is a <a href="#howToUse">link</a> into the help page, which the module
programmer has written. It should tell you how to use the output from the
current module.



<h1><a name="manuals">More information</a></h1>
The Dotfile Generator has a <a
href="http://www.imada.sdu.dk/~blackie/dotfile">home page</a>, which you may
wish to check out. A <a
href="http://www.imada.sdu.dk/~blackie/dotfile/dotdotfiles/">manual on how
to write modules</a> for The Dotfile Generator is also available on the
net.<p>

A mailing list exists for The Dotfile Generator. You may subscribe by
sending a mail to dotfile-request@imada.sdu.dk with the <b>subject</b>
subscribe. To unsubscribe, let the subject be unsubscribe.