Document Debconf's escape capability.

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

diff --git a/debconf_spec/include/commands.xml b/debconf_spec/include/commands.xml
index fbf05744a3ce8a2fd365a2a95d870221fe4767c3..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,6 +40,16 @@
            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>
@@ -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,6 +75,22 @@
     of the frontend's window. If you don't specify anything, a
     title will automatically be generated.
   </para>
+  <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>