
== Selecting editing options and languages ==[prefs-langs-and-filters]

//Languages and files// tab in the //Editor//
section of the //Preferences// dialog allows customizing
how syntax highlighting language and editing options are chosen
depending on the document filename, as well as setting editing options for
all documents which use given language and choosing file patterns and mime types
for which the given language should be used.


=== Language-specific options ===[prefs-lang-options]

Here you can set editing options on per-language basis, as well as define
for which file patterns and mime types given language should be used.

| //Language// combo box  | Choose the language you want to customize. Settings for ``None`` will apply to documents for which no syntax highlighting language was chosen. |
| //Mime types//          | The given language will be used for files with these mime types, unless the language is chosen based on the filename or overridden in the //File filters// section.
| //Extensions//          | The given language will be used for files whose filenames match these patterns, unless overridden in the //File filters// section.
| //Options//             | Default editing options to use in documents which use the given language. These options can be overridden using //File filters// section, and options set in the file text have a higher priority as well. See the [Editing options #editing-options] section for the format of this entry content.


=== File filters ===[prefs-file-filters]

//File filters// section allows to customize editing options,
as well as syntax highlighting language, on per-document basis using regular expressions
which are matched against the document filename. Full file paths are used, so one can
have per-directory settings.

Use dollar if you need to match ends of filenames, e.g. "``\.doc$``" will work as "``*.doc``"
pattern.

The filters are applied in the order they appear in the list, one by one. All filters
are applied to every file, so several filters may affect options in the same file. In this
way one can set some options for a set of files or a directory, then set or modify some
additional options for certain files in that set, etc.

To add a filter, use //New// button. Click the filter in the list to
select it, then click the //Filter// or //Options//
part of it to edit. Use //Delete// button to delete a filter,
and //Up// and //Down// buttons to change the order in
which they are applied.

//Filter// field contains a regular expression matched agains the
document filename. If it is found in the filename, then the options from the
//Options// field are applied to the document.

//Options// field contains the options, in format described in the
[Editing options #editing-options] section.


=== Editing options ===[editing-options]

APPNAME has some editing options which can be set in the document text,
or in the //Preferences// dialog for sets of files or for given syntax
highlighting language.

To set the options in the document text, place the following on the first,
second or the last line of the document:
```
-%- @em{options} -%-
```
where //options// is the option string
```
@em{key}: @em{value}; @em{key}: @em{value}; ...
```
(the latter is the format used also in the //Preferences// dialog).

Values can be strings, integers, or booleans.

Booleans are ``yes``, ``no``, ``true``, ``false``, ``1``, ``0``.

If a string value contains ``:`` character, then the following syntax may be used: ``@em{key}=/@em{value}/``.
Any character may be used instead of slash (and it must not occur in the //value//).
Example: ``word-chars=@-/:@``

The following options are available:

| ``lang``         | syntax highlighting language to use in this document. |
| ``strip``        | a boolean value, whether trailing whitespace should be removed from the document on save.
| ``add-newline``  | a boolean value, whether the editor should ensure that saved files have a trailing new line character.
| ``tab-width``    | displayed width of the Tab character. NOTE: This is not an indentation offset, this is the visual width of a Tab character.
| ``use-tabs``     | whether the Tab character should be used for indentation.
| ``indent-width`` | an integer specifying indentation offset used when the Tab key is pressed to indent text.

APPNAME tries to understand modelines of Vim, Emacs, and Kate text editors, so chances are it will correctly
pick up the conventional settings from source files.
