Debconf Templates Style Guide : round 2
After publishing my first draft of the so-called Debconf Templates
Style Guide (DTSG....maybe this acronym is too close from the
DFSG....) on October 28th, I have received many input and I have
completed some parts of the document.
Thanks to all people who already commented or encouraged me to
continue this work. There are too much of you guys and I'm a bit too
lazy for mentioning you all, but consider I owe you a beer "à la
terrasse d'un café".
Below is the now second draft of the document.
Again, feel free to comment, either privately, or publicly (this mail
is still crossposted to -boot, -devel and -l10n-english).
Debconf Templates Style Guide
-----------------------------
History:
0.01 10/28/2003 Initial public release
0.02 11/10/2003 Basic proofreading by Debian contributors
TODO:
- Use something else than crude text format. Help and advices welcome
- Add Rationale at the beginning of the document
- Details and guidelines for Choices fields
- Probably lot of stuff I didn't even think about.. :)
1. Do not abuse debconf
-----------------------
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.
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.
Carefully choose the questions priorities in maintainer scripts. See
man debconf-devel(7) for details about priorities. Most questions
should use medium and low priorities.
2. General recommendations for authors and translators
------------------------------------------------------
2.1 Write correct English
-------------------------
Most Debian package maintainers are not native English speakers. So,
writing properly phrased templates may not be easy for them.
Please use (and abuse) debian-l10n-english@lists.debian.org mailing
list. Have your templates proofread.
Badly written templates give a poor image of your package, of your
work...or even of Debian itself.
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.
2.2 Be kind to translators
--------------------------
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.
Please use gettext-based templates. Install po-debconf on your
development system and read its documentation ("man po-debconf" is a
good start).
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.
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.
2.3 Do not make assumptions about interfaces
--------------------------------------------
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.
More generally speaking, try to avoid referring to user actions. Just
give facts.
3. Templates fields definition
------------------------------
This part gives some information which is mostly taken from the
debconf-devel(7) manual page.
3.1 Type
--------
3.1.1 string
------------
Results in a free-form input field that the user can type any string into.
3.1.2 password
--------------
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.
3.1.3 boolean
-------------
A true/false choice.
3.1.4 select
------------
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
3.1.5 multiselect
-----------------
Like the select data type, except the user can choose any number of
items from the choices list (or chose none of them).
3.1.6 note
----------
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
3.1.7 text
----------
This type is now considered obsolete: don't use it.
3.1.8 error
-----------
THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET.
It has been added to cdebconf, the C version of debconf, first used in
the Debian Installer.
Please do not use it unless debconf supports it.
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).
3.2 Description: short and extended description
------------------------------------------------
Templates descriptions have two parts: short and extended. The short
description is in the "Description:" line of the template.
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.
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?"
The short description does not necessarily have to be a full
sentence. This is part of the "keep it short and efficient"
recommendation.
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.
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.
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.
For specific rules depending on templates type (string, boolean,
etc.), please read below.
3.3 Choices
-----------
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.
3.4 Default
-----------
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.
4. Templates fields specific style guide
----------------------------------------
4.1 Type field
--------------
No specific indication except : use the appropriate type by referring
to section 3.
4.2 Description field
---------------------
Below are specific instructions for properly writing the Description
(short and extended) depending on the template type.
4.2.1 String/password templates
-------------------------------
- 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.
- 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.
4.2.2 Boolean templates
-----------------------
- 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)
- The extended description should NOT include a question.
- Again, please avoid referring to specific interface widgets. A common
mistake for such templates is "if you answer Yes"-type
constructions.
4.2.3 Select/Multiselect
------------------------
- The short description is a prompt and NOT a title. Do NOT use useless
"Please choose..." constructions. Users are intelligent enough...:)
- 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).
4.2.4 Notes
-----------
- The short description should be considered to be a *title*.
- The extended description is what will be displayed as a more detailed
explanation of the note. Phrases, no terse writing style.
- 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.
4.3 Choices field
-----------------
<to be written>
4.4 Default field
-----------------
Do NOT use empty default field. If you don't want to use default
values, do not use Default at all.
If you use po-debconf (and you SHOULD, see 2.2), consider making this
field translatable, if you think it may be translated.
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 po-debconf(7).
5. Specific rules
-----------------
5.1 Debian installer
--------------------
Entries for main menu should use the infinitive form: "Execute a
shell" instead of "Shell execution". They are of type "text".
They (and their translations) should not exceed 58 characters length.
Error templates should use the "error" template type.
Templates should not refer directly to other debian-installer modules
main menu entry name. These entry names are likely to change. For instance, do not use:
Go back to "Partition a hard disk" and retry
but rather
Go back to the hard disk partitioning step and retry
--
Reply to: