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. 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_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
 189     their descriptions (and, currently in their choices fields). These
 190     substitutions look like "<literal>${key}</literal>". When the
 191     question is displayed, the substitutions are replaced with their
 192     values. This command can be used to set the value of a
 193     substitution.
 194   </para>
 195 </listitem>
 196 <listitem id="command_fget">
 197   <para>
 198     FGET
 199     <parameter>question</parameter>
 200     <parameter>flag</parameter>
 201   </para>
 202   <para>
 203     Questions (and other items) can have flags associated with them. The
 204     flags have a value of "<literal>true</literal>" or
 205     "<literal>false</literal>". This command returns
 206     the value of a flag.
 207   </para>
 208 </listitem>
 209 <listitem id="command_fset">
 210   <para>
 211     FSET
 212     <parameter>question</parameter>
 213     <parameter>flag</parameter>
 214     <parameter>value</parameter>
 215   </para>
 216   <para>
 217     This sets the state of a flag on a question. Valid
 218     states for the flag are "<literal>true</literal>" and
 219     "<literal>false</literal>".
 220   </para>
 221   <para>
 222     One common flag is the
 223     "<literal>seen</literal>" flag. It is normally only set if
 224     a user already seen a question.
 225     Typically, frontends only display questions to users if they have the
 226     seen flag set to "false". Sometimes you want the user to see a
 227     question again -- in these cases you can set the seen flag to
 228     false to force the frontend to redisplay it.
 229   </para>
 230   <para>
 231     Note that as a special convenience behavior, frontends will
 232     redisplay already seen questons if the question was first seen by
 233     the user in the same confmodule run. This makes it easy for a
 234     confmodule to back up to previous questons without having to reset
 235     the seen flag.
 236   </para>
 237 </listitem>
 238 <listitem id="command_metaget">
 239   <para>
 240     METAGET
 241     <parameter>question</parameter>
 242     <parameter>field</parameter>
 243   </para>
 244   <para>
 245     This returns the value of any field of a question (the description, for
 246     example).
 247   </para>
 248 </listitem>
 249 <listitem id="command_register">
 250   <para>
 251     REGISTER
 252     <parameter>template</parameter>
 253     <parameter>question</parameter>
 254   </para>
 255   <para>
 256     This creates a new question that is bound to a
 257     template. By default each template has an associated
 258     question with the same name. However, any number of
 259     questions can really be associated with a template, and
 260     this lets you create more such questions.
 261   </para>
 262 </listitem>
 263 <listitem id="command_unregister">
 264   <para>
 265     UNREGISTER
 266     <parameter>question</parameter>
 267   </para>
 268   <para>
 269     This removes a question from the database.
 270   </para>
 271 </listitem>
 272 <listitem id="command_purge">
 273   <para>
 274     PURGE
 275   </para>
 276   <para>
 277     Call this in your postrm when your package is
 278     purged. It removes all templates and questions your
 279     package has generated.
 280   </para>
 281 </listitem>