6.5.3. Templates fields definition

This part gives some information which is mostly taken from the debconf-devel 7 manual page.

6.5.3.1. Type

6.5.3.1.1. string

Results in a free-form input field that the user can type any string into.

6.5.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.

6.5.3.1.3. boolean

A true/false choice. Remember: true/false, not yes/no…

6.5.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.

If choices are translatable strings, the ‘Choices’ field may be marked as translatable by using __Choices. The double underscore will split out each choice in a separate string.

The po-debconf system also offers interesting possibilities to only mark some choices as translatable. Example:

Template: foo/bar
Type: Select
#flag:translate:3
__Choices: PAL, SECAM, Other
_Description: TV standard:
 Please choose the TV standard used in your country.

In that example, only the ‘Other’ string is translatable while others are acronyms that should not be translated. The above allows only ‘Other’ to be included in PO and POT files.

The debconf templates flag system offers many such possibilities. The po-debconf 7 manual page lists all these possibilities.

6.5.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).

6.5.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 cases.

6.5.3.1.7. text

This type is now considered obsolete: don’t use it.

6.5.3.1.8. error

This type is designed to handle error messages. It is mostly similar to the note type. Front ends may present it differently (for instance, the dialog front end of cdebconf draws a red screen instead of the usual blue one).

It is recommended to use this type for any message that needs user attention for a correction of any kind.

6.5.3.2. Description: short and extended description

Template 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 accommodated 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 explicitly 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. User tend to ignore too long screens. 20 lines are by experience a border you shouldn’t cross, because that means that in the classical dialog interface, people will need to scroll, and lot of people just don’t do that.

The extended description should never include a question.

For specific rules depending on templates type (string, boolean, etc.), please read below.

6.5.3.3. Choices

This field should be used for select and multiselect types. It contains the possible choices that will be presented to users. These choices should be separated by commas.

6.5.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.