chiark / gitweb /
debconf templates best practices
authoraba <aba@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sun, 7 Nov 2004 13:16:12 +0000 (13:16 +0000)
committeraba <aba@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Sun, 7 Nov 2004 13:16:12 +0000 (13:16 +0000)
git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@2632 313b444b-1b9f-4f58-a734-7bb04f332e8d

debian/changelog
developers-reference.sgml

index f263d12..1115b43 100644 (file)
@@ -31,6 +31,7 @@ developers-reference (3.3.5) unstable; urgency=low
     - add information about gpg usage. Closes: #175815.
     - make key replacement instructions more details. Closes: #275921
     - typo and language fixes. Thanks, Era Eriksson. Closes: #277576
+    - add hints about debconf templates from Christian Perrier.
   * Matt Zimmerman
     - Security uploads get urgency=high
     - Be even more explicit about not uploading security updates
index 5443f11..a08ed3b 100644 (file)
@@ -6,7 +6,7 @@
   <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.246 $">
+  <!ENTITY cvs-rev "$Revision: 1.247 $">
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
@@ -3973,6 +3973,332 @@ future.
 Debconf is a great tool but it is often poorly used.   Many common mistakes
 are listed in the <manref name="debconf-devel" section="7"> man page. 
 It is something that you must read if you decide to use debconf.
