442 lines
18 KiB
XML
442 lines
18 KiB
XML
<?xml version="1.0"?><!-- -%- indent-width:2 -%- -->
|
|
<!DOCTYPE chapter [
|
|
<!ENTITY % medit-defines SYSTEM "built/medit-defines.ent">
|
|
%medit-defines;
|
|
]>
|
|
<chapter id="chapter-prefs">
|
|
<title>Preferences</title>
|
|
|
|
<sect1 id="section-prefs-dialog" moo.helpsection="PREFS_DIALOG">
|
|
<title>Preferences dialog</title>
|
|
<para>
|
|
<guilabel>Preferences</guilabel> provides access to almost all &medit; settings.
|
|
Some settings are not available here, see <xref linkend="section-prefs-xml"/>.
|
|
</para>
|
|
<para>
|
|
<guilabel>Preferences</guilabel> dialog has several tabs:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel>General</guilabel></term>
|
|
<listitem>Contains settings which didn't find place in other sections, see
|
|
<xref linkend="section-prefs-general"/>.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>View</guilabel></term>
|
|
<listitem>Contains settings which control how &medit; displays text.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>File</guilabel></term>
|
|
<listitem>Contains settings which control how &medit; saves and loads files, see
|
|
<xref linkend="section-prefs-file"/>.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Languages</guilabel></term>
|
|
<listitem>See <xref linkend="section-prefs-langs"/>.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>File Filters</guilabel></term>
|
|
<listitem>See <xref linkend="section-prefs-file-filters"/>.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Plugins</guilabel></term>
|
|
<listitem>Displays information about available plugings and allows to disable/enable them.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>File Selector</guilabel></term>
|
|
<listitem>Contains File Selector settings, see <xref linkend="section-prefs-file-selector"/>.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Tools</guilabel></term>
|
|
<listitem>User-defined tools, see <xref linkend="section-prefs-user-tools"/>.</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="section-prefs-general" moo.helpsection="PREFS_GENERAL">
|
|
<title><guilabel>General</guilabel> tab</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>Smart Home and End</parameter></term>
|
|
<listitem>If checked, <keycap>Home</keycap> key moves cursor to first non-whitespace character
|
|
on the line on first <keycap>Home</keycap> key press, and moves cursor to the first character on the line
|
|
on second key press. Analogously <keycap>End</keycap> key moves cursor past last non-whitespace character
|
|
on the line, and then past last character on next key press.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Enable auto indentation</parameter></term>
|
|
<listitem>If checked, pressing <keycap>Enter</keycap> key inserts line end character and
|
|
whitespace to indent next line according to indentation settings.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Do not use tabs for indentation</parameter></term>
|
|
<listitem>If checked, spaces are used for indentation instead of tab character.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Tab key indents</parameter></term>
|
|
<listitem>If checked, <keycap>Tab</keycap> key inserts whitespace characters according
|
|
to indentation settings to indent text at cursor. Otherwise <keycap>Tab</keycap> key
|
|
only inserts single tab character.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Tab width</parameter></term>
|
|
<listitem>Displayed width of tab character in spaces. By default it is
|
|
<constant>8</constant>.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Indent width</parameter></term>
|
|
<listitem>Number of spaces inserted by single <keycap>Tab</keycap> key press. If tabs are
|
|
used for indentation then <keycap>Tab</keycap> key inserts spaces until line indent is
|
|
multiple of tab width, then it replaces spaces with tabs (if indent width is a multiple
|
|
of tab width then only tab characters are used.)</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="section-prefs-file" moo.helpsection="PREFS_FILE">
|
|
<title><guilabel>File</guilabel> tab</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>Encodings to autodetect</parameter></term>
|
|
<listitem><para>This entry contains comma-separated list of encodings used when
|
|
loading files if encoding is not specified in the <guilabel>Open</guilabel>.
|
|
&medit; tries every encoding from the list one by one and stops when file
|
|
content is valid text in this encoding. <code>LOCALE</code> denotes encoding
|
|
from current locale.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Encoding for new files</parameter></term>
|
|
<listitem><para>This is default encoding to save new files. For every document
|
|
its encoding on disk can be changed using Encoding submenu of Document menu.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Remove trailing spaces</parameter></term>
|
|
<listitem><para>If checked, trailing whitespace characters are removed from each
|
|
line of the document on save.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Ensure trailing newline</parameter></term>
|
|
<listitem><para>If checked, new line character will be added to document on save
|
|
if it doesn't end with one.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Make backups</parameter></term>
|
|
<listitem><para>If checked, old file contents will be moved to backup file on
|
|
save.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Enable session support</parameter></term>
|
|
<listitem><para>If checked, &medit; will remember open documents on exit and restore
|
|
them next time it's launched.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Open and Save As dialogs show current document folder</parameter></term>
|
|
<listitem><para>If checked, Open and Save As dialogs will show folder of the current document.
|
|
Otherwise they will show last used folder.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="section-prefs-langs" moo.helpsection="PREFS_LANGS">
|
|
<title><guilabel>Languages</guilabel> tab</title>
|
|
<para>
|
|
<guilabel>Languages and files</guilabel> tab 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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><guilabel>Language</guilabel> combo box</term>
|
|
<listitem><para>
|
|
Choose the language you want to customize. Settings for <code>None</code> will apply to
|
|
documents for which no syntax highlighting language was chosen.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Mime types</guilabel></term>
|
|
<listitem><para>
|
|
Selected language will be used for files with these mime types, unless the language
|
|
is chosen based on the filename or overridden in the <guilabel>File filters tab</guilabel> section.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Extensions</guilabel></term>
|
|
<listitem><para>
|
|
Selected language will be used for files whose filenames match these patterns,
|
|
unless overridden in the <guilabel>File filters tab</guilabel> section.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><guilabel>Options</guilabel></term>
|
|
<listitem><para>
|
|
Default editing options to use in documents which use the given language. These
|
|
options can be overridden using <guilabel>File filters tab</guilabel> section, and options set
|
|
in the file text have a higher priority as well. See <xref linkend="section-editing-options"/>
|
|
for format of this entry content.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="section-prefs-file-filters" moo.helpsection="PREFS_FILTERS">
|
|
<title>File filters tab</title>
|
|
<para>
|
|
<guilabel>File filters tab</guilabel> 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 (globs can also be
|
|
used, see below). Full file paths are used, so one can have per-directory settings.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
To add a filter, use <guilabel>New</guilabel> button. Click the filter in the list to
|
|
select it, then click the <guilabel>Filter</guilabel> or <guilabel>Options</guilabel>
|
|
part of it to edit. Use <guilabel>Delete</guilabel> button to delete a filter,
|
|
and <guilabel>Up</guilabel> and <guilabel>Down</guilabel> buttons to change the order in
|
|
which they are applied.
|
|
</para>
|
|
<para>
|
|
<guilabel>Filter</guilabel> field contains a regular expression matched agains the
|
|
document filename. If it is found in the filename,
|
|
then the options from the <guilabel>Options</guilabel> field are applied to the
|
|
document. Example:
|
|
<programlisting>projects/moo/</programlisting>
|
|
</para>
|
|
<para>
|
|
Use dollar if you need to match ends of filenames, e.g. "<code>\.doc$</code>" will work as
|
|
"<code>*.doc</code>" pattern.
|
|
</para>
|
|
<para>
|
|
Alternatively it can be
|
|
a comma-separated list of globs prefixed with "<code>globs:</code>" or a list
|
|
of language ids prefixed with "<code>langs:</code>", e.g.
|
|
<programlisting>globs:*.c,*.h</programlisting>
|
|
or
|
|
<programlisting>langs:c,c++</programlisting>
|
|
</para>
|
|
<para>
|
|
<guilabel>Options</guilabel> field contains the options, in format described in
|
|
<xref linkend="section-editing-options"/>.
|
|
</para>
|
|
<informalexample>
|
|
<graphic fileref="img/prefs-file-filters.png" align="center"/>
|
|
</informalexample>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="section-prefs-file-selector" moo.helpsection="PREFS_FILE_SELECTOR">
|
|
<title><guilabel>File Selector</guilabel> tab</title>
|
|
<para>
|
|
<guilabel>File Selector</guilabel> tab in the <guilabel>Preferences</guilabel>
|
|
dialog allows to define custom commands which are available in
|
|
<guimenu>Open With</guimenu> submenu of context menu in File Selector. By default
|
|
this submenu contains single item <guimenuitem>Default Application</guimenuitem>
|
|
which opens selected file with default application as configured in the system.
|
|
Here you can add additional commands and set whether they should be available
|
|
only for given file patterns or syntax highlighting languages.
|
|
</para>
|
|
<para>
|
|
Use <guilabel>New</guilabel> button to create new command, <guilabel>Delete</guilabel>
|
|
button to delete selected command, and <guilabel>Up</guilabel> and <guilabel>Down</guilabel>
|
|
to change relative order of the commands, they will appear in the menu in the same order
|
|
as in this list.
|
|
</para>
|
|
<para>
|
|
The following entries set the command properties:
|
|
<variablelist>
|
|
<?dbhtml list-presentation="table"?>
|
|
<!-- <?dbhtml term-separator=" : "?>-->
|
|
<varlistentry>
|
|
<term><parameter>Name</parameter></term>
|
|
<listitem>Menu item label for this command.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Command</parameter></term>
|
|
<listitem>Shell command to execute when the menu item is activated. <code>%f</code> will
|
|
be replaced with full path of the selected file; if more than one file is selected then
|
|
the command will be executed for each file one by one. If <parameter>command</parameter>
|
|
contains <code>%F</code> and several files are selected then <code>%F</code> will be
|
|
replaced with the space-separated list of paths of all selected files. If a single file
|
|
is selected then <code>%f</code> and <code>%F</code> behave in the same way.
|
|
Example: <code>firefox %f</code>, <code>glade %F</code></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Extensions</parameter></term>
|
|
<listitem>Semicolon-separated list of file patterns to define for which files this command
|
|
is available, e.g. <code>*.c;*.h</code>. Use <code>*</code> if the command should
|
|
be available for all files.</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Mime types</parameter></term>
|
|
<listitem>Semicolon-separated list of mime types to define for which files this command
|
|
is available, e.g. <code>application/docbook+xml;application/x-glade</code>. Leave it empty
|
|
if <parameter>Extensions</parameter> entry defines whether the command should be enabled.</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<informalexample>
|
|
<graphic fileref="img/prefs-file-selector.png" align="center"/>
|
|
</informalexample>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="section-editing-options">
|
|
<title>Options for editing text</title>
|
|
<para>
|
|
&medit; has some editing options which can be set in the document text,
|
|
or in the <guilabel>Preferences</guilabel> dialog for sets of files or for given syntax
|
|
highlighting language.
|
|
</para>
|
|
<para>
|
|
To set the options in the document text, place the following on the first,
|
|
second or the last line of the document:
|
|
<programlisting>
|
|
-%- <parameter>options</parameter> -%-
|
|
</programlisting>
|
|
where <parameter>options</parameter> is the option string
|
|
<programlisting>
|
|
<parameter>key</parameter>: <parameter>value</parameter>; <parameter>key</parameter>: <parameter>value</parameter>; ...
|
|
</programlisting>
|
|
(the latter is the format used also in the <guilabel>Preferences</guilabel> dialog).
|
|
</para>
|
|
<para>
|
|
For example, the following might be the first line in a C file:
|
|
<programlisting>
|
|
/* -%- indent-width: 2; use-tabs: yes; strip: yes -%- */
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Values can be strings, integers, or booleans.
|
|
</para>
|
|
<para>
|
|
Booleans are <code>yes</code>, <code>no</code>, <code>true</code>, <code>false</code>, <code>1</code>, <code>0</code>.
|
|
</para>
|
|
<para>
|
|
If a string value contains <code>:</code> character, then the following syntax may be used:
|
|
<code><parameter>key</parameter>=/<parameter>value</parameter>/</code>. Any character may be used instead of slash (and it
|
|
must not occur in the <parameter>value</parameter>). Example: <code>word-chars=@-/:@</code>
|
|
</para>
|
|
<para>
|
|
The following options are available:
|
|
<variablelist>
|
|
<?dbhtml list-presentation="table"?>
|
|
<?dbhtml term-separator=" : "?>
|
|
<varlistentry>
|
|
<term><code>lang</code></term>
|
|
<listitem><para>syntax highlighting language to use in this document. Special value <code>none</code> will
|
|
turn off syntax highlighting in this document.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>strip</code></term>
|
|
<listitem><para>a boolean value, whether trailing whitespace should be removed from the document on save.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>add-newline</code></term>
|
|
<listitem><para>a boolean value, whether the editor should ensure that saved files have a trailing new line character.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>indent-width</code></term>
|
|
<listitem><para>an integer specifying indentation offset used when the Tab key is pressed to indent text.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>tab-width</code></term>
|
|
<listitem><para>displayed width of the tab character. Note that this is <emphasis>not</emphasis> the same as
|
|
<code>indent-width</code>.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>use-tabs</code></term>
|
|
<listitem><para>whether tab character should be used for indentation.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
&medit; 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.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<sect1 id="section-prefs-xml">
|
|
<title>Preferences files</title>
|
|
<para>
|
|
&medit; preferences are stored in &medit-prefs-xml-unix; file.
|
|
It is an XML file which may be edited to set preferences which have not found
|
|
their place in the <guilabel>Preferences</guilabel> dialog.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
&medit; reads the preferences file on startup and writes it whenever <guilabel>OK</guilabel>
|
|
or <guilabel>Apply</guilabel> button is clicked in the <guilabel>Preferences</guilabel> dialog. Therefore, if you
|
|
modify the preferences file, your changes may be overwritten, and they not take
|
|
effect until you restart &medit;.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
The following "hidden" settings are available:
|
|
<variablelist>
|
|
<?dbhtml term-separator=" : "?>
|
|
<varlistentry>
|
|
<term><parameter>Editor/window_title</parameter></term>
|
|
<listitem><para>Format of the window title. It is a string which may
|
|
contain format sequences, which are percent sign followed by a character:
|
|
<variablelist>
|
|
<?dbhtml list-presentation="table"?>
|
|
<?dbhtml term-separator=" : "?>
|
|
<varlistentry>
|
|
<term><code>%a</code></term>
|
|
<listitem>application name</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>%b</code></term>
|
|
<listitem>current document basename</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>%f</code></term>
|
|
<listitem>full path of the current document</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>%u</code></term>
|
|
<listitem>URI of the current document</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>%s</code></term>
|
|
<listitem>the status of the current document, e.g. "<code> [modified]</code>". It is prefixed
|
|
with a space, so that "<code>%b%s</code>" produces a nice string</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><code>%%</code></term>
|
|
<listitem>the percent character</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
Default value is "<code>%a - %f%s</code>" which produces something like "<code>medit - /home/user/file [modified]</code>".
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>Editor/window_title_no_doc</parameter></term>
|
|
<listitem><para>same as <parameter>Editor/window_title</parameter>, used when no document is open.
|
|
Default value is "<code>%a</code>".</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</sect1>
|
|
|
|
</chapter>
|