debian_debian-policy/debconf_spec/include/commands.xml

<listitem id="command_version">
  <para>
    VERSION
    <parameter>number</parameter>
  </para>
  <para>
    This exchanges with the frontend the protocol version
    number that is being used. The current version is
    2.1. Versions in the 2.x series will be
    backwards-compatible. You may specify the protocol version
    number you are speaking. The frontend will return the version
    of the protocol it speaks. If the version you specify is too
    low, this command will return the numeric return code
    <literal>30</literal>.
  </para>
</listitem>
<listitem id="command_capb">
  <para>
    CAPB
    <parameter>capabilities</parameter>
  </para>
  <para>
    This exchanges with the frontend a list of supported capabilities
    Capabilities both the frontend and your confmodule support may be
    used; the capabilities supported by the frontend are returned by
    this command.
    <table frame="all">
      <title>Currently used capabilities</title>
      <tgroup cols="2">
      <thead>
        <row>
          <entry>capability</entry>
	  <entry>description</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>backup</entry>
 	  <entry>
	    Backing up to a previous step is supported.
	  </entry>
        </row>
	<row>
	  <entry>escape</entry>
	  <entry>
	    The frontend expects commands sent to it to have backslashes and
	    newlines quoted as <literal>\\</literal> and <literal>\n</literal>
	    respectively and will in turn quote backslashes and newlines in its
	    replies.  See <citerefentry><refentrytitle>debconf-escape</refentrytitle>
	    <manvolnum>1</manvolnum></citerefentry>.
	  </entry>
	</row>
	<row>
	  <entry>multiselect</entry>
	  <entry>
	    The multiselect data type is supported. You do not need to
	    check this capability if you depend on any modern version
	    of debconf.
	  </entry>
	</row>
      </tbody>
      </tgroup>
    </table>
  </para>
</listitem>
<listitem id="command_settitle">
  <para>
    SETTITLE
    <parameter>template</parameter>
  </para>
  <para>
    You can use this command to set a title in the
    frontend. This may appear in different ways, depending on the
    frontend being used, for example it might change the title
    of the frontend's window. If you don't specify anything, a
    title will automatically be generated.
  </para>
  <para>
    Using a template has the advantage that titles are translatable
    and that they can be maintained in the same place as other text
    displayed to users.
  </para> 
</listitem>
<listitem id="command_title">
  <para>
    TITLE
    <parameter>string</parameter>
  </para>
  <para>
    Similar to SETTITLE, but takes a string instead of a template as
    parameter. Consequence is that the title will not be translatable,
    unless some other mechanism (like gettext) is used.
  </para>
</listitem>
<listitem id="command_stop">
  <para>
    STOP
  </para>
  <para>
    This command tells the frontend you're done talking to it. Typically
    the frontend can detect the termination of your program and this
    command is not necessary.
  </para>
</listitem>
<listitem id="command_input">
  <para>
    INPUT
    <parameter>priority</parameter>
    <parameter>question</parameter>
  </para>
  <para>
    This tells the frontend to display a question (or other type of
    item) to the user. <parameter>question</parameter> is the name of the
    item to display, all other information about the item is retrieved
    from the templates described previously.
    <parameter>priority</parameter> is how important it is that the
    user be prompted. The frontend need only ask this question if the
    priority is high enough. The question is not displayed until a go
    command is given. This allows us to ask multiple questions in a single
    screen. Once a question has been displayed to the user and the user has
    provided input, the frontend will set the
    <literal>seen</literal> flag.
    &priority_table;
  </para>
  <para>
    Note that the frontend decides if the user is actually
    prompted or not. If the user has already answered a
    question, they are normally not asked it again even if
    input is called again. And if the user is ignoring low
    priority items, they will not see them. In either of
    these cases, this command returns the numeric return code
    <literal>30</literal>.
  </para>
</listitem>
<listitem id="command_beginblock">
  <para>
    BEGINBLOCK
  </para>
