From 64a99d105c759b1242350be1d78d16b3c7017503 Mon Sep 17 00:00:00 2001
From: Russ Allbery <rra@debian.org>
Date: Mon, 21 Jun 2010 09:29:32 -0700
Subject: [PATCH] Document debconf SETTITLE command

Document the SETTITLE command in the debconf policy.  Inclusion of this
command should not pose any problems as it has been supported since 2003
(debconf version 1.3.22).

Patch from Frans Pop <elendil@planet.nl>.
---
 debconf_spec/debconf_specification.xml |  4 ++--
 debconf_spec/include/commands.xml      | 24 ++++++++++++++++++++----
 debconf_spec/include/types.xml         |  7 +++++++
 debian/changelog                       |  4 ++++
 upgrading-checklist.sgml               |  5 +++++
 5 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/debconf_spec/debconf_specification.xml b/debconf_spec/debconf_specification.xml
index ef8da7d..a163213 100644
--- a/debconf_spec/debconf_specification.xml
+++ b/debconf_spec/debconf_specification.xml
@@ -10,8 +10,8 @@
 
   <articleinfo>
     <title>Configuration management</title>
-    <subtitle>Protocol version 2</subtitle>
-    <releaseinfo>Revision 7.0</releaseinfo>
+    <subtitle>Protocol version 2.1</subtitle>
+    <releaseinfo>Revision 7.1</releaseinfo>
     <author>
       <firstname>
         Wichert
diff --git a/debconf_spec/include/commands.xml b/debconf_spec/include/commands.xml
index fbf0574..d5bad36 100644
--- 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
@@ -53,10 +53,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 +65,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>
diff --git a/debconf_spec/include/types.xml b/debconf_spec/include/types.xml
index 4112ee1..50b3fe4 100644
--- a/debconf_spec/include/types.xml
+++ b/debconf_spec/include/types.xml
@@ -69,6 +69,13 @@
         as is possible.
       </entry>
     </row>
+    <row>
+      <entry>title</entry>
+      <entry>
+        Holds a (short) string that can be displayed using the SETTITLE
+        command. Only the value of the short description will be used.
+      </entry>
+    </row>
   </tbody>
 </tgroup>
 </table>
diff --git a/debian/changelog b/debian/changelog
index e57be0e..f8fd3d4 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -78,6 +78,10 @@ debian-policy (3.8.5.0) UNRELEASED; urgency=low
     Seconded: Emilio Pozuelo Monfort <pochu@debian.org>
     Seconded: Andrew McMillan <andrew@morphoss.com>
     Closes: #575639
+  * Debconf: Add SETTITLE, like title but uses a template
+    Wording: Frans Pop <elendil@planet.nl>
+    Seconded: Russ Allbery <rra@debian.org>
+    Seconded: Ben Pfaff <blp@cs.stanford.edu>
   * Perl Policy: Change perlapi provides to use an ABI version
     Wording: Niko Tyni <ntyni@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
diff --git a/upgrading-checklist.sgml b/upgrading-checklist.sgml
index 9f0d966..921daa9 100644
--- a/upgrading-checklist.sgml
+++ b/upgrading-checklist.sgml
@@ -94,6 +94,11 @@ Release Jun 2010.
   in <file>debian/copyright</file>, although it will still be in
   common-licenses for the time being.
   </item>
+<tag>debconf</tag>
+  <item>Add <tt>SETTITLE</tt> (which has been supported for some time).
+  Like <tt>TITLE</tt> but takes a template instead of a string to allow
+  translation.
+  </item>
 <tag>perl</tag>
   <item><package>perl-base</package> now
   provides <package>perlapi-<var>abiname</var></package> instead of a
-- 
2.39.2