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