--- /dev/null
+<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.0. 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>multiselect</entry>
+ <entry>
+ The multiselect data type is supported. For compatability
+ reasons, you should not ask questions of this type unless
+ this capability is returned.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+</listitem>
+<listitem id="command_title">
+ <para>
+ TITLE
+ <parameter>string</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>
+</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. 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>
+</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 postinst when your package is
+ purged. It removes all templates and questions your
+ package has generated.
+ </para>
+</listitem>