<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" 
[
<!ENTITY % progeny-entity SYSTEM "../doctools/progeny.ent">
%progeny-entity;
]>

<!-- $Progeny: configlets-druid.refentry,v 1.7 2002/02/12 16:44:36 epg Exp $ -->

<refentry>
  <refentryinfo>
    <authorgroup>
      <author>
        <firstname>John</firstname>
        <othername role="mi">R.</othername>
        <surname>Daily</surname>
      </author>
    </authorgroup>
    <copyright>
      <year>2002</year>
      <year>2001</year>
      <holder>Progeny Linux Systems, Inc.</holder>
    </copyright>
    <date>2002-01-11</date>
  </refentryinfo>

  <refmeta>
    <refentrytitle>CONFIGLETS-DRUID</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>configlets-druid</refname>
    <refpurpose>&gnome; front end to run configlets in a wizard-like
    manner.</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>configlets-druid</command>
      <group choice="opt">
        <arg>--ask-only</arg>
        <arg>--commit-only</arg>
      </group>
      <arg choice="opt"><replaceable>configlet_dir</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      <command>configlets-druid</command> is a &gnome; front end to
      installed configlets.  It provides a druid interface to them,
      where each appears in a window with a Back and Next button to
      choose between them.
    </para> 

    <para>
      After the initial welcoming screen, the druid shows a list of
      the configlets that will be displayed, along with short
      descriptions of each.  Next to each configlet's name is a check
      box that is checked by default (but see below for information on
      configuring this); the user may check or uncheck any of the
      configlets shown.  The next screen after this is the first
      configlet in the list that was checked; the rest of the screens
      consist of the rest of the checked configlets, followed by a
      wrap-up screen.  If the user uses Back to return to the list and
      selects a different set of configlets, the newly checked list
      will be displayed when the user clicks Next to proceed.
    </para>

    <para>
      See
      <filename>/usr/share/doc/python-configlets/book/book.html</filename>
      or <literal>http://hackers.progeny.com/configlets/</literal> for
      more information.
    </para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>
    <variablelist>
      <varlistentry>
        <term><option>--ask-only</option></term>
        <listitem>
          <para>
            Run the druid, but do not commit any changes to &debconf; until
            later, when run with <option>--commit-only</option>. Intended
            for use by <application>apt</application>-like tools.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>--commit-only</option></term>
        <listitem>
          <para>
            Save earlier recorded values to &debconf;.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><replaceable>configlet_dir</replaceable></term>
        <listitem>
          <para>
            Location for installed configlets. Defaults to
            <filename>/usr/share/configlets/</filename>.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>CONFIGURATION</title>

    <para>
    <command>configlets-druid</command> can use a configuration file,
    located at <filename>/etc/configlets-druid.cfg</filename>.  This
    file can contain blank lines and comment lines that start with a
    '#' character (which are ignored) and item-value pairs, one per
    line, with whitespace separating the item and value.  (The value
    can contain whitespace.)  For some items, no value is necessary;
    in those cases, it can be omitted.
    </para>

    <para>
    The following configuration items are recognized:
    </para>

    <variablelist>

      <varlistentry>
        <term><option>cancelable</option></term>
	<listitem>
	  <para>
	  Turn on the Cancel button on the druid.  The default is to
	  turn the Cancel button off.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>debug</option></term>
	<listitem>
	  <para>
	  Cause the druid and the configlets to print large amounts of
	  debugging information to standard error.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>dont_show_required_configlets</option></term>
	<listitem>
	  <para>
	  If a configlet is listed as required (see the
	  <option>required_configlets</option> item below), then it is
	  displayed with "(mandatory)" added to its description, and
	  its checkbox cannot be unchecked.  If this item is
	  specified, then required configlets will not be shown in the
	  first screen at all.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>gtkrc</option></term>
	<listitem>
	  <para>
	  Provides a path to a custom gtkrc for the druid.  By
	  default, the gtkrc from the Raleigh theme is used if
	  available, or no gtkrc if it is not.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>logo</option></term>
	<listitem>
	  <para>
	  Provides the path to the logo to load into the druid's logo
	  space.  If not specified, this defaults to a Debian logo.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>omit_configlets</option></term>
	<listitem>
	  <para>
	  Configlets whose names appear in this space-separated list
	  are omitted from the druid entirely and are not shown.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>required_configlets</option></term>
	<listitem>
	  <para>
	  Configlets whose names appear in this space-separated list
	  are considered "required".  This means that they are
	  displayed with "(mandatory)" added to their descriptions,
	  and their check boxes are checked and set insensitive (so
	  that the user cannot uncheck the box).
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>show_only_listed_configlets</option></term>
	<listitem>
	  <para>
	  By default, the druid loads and shows all of the configlets
	  it finds, subject to exceptions.  If this item is given,
	  only configlets explicitly mentioned in the configuration
	  file are loaded and shown.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>standard_configlets</option></term>
	<listitem>
	  <para>
	  This item is ignored unless
	  <option>show_only_listed_configlets</option> is also given.
	  In that case, it consists of a space-separated list of
	  configlets that are to be shown in the normal way.
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>unchecked_configlets</option></term>
	<listitem>
	  <para>
	  Configlets whose names appear in this space-separated list
	  are displayed with their check boxes unchecked by default.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1>
    <title>FILES</title>

    <variablelist>
      <varlistentry>
        <term><filename>/usr/share/configlets</filename></term>
        <listitem>
          <para>
	  The location from which all configlets are loaded.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><filename>/etc/configlets-druid.cfg</filename></term>
        <listitem>
          <para>
	  The configuration file.
	  </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>AUTHORS</title>

    <para>
      Jeff Licquia &lt;<email>jlicquia@progeny.com</email>&gt;
    </para>
    <para>
      Eric Gillespie, Jr. &lt;<email>epg@progeny.com</email>&gt;
    </para>
  </refsect1>
</refentry>