+Also, we document some best practices here.
+       <p>
+These guidelines include some writing style and typography
+recommendations, general considerations about debconf usage as well as
+more specific recommendations for some parts of the distribution (for
+instance, the installation system).
+
+       <sect1>Do not abuse debconf
+       <p>
+Since debconf appeared in Debian, it has been widely abused and
+several criticisms received by the Debian distribution come from
+debconf abuse with the need of answering a wide bunch of questions
+before getting any little thing installed.
+       <p>
+Keep usage notes to what they belong: the NEWS.Debian, or
+README.Debian file. Only use notes for important notes which may
+directly affect the package usability. Remember that notes will always
+block the install until confirmed or bother the user by email.
+       <p>
+Carefully choose the questions priorities in maintainer scripts. See
+<manref name="debconf-devel" section="7"> for details about priorities.
+Most questions should use medium and low priorities.
+
+       <sect1>General recommendations for authors and translators
+       <p>
+       <sect2>Write correct English
+       <p>
+Most Debian package maintainers are not native English speakers. So,
+writing properly phrased templates may not be easy for them.
+       <p>
+Please use (and abuse) debian-l10n-english@lists.debian.org mailing
+list. Have your templates proofread.
+       <p>
+Badly written templates give a poor image of your package, of your
+work...or even of Debian itself.
+       <p>
+Avoid technical jargon as much as possible. If some terms sound common
+to you, they may be impossible to understand for others. If you cannot
+avoid them, try to explain them (use the extended description). When
+doing so, try to balance between verbosity and simplicity.
+
+       <sect2>Be kind to translators
+       <p>
+Debconf templates may be translated. Debconf, along with its sister
+package po-debconf offers a simple framework for getting
+templates translated by translation teams or even individuals.
+       <p>
+Please use gettext-based templates. Install po-debconf on your
+development system and read its documentation ("man po-debconf" is a
+good start).
+       <p>
+Avoid changing templates too often. Changing templates text induces
+more work to translators which will get their translation "fuzzied". If
+you plan changes to your original templates, please contact
+translators. Most active translators are very reactive and getting
+their work included along with your modified templates will save you
+additional uploads. If you use gettext-based templates, the
+translator's name and e-mail addresses are mentioned in the po files
+headers.
+       <p>
+If in doubt, you may also contact the translation team for a given
+language (debian-l10n-xxxxx@lists.debian.org), or the
+debian-i18n@lists.debian.org mailing list.
+
+       <sect2>Do not make assumptions about interfaces
+       <p>
+Templates text should not make reference to widgets belonging to some
+debconf interfaces. Sentences like "If you answer Yes..." have no
+meaning for users of graphical interfaces which use checkboxes for
+boolean questions.
+       <p>
+More generally speaking, try to avoid referring to user actions.
+Just give facts.
+
+       <sect2>Do not use first person
+       <p>
+You should avoid the use of first person ("I will do this..." or "We
+recommend..."). The computer is not a person and the Debconf tempaltes
+do not speak for the Debian developers. You should use neutral
+construction and often the passive form. Those of you who already
+wrote scientific publications, just write your templates like you
+would write a scientific paper.
+
+       <sect2>Be gender neutral
+       <p>
+The world is made of men and women. Please use gender-neutral
+constructions in your writing. This is not Political Correctness, this
+is showing respect to all humanity.
+
+
+       <sect1>Templates fields definition
+       <p>
+This part gives some information which is mostly taken from the
+<manref name="debconf-devel" section="7"> manual page.
+
+       <sect2>Type
+       <p>
+
+       <sect3>string:
+       <p>
+Results in a free-form input field that the user can type  any string into.
+
+       <sect3>password:
+       <p>
+Prompts the user for a password. Use this with caution; be aware that
+the password the user enters will be written to debconf's
+database. You should probably clean that value out of the database as
+soon as is possible.
+
+       <sect3>boolean:
+       <p>
+A true/false choice. Remember: true/false, NOT YES/NO...
+
+       <sect3>select:
+       <p>
+A choice between one of a number of values. The choices must be
+specified in a field named 'Choices'.  Separate the possible values
+with commas and spaces, like this: Choices: yes, no, maybe
+
+       <sect3>multiselect:
+       <p>
+Like the select data type, except the user can choose any number of
+
+       items from the choices list (or chose none of them).
+
+       <sect3>note:
+       <p>
+Rather than being a question per se, this datatype indicates a note
+that can be displayed to the user. It should be used only for
+important notes that the user really should see, since debconf will go
+to great pains to make sure the user sees it; halting the install for
+them to press a key, and even mailing the note to them in some
+cases.
+
+       <sect3>text:
+       <p>
+This type is now considered obsolete: don't use it.
+
+       <sect3>error:
+       <p>
+<strong>THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET.</strong>
+       <p>
+It has been added to cdebconf, the C version of debconf, first used in
+the Debian Installer.
+       <p>
+Please do not use it unless debconf supports it.
+       <p>
+This type is designed to handle error message. It is mostly similar to
+the "note" type. Frontends may present it differently (for instance,
+the dialog frontend of cdebconf draws a red screen instead of the
+usual blue one).
+
+
+       <sect2>Description: short and extended description
+       <p>
+Templates descriptions have two parts: short and extended. The short 
+description is in the "Description:" line of the template.
+       <p>
+The short description should be kept short (50 characters or so) so
+that it may be accomodated by most debconf interfaces. Keeping it
+short also helps translators, as usually translations tend to end up
+being longer than the original.
+       <p>
+The short description should be able to stand on its own. Some
+interfaces do not show the long description by default, or only if the
+user explicitely asks for it or even do not show it at all. Avoid
+things like "What do you want to do?"
+       <p>
+The short description does not necessarily have to be a full
+sentence. This is part of the "keep it short and efficient"
+recommendation.
+       <p>
+The extended description should not repeat the short description word
+for word. If you can't think up a long description, then first, think
+some more.  Post to debian-devel. Ask for help. Take a writing class!
+That extended description is important. If after all that you still
+can't come up with anything, leave it blank.
+       <p>
+The extended description should use complete sentences. Paragraphs
+should be kept short for improved readability. Do not mix two ideas
+in the same paragraph but rather use another paragraph.
+       <p>
+Don't be too verbose. Some debconf interfaces cannot deal very well
+with descriptions of more than about 20 lines, so try to keep it below
+this limit.
+       <p>
+For specific rules depending on templates type (string, boolean,
+etc.), please read below.
+
+       <sect2>Choices
+       <p>
+This field should be used for Select and Multiselect types. It
+contains the possible choices which will be presented to users. These
+choices should be separated by commas.
+
+
+       <sect2>Default
+       <p>
+This field is optional. It contains the default answer for string,
+select and multiselect templates. For multiselect templates, it may
+contain a comma-separated list of choices.
+
+       <sect1>Templates fields specific style guide
+       <p>
+
+       <sect2>Type field
+       <p>
+No specific indication except: use the appropriate type by referring
+to the previous section.
+
+       <sect2>Description field
+       <p>
+Below are specific instructions for properly writing the Description
+(short and extended) depending on the template type.
+
+       <sect3>String/password templates
+       <p>
+<list>
+<item> The short description is a prompt and NOT a title. Avoid
+    question style prompts ("IP Address?") in favour of
+    "opened" prompts ("IP address:").
+    The use of colons is recommended.
+
+<item> The extended description is a complement to the short description.
+    In the extended part, explain what is being asked, rather than ask
+    the same question again using longer words. Use complete sentences.
+    Terse writing style is strongly discouraged.
+</list>
+
+       <sect3>Boolean templates
+       <p>
+<list>
+<item> The short description should be phrased in the form of a question
+    which should be kept short and should generally end with a question
+    mark. Terse writing style is permitted and even encouraged if the
+    question is rather long (remember that translations are often longer
+    than original versions)
+
+<item> The extended description should NOT include a question. 
+
+<item> Again, please avoid referring to specific interface widgets. A common
+    mistake for such templates is "if you answer Yes"-type
+    constructions.
+</list>
+
+       <sect3>Select/Multiselect
+       <p>
+<list>
+<item> The short description is a prompt and NOT a title. Do NOT use useless
+    "Please choose..." constructions. Users are clever enough to figure
+    out they have to choose something...:)
+
+<item> The extended description will complete the short description. It may
+    refer to the available choices. It may also mention that the user
+    may choose more than one of the available choices, if the template
+    is a multiselect one (although the interface often makes this
+    clear).
+</list>
+
+       <sect3>Notes
+       <p>
+<list>
+<item> The short description should be considered to be a *title*. 
+
+<item> The extended description is what will be displayed as a more detailed
+    explanation of the note. Phrases, no terse writing style.
+
+<item> DO NOT ABUSE DEBCONF. Notes are the most common way to abuse
+    debconf. As written in debconf-devel manual page: it's best to use them
+    only for warning about very serious problems. The NEWS.Debian or
+    README.Debian files are the appropriate location for a lot of notes.
+    If, by reading this, you consider converting your Note type templates
+    to entries in NEWS/Debian or README.Debian, plus consider keeping existing
+    translations for the future.
+</list>
+
+
+       <sect2>Choices field
+       <p>
+If the Choices are likely to change often, please consider using the
+"__Choices" trick. This will split each individual choice into a
+single string, which will considerably help translators for doing
+their work.
+
+       <sect2>Default field
+       <p>
+If the default value, for a "select" template, is likely to vary
+depending on the user language (for instance, if the choice is a
+language choice), please use the "_DefaultChoice" trick.
+       <p>
+This special field allow translators to put the most appropriate
+choice according to their own language. It will become the default
+choice when their language is used while your own mentioned Default
+Choice will be used chan using English.
+       <p>
+Example, taken from the geneweb package templates:
+<example>
+Template: geneweb/lang
+Type: select
+__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
+# This is the default choice. Translators may put their own language here
+# instead of the default.
+# WARNING : you MUST use the ENGLISH FORM of your language
+# For instance, the french translator will need to put "French (fr)" here.
+_DefaultChoice: English (en)[ translators, please see comment in PO files]
+_Description: Geneweb default language:
+</example>
+       <p>
+Note the use of brackets which allow internal comments in debconf
+fields.  Also note the use of comments which will show up in files the
+translators will work with.
+       <p>
+The comments are needed as the DefaultChoice trick is a bit
+confusing: the translators may put their own choice
+
+       <sect2>Default field
+       <p>
+Do NOT use empty default field. If you don't want to use default
+values, do not use Default at all.
+       <p>
+If you use po-debconf (and you SHOULD, see 2.2), consider making this
+field translatable, if you think it may be translated.
+       <p>
+If the default value may vary depending on language/country (for
+instance the default value for a language choice), consider using the
+special "_DefaultChoice" type documented in <manref name="po-debconf" section="7">).
       </sect>