debconf/commands.xml

   1 <itemizedlist>
   2   <listitem id="command_version">
   3     <para>
   4       VERSION
   5       <parameter>number</parameter>
   6     </para>
   7     <para>
   8       This exchanges with the frontend the protocol version number that is
   9       being used. The current version is 2.1. Versions in the 2.x series
  10       will be backwards-compatible. You may specify the protocol version
  11       number you are speaking. The frontend will return the version of the
  12       protocol it speaks. If the version you specify is too low, this
  13       command will return the numeric return code <literal>30</literal>.
  14     </para>
  15   </listitem>
  16   <listitem id="command_capb">
  17     <para>
  18       CAPB
  19       <parameter>capabilities</parameter>
  20     </para>
  21     <para>
  22       This exchanges with the frontend a list of supported capabilities
  23       Capabilities both the frontend and your confmodule support may be
  24       used; the capabilities supported by the frontend are returned by
  25       this command.
  26       <table frame="all">
  27         <title>Currently used capabilities</title>
  28         <tgroup cols="2">
  29           <thead>
  30             <row>
  31               <entry>capability</entry>
  32               <entry>description</entry>
  33             </row>
  34           </thead>
  35           <tbody>
  36             <row>
  37               <entry>backup</entry>
  38               <entry>
  39                 Backing up to a previous step is supported.
  40               </entry>
  41             </row>
  42             <row>
  43               <entry>escape</entry>
  44               <entry>
  45                 The frontend expects commands sent to it to have
  46                 backslashes and newlines quoted as <literal>\\</literal>
  47                 and <literal>\n</literal> respectively and will in turn
  48                 quote backslashes and newlines in its replies.  See
  49                 <citerefentry><refentrytitle>debconf-escape</refentrytitle>
  50                 <manvolnum>1</manvolnum></citerefentry>.
  51               </entry>
  52             </row>
  53             <row>
  54               <entry>multiselect</entry>
  55               <entry>
  56                 The multiselect data type is supported. You do not need to
  57                 check this capability if you depend on any modern version
  58                 of debconf.
  59               </entry>
  60             </row>
  61           </tbody>
  62         </tgroup>
  63       </table>
  64     </para>
  65   </listitem>
  66   <listitem id="command_settitle">
  67     <para>
  68       SETTITLE
  69       <parameter>template</parameter>
  70     </para>
  71     <para>
  72       You can use this command to set a title in the frontend. This may
  73       appear in different ways, depending on the frontend being used, for
  74       example it might change the title of the frontend's window. If you
  75       don't specify anything, a title will automatically be generated.
  76     </para>
  77     <para>
  78       Using a template has the advantage that titles are translatable and
  79       that they can be maintained in the same place as other text
  80       displayed to users.
  81     </para>
  82   </listitem>
  83   <listitem id="command_title">
  84     <para>
  85       TITLE
  86       <parameter>string</parameter>
  87     </para>
  88     <para>
  89       Similar to SETTITLE, but takes a string instead of a template as
  90       parameter. Consequence is that the title will not be translatable,
  91       unless some other mechanism (like gettext) is used.
  92     </para>
  93   </listitem>
  94   <listitem id="command_stop">
  95     <para>
  96       STOP
  97     </para>
  98     <para>
  99       This command tells the frontend you're done talking to it. Typically
 100       the frontend can detect the termination of your program and this
 101       command is not necessary.
 102     </para>
 103   </listitem>
 104   <listitem id="command_input">
 105     <para>
 106       INPUT
 107       <parameter>priority</parameter>
 108       <parameter>question</parameter>
 109     </para>
 110     <para>
 111       This tells the frontend to display a question (or other type of
 112       item) to the user. <parameter>question</parameter> is the name of
 113       the item to display, all other information about the item is
 114       retrieved from the templates described previously.
 115       <parameter>priority</parameter> is how important it is that the user
 116       be prompted. The frontend need only ask this question if the
 117       priority is high enough. The question is not displayed until a go
 118       command is given. This allows us to ask multiple questions in a
 119       single screen. Once a question has been displayed to the user and
 120       the user has provided input, the frontend will set the
 121       <literal>seen</literal> flag.
 122       &priority_table;
 123     </para>
 124     <para>
 125       Note that the frontend decides if the user is actually prompted or
 126       not. If the user has already answered a question, they are normally
 127       not asked it again even if input is called again. And if the user is
 128       ignoring low priority items, they will not see them. In either of
 129       these cases, this command returns the numeric return code
 130       <literal>30</literal>.
 131     </para>
 132   </listitem>
 133   <listitem id="command_beginblock">
 134     <para>
 135       BEGINBLOCK
 136     </para>
 137   </listitem>
 138   <listitem id="command_endblock">
 139     <para>
 140       ENDBLOCK
 141     </para>
 142     <para>
 143       Some frontends are able to display a number of items to the user at
 144       once. To do this, they need to be given blocks of input commands,
 145       enclosed in the BEGINBLOCK and ENDBLOCK commands. Blocks can be
 146       nested and very advanced frontends may use this as a user interface
 147       hint.
 148     </para>
 149     <note>
 150       <para>
 151         There is an implicit block around any set of INPUT commands that
 152         are not enclosed in an explicit block.
 153       </para>
 154     </note>
 155   </listitem>
 156   <listitem id="command_go">
 157     <para>
 158       GO
 159     </para>
 160     <para>
 161       Shows the current set of accumulated items to the user and lets them
 162       fill in values, etc. If the backup capability is supported and the
 163       user indicates they want to back up a step, this command returns the
 164       numeric return code <literal>30</literal>.
 165     </para>
 166   </listitem>
 167   <listitem id="command_clear">
 168     <para>
 169       CLEAR
 170     </para>
 171     <para>
 172       Clears the accumulated set of INPUT commands without displaying them
 173       to the user.
 174     </para>
 175   </listitem>
 176   <listitem id="command_get">
 177     <para>
 178       GET <parameter>question</parameter>
 179     </para>
 180     <para>
 181       Ask the frontend to tell you how the user answered a question. The
 182       value is returned to you.
 183     </para>
 184   </listitem>
 185   <listitem id="command_set">
 186     <para>
 187       SET
 188       <parameter>question</parameter>
 189       <parameter>value</parameter>
 190     </para>
 191     <para>
 192       Set the answer of a question to a value.
 193     </para>
 194   </listitem>
 195   <listitem id="command_reset">
 196     <para>
 197       RESET <parameter>question</parameter>
 198     </para>
 199     <para>
 200       Reset the question to its default value. This includes resetting
 201       flags to their defaults.
 202     </para>
 203   </listitem>
 204   <listitem id="command_subst">
 205     <para>
 206       SUBST
 207       <parameter>question</parameter>
 208       <parameter>key</parameter>
 209       <parameter>value</parameter>
 210     </para>
 211     <para>
 212       Questions (and other items) can have substitutions embedded in their
 213       descriptions (and, currently in their choices fields). These
 214       substitutions look like "<literal>${key}</literal>". When the
 215       question is displayed, the substitutions are replaced with their
 216       values. This command can be used to set the value of a substitution.
 217     </para>
 218   </listitem>
 219   <listitem id="command_fget">
 220     <para>
 221       FGET
 222       <parameter>question</parameter>
 223       <parameter>flag</parameter>
 224     </para>
 225     <para>
 226       Questions (and other items) can have flags associated with them. The
 227       flags have a value of "<literal>true</literal>" or
 228       "<literal>false</literal>". This command returns the value of a
 229       flag.
 230     </para>
 231   </listitem>
 232   <listitem id="command_fset">
 233     <para>
 234       FSET
 235       <parameter>question</parameter>
 236       <parameter>flag</parameter>
 237       <parameter>value</parameter>
 238     </para>
 239     <para>
 240       This sets the state of a flag on a question. Valid states for the
 241       flag are "<literal>true</literal>" and "<literal>false</literal>".
 242     </para>
 243     <para>
 244       One common flag is the "<literal>seen</literal>" flag. It is
 245       normally only set if a user already seen a question.  Typically,
 246       frontends only display questions to users if they have the seen flag
 247       set to "false". Sometimes you want the user to see a question again
 248       -- in these cases you can set the seen flag to false to force the
 249       frontend to redisplay it.
 250     </para>
 251     <para>
 252       Note that as a special convenience behavior, frontends will
 253       redisplay already seen questions if the question was first seen by
 254       the user in the same confmodule run. This makes it easy for a
 255       confmodule to back up to previous questions without having to reset
 256       the seen flag.
 257     </para>
 258   </listitem>
 259   <listitem id="command_metaget">
 260     <para>
 261       METAGET
 262       <parameter>question</parameter>
 263       <parameter>field</parameter>
 264     </para>
 265     <para>
 266       This returns the value of any field of a question (the description,
 267       for example).
 268     </para>
 269   </listitem>
 270   <listitem id="command_register">
 271     <para>
 272       REGISTER
 273       <parameter>template</parameter>
 274       <parameter>question</parameter>
 275     </para>
 276     <para>
 277       This creates a new question that is bound to a template. By default
 278       each template has an associated question with the same
 279       name. However, any number of questions can really be associated with
 280       a template, and this lets you create more such questions.
 281     </para>
 282   </listitem>
 283   <listitem id="command_unregister">
 284     <para>
 285       UNREGISTER
 286       <parameter>question</parameter>
 287     </para>
 288     <para>
 289       This removes a question from the database.
 290     </para>
 291   </listitem>
 292   <listitem id="command_purge">
 293     <para>
 294       PURGE
 295     </para>
 296     <para>
 297       Call this in your postrm when your package is purged. It removes all
 298       templates and questions your package has generated.
 299     </para>
 300   </listitem>
 301 </itemizedlist>