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 ([EMAIL PROTECTED]), 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 --