Manoj

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

diff --git a/debconf_spec/include/commands.xml b/debconf_spec/include/commands.xml
index 984c29db0d16a2072d23c4f8b331af8f4d4d69a8..e7aa324921eaea76ed006b369bc22d74e9a7a7f0 100644 (file)
--- a/debconf_spec/include/commands.xml
+++ b/debconf_spec/include/commands.xml
@@ -43,9 +43,9 @@
        <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>
@@ -65,7 +65,7 @@
     of the frontend's window. If you don't specify anything, a
     title will automatically be generated.
   </para>
-</listitem> 
+</listitem>
 <listitem id="command_stop">
   <para>
     STOP
@@ -185,11 +185,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 +201,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 +215,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 +227,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 questons 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 questons without having to reset
+    the seen flag.
+  </para>
 </listitem>
 <listitem id="command_metaget">
   <para>