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