</listitem>
<listitem id="command_endblock">
  <para>
    ENDBLOCK
  </para>
  <para>
    Some frontends are able to display a number of items to
    the user at once. To do this, they need to be given blocks
    of input commands, enclosed in the BEGINBLOCK and ENDBLOCK
    commands. Blocks can be nested and very advanced frontends
    may use this as a user interface hint.
  </para>
  <note>
    <para>
      There is an implicit block around any set of INPUT commands
      that are not enclosed in an explicit block.
    </para>
  </note>
</listitem>
<listitem id="command_go">
  <para>
    GO
  </para>
  <para>
    Shows the current set of accumulated items to the user and lets
    them fill in values, etc. If the backup capability is supported
    and the user indicates they want to back up a step, this command
    returns the numeric return code <literal>30</literal>.
  </para>
</listitem>
<listitem id="command_clear">
  <para>
    CLEAR
  </para>
  <para>
    Clears the accumulated set of INPUT commands without displaying
    them to the user.
  </para>
</listitem>
<listitem id="command_get">
  <para>
    GET <parameter>question</parameter>
  </para>
  <para>
    Ask the frontend to tell you how the user answered a question. The
    value is returned to you.
  </para>
</listitem>
<listitem id="command_set">
  <para>
    SET
    <parameter>question</parameter>
    <parameter>value</parameter>
  </para>
  <para>
    Set the answer of a question to a value.
  </para>
</listitem>
<listitem id="command_reset">
  <para>
    RESET <parameter>question</parameter>
  </para>
  <para>
    Reset the question to its default value. This includes
    resetting flags to their defaults.
  </para>
</listitem>
<listitem id="command_subst">
  <para>
      SUBST
      <parameter>question</parameter>
      <parameter>key</parameter>
      <parameter>value</parameter>
  </para>
  <para>
    Questions (and other items) can have substitutions embedded in
    their descriptions (and, currently in their choices fields). These
    substitutions look like "<literal>${key}</literal>". When the
    question is displayed, the substitutions are replaced with their
    values. This command can be used to set the value of a
    substitution.
  </para>
</listitem>
<listitem id="command_fget">
  <para>
    FGET
    <parameter>question</parameter>
    <parameter>flag</parameter>
  </para>
  <para>
    Questions (and other items) can have flags associated with them. The
    flags have a value of "<literal>true</literal>" or
    "<literal>false</literal>". This command returns
    the value of a flag.
  </para>
</listitem>
<listitem id="command_fset">
  <para>
    FSET
    <parameter>question</parameter>
    <parameter>flag</parameter>
    <parameter>value</parameter>
  </para>
  <para>
    This sets the state of a flag on a question. Valid
    states for the flag are "<literal>true</literal>" and
    "<literal>false</literal>".
  </para>
  <para>
    One common flag is the
    "<literal>seen</literal>" flag. It is normally only set if
    a user already seen a question.
    Typically, frontends only display questions to users if they have the
    seen flag set to "false". Sometimes you want the user to see a
    question again -- in these cases you can set the seen flag to
    false to force the frontend to redisplay it.
  </para>
  <para>
    Note that as a special convenience behavior, frontends will
    redisplay already seen questions if the question was first seen by
    the user in the same confmodule run. This makes it easy for a
    confmodule to back up to previous questions without having to reset
    the seen flag.
  </para>
</listitem>
<listitem id="command_metaget">
  <para>
    METAGET
    <parameter>question</parameter>
    <parameter>field</parameter>
  </para>
  <para>
    This returns the value of any field of a question (the description, for
    example).
  </para>
</listitem>
<listitem id="command_register">
  <para>
    REGISTER
    <parameter>template</parameter>
    <parameter>question</parameter>
  </para>
  <para>
    This creates a new question that is bound to a
    template. By default each template has an associated
    question with the same name. However, any number of
    questions can really be associated with a template, and
    this lets you create more such questions.
  </para>
</listitem>
<listitem id="command_unregister">
  <para>
    UNREGISTER
    <parameter>question</parameter>
  </para>
  <para>
    This removes a question from the database.
  </para>
</listitem>
<listitem id="command_purge">
  <para>
    PURGE
  </para>
  <para>
    Call this in your postrm when your package is
    purged. It removes all templates and questions your
    package has generated.
  </para>
</listitem>