General rules of language selection

Most of properties related to presenting configuration to the user are multilingual, i.e. values of these properties are chosen depending on language settings.

Each language has an abbreviating id, for example "en" for English and "pl" for Polish.

Whenever the value of a multilingual property needs to be obtained, the value in user language should be returned, and if that's not possible, in English (en), which is the default language.

Titles

The title property defines the variable human-readable title, e.g.

title = {
    en: "DNS server address",
    pl: "Adres serwera DNS"
}

Descriptions

The descr property defines the variable human-readable description, i.e. a text which should help the user to understand the variable meaning and/or give him important notes on it. User interfaces should by default show variable descriptions next to titles. Example:

descr = {
    en: "Enable this option to start BGP daemon at boot",
    pl: "Włącz tą opcję, aby startować daemon BGP w czasie bootowania"
}

Help texts

The help property defines the variable help text, which should describe the variable in detail. Example:

help = {
    en: <EOF
The 'foobar' option

  The 'foobar' option turns your router in a supercharged vacuum cleaner, which
  (...)
EOF

    pl: <EOF
Opcja 'foobar'

  Opcja 'foobar' zamienia Twój router w turbodoładowany odkurzacz, który
  (...)
EOF

Help texts for directories should be available to view quickly while listing them (applies to graphical or pseudo-graphical interfaces).

User notes

The user can add arbitrary notes to any Flatconf entry (i.e. a file or a directory), which is stored in fc:/dir/variable.notes.

Autorefresh

In user interfaces which can support that, the refresh option gives the time in seconds after which the variable value should be fetched again. This applies only to variables of dir, action and diag types and/or having the value property.

Directories

Labels and tabs

The order property of directories may, apart of variable names, contain:

  • labels and
  • tabs,

both of which have multilingual titles. They are used to visually separate variables, so they are easier to recognize and localize in directory listing.

User interfaces that do not support tabs should treat them as labels.

Example:

# fs:/dir.fc
order = {
        # no label/tab here
        "hostname",
        "country",

        # all variables up to next label/tab marked as "Date and time"
        { type: "label", en: "Date and time", pl: "Data i czas" },
        "timezone",
        "ntp",
        "ntpserver",

        # well, assume SSH settings are for advanced users, so we create a special tab for them
        { type: "tab", en: "Advanced", pl: "Zaawansowane" },
        "ssh"
        "sshkeys"
}

Submit buttons

For directories of action type it is possible to replace the default text on submit buttons (e.g. just "Submit") using the submit property, which is similar to the title property.