# How to use this help page

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 configuration page.

## Help page layout

In the following list you'll see the different parts of the help page.

Index list
  In the index list you can see all the section headers in the help text.
Help text
  The help text is of course the box showing the actual help text.
Left and Right arrows
  These two buttons let you travel back and forth in your history list. This is just like you know them from you favorite web browser.
Search String
  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.
Up and Down arrows
  These two arrows will bring you to the previous/next match in your search.

Note: This help file is also available via WWW

# Introduction

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 dotfile without any arguments in your shell.

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 load page, 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 configuration pages. The pages contains the actual configuration options, and when you've configured all to your hearts content, you will generate, which will result in a configuration file for the given program.

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 help region at the button of the configuration page or in the help browser you are looking at.

# Navigating The Dotfile Generator

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.

## The load page

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

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.

You may chose to load only some of the configuration pages or all the pages in the module. To select only some of the pages, click the Details button.

If you came to this page, from the Reload 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 Cancel button at startup.

### The detail page

On the Detail page, you can select which configuration pages to load, reload or reset. For export files you may choose either to merge the existing page with the one shown in the item, or you may overwrite the exiting page, with the one in the item.

Merge means that elements of ExtEntries, will be merged, ie. the elements will be added to the elements of the ExtEntry.

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.

## The configuration page

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 Window widgets.

### Layout

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.

At the bottom of the page you can see which pages will be generated. See the setup menu for the different possibilities.

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.

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 the user manual.

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

## The ExtEntry

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.

### Adding elements

To add a new tuple to an extentry, you have to press the button, which look like this:

This will also locate the new element in the view of the ExtEntry.

### Cut Copy and Paste

The tuples in the ExtEntry may be treated just like they were basic elements. Under the icon which look like this: is located a pull down menu with the following items:

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

### Index element

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.

If an ExtEntry has an index element, a button which look like this:
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.

## FillOut

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

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.

## Window

The configurations on one configuration page, may be located in several windows. This is especially useful, inside ExtEntries.

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

## Command

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:

Color Widget
  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.
Font Widget
  Here you select a font, either by name or by it's basic attributes (font name, font size etc.)
File/Directory Browser
  This is an ordinary browser, which you surely know from other applications.

# Menus

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.

## File

### Generate

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 setup menu. To see how to use the output, please refer to the section below

### Regenerate

To generate a large module may take awhile. This delay will be annoying, if you play around 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!

### Save

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

You can (re)load the save files from the load menu

This format is version dependent (both The Dotfile Generator version and module version). It is however very fast compared to the export format.

### Save As

This will save your configuration to the file you specify.

### Export

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.)

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.

### Reload

This will let you reload/reset one or more configuration pages.

### Quit

This will quit The Dotfile Generator. If you have any unsaved changes, you will be offered to save these.

## Setup

### Options

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

Name of the file(s) to generate to.
  At the top of the setup window you can specify which file(s) to generate to, and the comment character for the given file.
What to generate.
  Next you can select where you want the generated code to go: Either in file(s), in window(s) on the screen, or both.
How much to generate.
  You can specify how many pages you which to generate:
  One page.
    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.
  Selected pages.
    The Dotfile Generator will only generated the pages, which you select. The selection is done at the bottom of the configuration page.
  All pages.
    All the configuration pages are generated.
Generate Defaults?
  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.
Save when Generating.
  When you generate your module, you'll often want to save too. Here you can tell The Dotfile Generator to do this for you automatically.
Place windows.
  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...

### Manage Save/Export Files

This will let you configure the header and description on the save- and export files.

## Mail

You can mail either a suggestion/comment, a bug report, or a postcard from The Dotfile Generator.

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.

## Help

### About

This will bring up a window with version information about The Dotfile Generator and the current module.

### Help Page

This will bring up this help page.

### How to use the output

This is a link into the help page, which the module programmer has written. It should tell you how to use the output from the current module.

# More information

The Dotfile Generator has a home page, which you may wish to check out. A manual on how to write modules for The Dotfile Generator is also available on the net.

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