debconf_spec/include/commands.xml

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