Build-Depends on emacs24-nox|emacs24 instead of emacs23.

[debian/debian-policy.git] / debconf_spec / include / commands.xml

diff --git a/debconf_spec/include/commands.xml b/debconf_spec/include/commands.xml
index dde75a265ba3b7122cf030dc6c59f8f0e90830ff..b8d30c27cadc339bbe461f255c56acc389a620fb 100644 (file)
--- a/debconf_spec/include/commands.xml
+++ b/debconf_spec/include/commands.xml
@@ -6,7 +6,7 @@
   <para>
     This exchanges with the frontend the protocol version
     number that is being used. The current version is
-    2.0. Versions in the 2.x series will be
+    2.1. Versions in the 2.x series will be
     backwards-compatible. You may specify the protocol version
     number you are speaking. The frontend will return the version
     of the protocol it speaks. If the version you specify is too
@@ -40,12 +40,22 @@
            Backing up to a previous step is supported.
          </entry>
         </row>
+       <row>
+         <entry>escape</entry>
+         <entry>
+           The frontend expects commands sent to it to have backslashes and
+           newlines quoted as <literal>\\</literal> and <literal>\n</literal>
+           respectively and will in turn quote backslashes and newlines in its
+           replies.  See <citerefentry><refentrytitle>debconf-escape</refentrytitle>
+           <manvolnum>1</manvolnum></citerefentry>.
+         </entry>
+       </row>
        <row>
          <entry>multiselect</entry>
          <entry>
-           The multiselect data type is supported. For compatability
-           reasons, you should not ask questions of this type unless
-           this capability is returned.
+           The multiselect data type is supported. You do not need to
+           check this capability if you depend on any modern version
+           of debconf.
          </entry>
        </row>
       </tbody>
@@ -53,10 +63,10 @@
     </table>
   </para>
 </listitem>
-<listitem id="command_title">
+<listitem id="command_settitle">
   <para>
-    TITLE
-    <parameter>string</parameter>
+    SETTITLE
+    <parameter>template</parameter>
   </para>
   <para>
     You can use this command to set a title in the
@@ -65,7 +75,23 @@
     of the frontend's window. If you don't specify anything, a
     title will automatically be generated.
   </para>
-</listitem> 
+  <para>
+    Using a template has the advantage that titles are translatable
+    and that they can be maintained in the same place as other text
+    displayed to users.
+  </para> 
+</listitem>
+<listitem id="command_title">
+  <para>
+    TITLE
+    <parameter>string</parameter>
+  </para>
+  <para>
+    Similar to SETTITLE, but takes a string instead of a template as
+    parameter. Consequence is that the title will not be translatable,
+    unless some other mechanism (like gettext) is used.
+  </para>
+</listitem>
 <listitem id="command_stop">
   <para>
     STOP
@@ -185,11 +211,12 @@
       <parameter>value</parameter>
   </para>
   <para>
-    Questions (and other items) can have substitutions embedded in their
-    descriptions. These substitutions look like
-    "<literal>${key}</literal>". When the question is displayed,
-    the substitutions are replaced with their values. This
-    command can be used to set the value of a substitution.
+    Questions (and other items) can have substitutions embedded in
+    their descriptions (and, currently in their choices fields). These
+    substitutions look like "<literal>${key}</literal>". When the
+    question is displayed, the substitutions are replaced with their
+    values. This command can be used to set the value of a
+    substitution.
   </para>
 </listitem>
 <listitem id="command_fget">
@@ -200,7 +227,7 @@
   </para>
   <para>
     Questions (and other items) can have flags associated with them. The
-    flags have a value of "<literal>true</literal>" or 
+    flags have a value of "<literal>true</literal>" or
     "<literal>false</literal>". This command returns
     the value of a flag.
   </para>
@@ -214,11 +241,11 @@
   </para>
   <para>
     This sets the state of a flag on a question. Valid
-    states for the flag are "<literal>true</literal>" and 
+    states for the flag are "<literal>true</literal>" and
     "<literal>false</literal>".
   </para>
   <para>
-    One common flag is the 
+    One common flag is the
     "<literal>seen</literal>" flag. It is normally only set if
     a user already seen a question.
     Typically, frontends only display questions to users if they have the
@@ -226,6 +253,13 @@
     question again -- in these cases you can set the seen flag to
     false to force the frontend to redisplay it.
   </para>
+  <para>
+    Note that as a special convenience behavior, frontends will
+    redisplay already seen questions if the question was first seen by
+    the user in the same confmodule run. This makes it easy for a
+    confmodule to back up to previous questions without having to reset
+    the seen flag.
+  </para>
 </listitem>
 <listitem id="command_metaget">
   <para>
@@ -266,7 +300,7 @@
     PURGE
   </para>
   <para>
-    Call this in your postinst when your package is
+    Call this in your postrm when your package is
     purged. It removes all templates and questions your
     package has generated.
   </para>