PageRenderTime 179ms CodeModel.GetById 161ms app.highlight 11ms RepoModel.GetById 0ms app.codeStats 1ms

/jEdit/tags/jedit-4-5-pre1/doc/users-guide/customizing.xml

#
XML | 713 lines | 554 code | 150 blank | 9 comment | 0 complexity | 93478b064e80013079f3307e719ad5e5 MD5 | raw file
  1<?xml version="1.0" encoding="UTF-8"?>
  2<chapter id="customizing">
  3    <title>Customizing jEdit</title>
  4    <!-- jEdit buffer-local properties: -->
  5    <!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=0: -->
  6    <!-- :xml.root=users-guide.xml: -->
  7
  8    <section id="buffer-opts">
  9        <title>The Buffer Options Dialog Box</title>
 10
 11        <para><guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
 12        Options</guimenuitem> displays a dialog box for changing editor settings
 13        on a per-buffer basis. Changes made in this dialog box are not retained
 14        after the buffer is closed.</para>
 15
 16        <para>The following settings can be changed here:</para>
 17
 18        <itemizedlist>
 19            <listitem>
 20                <para>The line separator (see <xref
 21                linkend="line-separators" />)</para>
 22            </listitem>
 23
 24            <listitem>
 25                <para>The character encoding (see <xref
 26                linkend="encodings" />)</para>
 27            </listitem>
 28
 29            <listitem>
 30                <para>If the file should be GZipped on disk (see <xref
 31                linkend="opening" />)</para>
 32            </listitem>
 33
 34            <listitem>
 35                <para>The edit mode (see <xref linkend="modes" />)</para>
 36            </listitem>
 37
 38            <listitem>
 39                <para>The fold mode (see <xref linkend="folding" />)</para>
 40            </listitem>
 41
 42            <listitem>
 43                <para>The wrap mode and margin (see <xref
 44                linkend="word-wrap" />)</para>
 45            </listitem>
 46
 47            <listitem>
 48                <para>The tab width (see <xref linkend="indent" />)</para>
 49            </listitem>
 50
 51            <listitem>
 52                <para>The indent width</para>
 53            </listitem>
 54
 55            <listitem>
 56                <para>If soft tabs should be used (see <xref
 57                linkend="indent" />)</para>
 58            </listitem>
 59        </itemizedlist>
 60    </section>
 61
 62    <section id="buffer-local">
 63        <title>Buffer-Local Properties</title>
 64
 65        <para>Buffer-local properties provide an alternate way to change editor
 66        settings on a per-buffer basis. While changes made in the
 67        <guimenuitem>Buffer Options</guimenuitem> dialog box are lost after the
 68        buffer is closed, buffer-local properties take effect each time the file
 69        is opened, because they are embedded in the file itself.</para>
 70
 71        <para>When jEdit loads a file, it checks the first and last 10 lines for
 72        colon-enclosed name/value pairs. For example, placing the following in a
 73        buffer changes the indent width to 4 characters, enables soft tabs, and
 74        activates the Perl edit mode:</para>
 75
 76        <screen>:indentSize=4:noTabs=true:mode=perl:</screen>
 77
 78        <para>Adding buffer-local properties to a buffer takes effect after the
 79        next time the buffer is saved.</para>
 80
 81        <para>The following table describes each buffer-local property in
 82        detail.</para>
 83
 84        <informaltable>
 85            <tgroup cols="2">
 86                <colspec colnum="1" colwidth="1.5in" />
 87                <colspec colwidth="1*"/>
 88
 89                <thead>
 90                    <row>
 91                        <entry>Property name</entry>
 92
 93                        <entry>Description</entry>
 94                    </row>
 95                </thead>
 96
 97                <tbody>
 98                    <row>
 99                        <entry><varname>collapseFolds</varname></entry>
100
101                        <entry>Folds with a level of this or higher will be
102                        collapsed when the buffer is opened. If set to zero, all
103                        folds will be expanded initially. See <xref
104                        linkend="folding" />.</entry>
105                    </row>
106
107                    <row>
108                        <entry><varname>deepIndent</varname></entry>
109
110                        <entry>When set to <quote>true</quote>, multiple-line
111                        expressions delimited by parentheses are aligned like
112                        so: <programlisting>retVal.x = (int)(horizontalOffset
113    + Chunk.offsetToX(info.chunks,
114                      offset));</programlisting> With this setting disabled, the
115                        text would look like so: <programlisting>retVal.x = (int)(horizontalOffset
116    + Chunk.offsetToX(info.chunks,
117    offset));</programlisting></entry>
118                    </row>
119
120                    <row><entry><varname>encoding</varname></entry>
121                    <entry> The character encoding that should be used for this file
122                    (only works if at the top of file). 
123                    See <xref linkend="encodings"/>. </entry></row>
124
125                    <row>
126                        <entry><varname>folding</varname></entry>
127
128                        <entry>The fold mode; one of <quote>none</quote>,
129                        <quote>indent</quote>, <quote>explicit</quote>, or the
130                        name of a plugin folding mode. See <xref
131                        linkend="folding" />.</entry>
132                    </row>
133
134                    <row>
135                        <entry><varname>indentSize</varname></entry>
136
137                        <entry>The width, in characters, of one indent. Must be
138                        an integer greater than 0. See <xref
139                        linkend="indent" />.</entry>
140                    </row>
141
142                    <row>
143                        <entry><varname>maxLineLen</varname></entry>
144
145                        <entry>The maximum line length and wrap column position.
146                        Inserting text beyond this column will automatically
147                        insert a line break at the appropriate position. See
148                        <xref linkend="entering-text" />.</entry>
149                    </row>
150
151                    <row>
152                        <entry><varname>mode</varname></entry>
153
154                        <entry>The default edit mode for the buffer. See <xref
155                        linkend="modes" />.</entry>
156                    </row>
157
158                    <row>
159                        <entry><varname>noTabs</varname></entry>
160
161                        <entry>If set to <quote>true</quote>, soft tabs
162                        (multiple space characters) will be used instead of
163                        <quote>real</quote> tabs. See <xref
164                        linkend="indent" />.</entry>
165                    </row>
166
167                    <row>
168                        <entry><varname>noWordSep</varname></entry>
169
170                        <entry>A list of non-alphanumeric characters that are
171                        <emphasis>not</emphasis> to be treated as word
172                        separators. Global default is <quote>_</quote>.</entry>
173                    </row>
174
175                    <row>
176                        <entry><varname>tabSize</varname></entry>
177
178                        <entry>The tab width. Must be an integer greater than 0.
179                        See <xref linkend="indent" />.</entry>
180                    </row>
181
182                    <row>
183                        <entry><varname>wordBreakChars</varname></entry>
184
185                        <entry>Characters, in addition to spaces and tabs, at
186                        which lines may be split when word wrapping. See <xref
187                        linkend="entering-text" />.</entry>
188                    </row>
189
190                    <row>
191                        <entry><varname>wrap</varname></entry>
192
193                        <entry>The word wrap mode; one of <quote>none</quote>,
194                        <quote>soft</quote>, or <quote>hard</quote>. See <xref
195                        linkend="word-wrap" />.</entry>
196                    </row>
197                </tbody>
198            </tgroup>
199        </informaltable>
200    </section>
201
202    <section id="global-opts">
203        <title>The Global Options Dialog Box</title>
204
205        <para><guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
206        Options</guimenuitem> displays the global options dialog box. The dialog
207        box is divided into several panes, each pane containing a set of related
208        options. Use the list on the left of the dialog box to switch between
209        panes. Only panes created by jEdit are described here; some plugins add
210        their own option panes, and information about them can be found in the
211        documentation for the plugins in question.</para>
212
213        <section id="general-pane">
214            <title>The General Pane</title>
215            <para>The <guibutton>General</guibutton> pane contains various
216            settings, such as
217            the number of recent files to remember,
218            how often to check for changed files,
219            if the recent file list should be sorted,
220            if previously open files or split configurations should be restored on startup, and so on.</para>
221        </section>
222
223        <section id="abbrevs-pane">
224            <title>The Abbreviations Pane</title>
225
226            <indexterm>
227                <primary>Abbreviations</primary>
228
229                <secondary>creating and editing</secondary>
230            </indexterm>
231
232            <para>The <guibutton>Abbreviations</guibutton> option pane can be
233            used to enable or disable automatic abbreviation expansion, and to
234            edit currently defined abbreviations.</para>
235
236            <para>The combo box labelled <quote>Abbrev set</quote> selects the
237            abbreviation set to edit. The first entry, <quote>global</quote>,
238            contains abbreviations available in all edit modes. The subsequent
239            entries correspond to each mode's local set of abbreviations.</para>
240
241            <para>To change an abbreviation or its expansion, either
242            double-click the appropriate table entry, or click a table entry and
243            then click the <guibutton>Edit</guibutton> button. This will display
244            a dialog box for modifying the abbreviation.</para>
245
246            <para>The <guibutton>Add</guibutton> button displays a dialog box
247            where you can define a new abbreviation. The
248            <guibutton>Remove</guibutton> button removes the currently selected
249            abbreviation from the list.</para>
250
251            <para>See <xref linkend="positional-params" /> for information about
252            positional parameters in abbreviations.</para>
253        </section>
254
255        <section id="appearance-pane">
256            <title>The Appearance Pane</title>
257
258            <para>The <guibutton>Appearance</guibutton> pane can be used to
259            change the appearance of user interface controls such as buttons,
260            labels and menus. It can also be used to change the docking
261            framework (the dockable window manager). The number of items
262            retained in history text fields can also be set here; see
263            <xref linkend="history" />.</para>
264
265        </section>
266
267
268        <section id="context-pane">
269            <title>The Context Menu Pane</title>
270
271            <para>The <guibutton>Context Menu</guibutton> option pane edits the
272            text area's right-click context menu. See <xref
273            linkend="views" />.</para>
274        </section>
275
276        <section id="docking-pane">
277            <title>The Docking Pane</title>
278
279            <para>The <guibutton>Docking</guibutton> option pane shows a
280            list of available dockables, and allows you to specify
281            docking locations for each of them. Another way to
282            specify docking locations is to use the popup menus associated with each dockable window. </para>
283
284            <para> It is possible to configure jEdit to automatically load and/or save <emphasis role="bold">Docking Layouts</emphasis> (similar to eclipse perspectives) based on the edit mode of your current b uffer through the checkboxes in this pane. See <xref linkend="docking" />.
285            </para>
286
287
288        </section>
289
290        <section id="editing-pane">
291            <title>The Editing Pane</title>
292
293            <para>The <guibutton>Editing</guibutton> option pane contains
294            settings such as the tab size, syntax highlighting and soft tabs on
295            a global or mode-specific basis. </para>
296
297            <para>Changing options from this optionpane does not change XML mode definition files on disk; it merely writes values to the user properties file which
298            override those set in mode files. To find out how to edit mode files directly, see <xref linkend="writing-modes-part" />. Some of these options can be further overridden on an individual file basis through the use of buffer-local properties. </para>
299
300            <para>The <literal>File name
301            glob</literal> and <literal>First line glob</literal> text
302            fields let you specify a glob pattern that names and first lines of
303            buffers will be matched against to determine the edit mode. See
304            <xref linkend="globs" /> for information about glob patterns.</para>
305
306            <para> The <literal>Extra Word Characters</literal> allows you to set the <literal>noLineSep</literal> buffer property on a mode-wide basis, allowing you to define what is considered part of a word when double-clicking on it in the text area.
307            </para>
308
309            <para> The <literal>Deep Indent</literal> option instructs jEdit to indent subsequent lines so that they line up with the open bracket on the previous line. </para>
310
311
312        </section>
313
314        <section id="encodings-pane">
315            <title>The Encodings Pane</title>
316
317            <para>This option pane offers
318            users of jEdit many flexible options for defining how Encodings are handled in jEdit. See <xref linkend="encodings" /> for the
319            basics.</para>
320
321            <para>The default line separator character (see <xref linkend="line-separators" />) can be set from here. </para>
322
323            <para> <guilabel>Use autodetection when possible</guilabel> is an option you can switch on or off.</para>
324
325            <para>The <literal>List of Encoding Autodetector Names</literal>
326            can be used to control what encoding detections are used on each file when it is loaded.
327            The order they appear in this list determines the order of detectors that are tried.
328            There are some detectors which are available with jEdit core:
329            <itemizedlist>
330              <listitem><para>
331                <literal>BOM</literal>:
332                detects <ulink url="http://www.unicode.org/faq/utf_bom.html#BOM">
333                Byte Order Mark</ulink>.
334              </para></listitem>
335              <listitem><para>
336                <literal>XML-PI</literal>:
337                detects <ulink url="http://www.w3.org/TR/REC-xml/#charencoding">
338                encoding declaration in XML Processing Instruction</ulink>.
339              </para></listitem>
340              <listitem><para>
341                <literal>html</literal>:
342                detects <ulink url="http://www.w3.org/TR/html4/struct/global.html#edef-META">
343                charset description in HTML META element</ulink>.
344              </para></listitem>
345              <listitem><para>
346                <literal>python</literal>:
347                detects <ulink url="http://docs.python.org/reference/lexical_analysis.html#encoding-declarations">
348                various encoding declaration accepted in Python</ulink>. This
349                accepts encoding declarations for GNU Emacs or Bram Moolenaar's
350                VIM.
351              </para></listitem>
352              <listitem><para>
353                <literal>buffer-local-property</literal>:
354                detects same syntax described at <xref linkend="buffer-local" />
355                for property name "encoding". Note that unlike other buffer-local
356                properties, this one will not work unless it is at the top of the file.
357              </para></listitem>
358            </itemizedlist>
359            Others can be defined in plugins as services and added to this
360            space-separated list. See <ulink
361            url="../api/org/gjt/sp/jedit/io/EncodingDetector.html">EncodingDetector</ulink>
362            for details on how to offer additional encoding autodetector.</para>
363
364            <para>The <literal>List of Fallback Encodings</literal> is used when
365            a file fails to open in the default encoding, and the Encoding
366            Autodetectors also fail. The list order here determines the order of
367            encodings that are tried. Each is separated by a space. This is
368            especially handy when doing directory searches through files of
369            different encodings. We suggest using <literal>UTF-8</literal> as
370            either your default or one of the fallback encodings.</para>
371
372            <para>While jEdit allows you to edit files in a variety of different
373            encodings, the average user switches between only 2 or 3. In other
374            parts of jEdit, where the list of encodings is displayed in a
375            combobox (such as the buffer options) or a menu (such as
376            <guimenuitem>File - Reload with Encoding</guimenuitem> submenu) it
377            may be desirable to display only a subset of available encodings,
378            those that are in common local use. The Encodings checkbox list
379            allows the user to select the subset of supported encodings to
380            display in other GUI components that list all of the
381            encodings.</para>
382        </section>
383
384        <section id="gutter-pane">
385            <title>The Gutter Pane</title>
386
387            <para>The <guibutton>Gutter</guibutton> option pane contains
388            settings to customize the appearance of the gutter. Some new options were added
389            to jEdit 4.3, including "show gutter", "minimal number of digits to reserve for line numbers",
390            and "fold style".  See <xref linkend="overview" />.</para>
391        </section>
392
393        <section id="mouse-pane">
394            <title>The Mouse Pane</title>
395
396            <para>The <guibutton>Mouse</guibutton> option pane contains settings
397            for toggling drag and drop of text, as well as gutter mouse click
398            behavior.</para>
399
400            <para> The only option that may not be self-explanatory is the  <emphasis role="bold">Double-Click drag joins non-alphanumeric characters</emphasis>. This option means that double-click will select a region that includes the non-alphabetical characters, as defined for the current mode. The actual set of characters can be defined for an indiviual file via buffer-local properties (<literal>noWordSep</literal>) or on a mode-wide basis from the Editing option pane (<literal>Extra Word Characters</literal>).  </para>
401
402        </section>
403
404        <section id="printing-pane">
405            <title>The Printing Pane</title>
406
407            <para>The <guibutton>Printing</guibutton> option pane contains
408            settings to control the appearance of printed output. Workarounds
409            that might be needed for your Java version to print correctly can
410            also be enabled here. See <xref linkend="printing" />.</para>
411        </section>
412
413        <section id="pluginmgr-pane">
414            <title>The Plugin Manager Pane</title>
415
416            <para>The <guibutton>Plugin Manager</guibutton> pane contains a
417            chooser for the desired download mirror, as well as various settings
418            such as the directory where plugins are to be installed. In addition, you can set the time in minutes that the pluginlist can be cached from jedit.org, helping to reduce the server load. See <xref
419            linkend="using-plugins" />.</para>
420        </section>
421
422        <section id="firewall-pane">
423            <title>The Proxy Servers Pane</title>
424
425            <para>The <guibutton>Proxy Servers</guibutton> option pane lets you
426            specify HTTP and SOCKS proxy servers to use when jEdit makes network
427            connections, for example when downloading plugins.</para>
428        </section>
429
430        <section id="autosave-backups-pane">
431            <title>The Saving and Backup Pane</title>
432
433            <para>The <guibutton>Saving and Backup</guibutton> option pane contains
434            settings for the autosave and backup features. See <xref
435            linkend="autosave" /> and <xref linkend="backups" />.</para>
436        </section>
437
438        <section id="shortcuts-pane">
439            <title>The Shortcuts Pane</title>
440
441            <para>The <guibutton>Shortcuts</guibutton> option pane associates
442            keyboard shortcuts with commands. Each command can have up to two
443            shortcuts associated with it.</para>
444
445            <para>The combo box at the top of the option pane selects the
446            command set to edit. Command sets include the set of all built-in
447            commands, the commands of each plugin, and the set of macros.</para>
448
449            <para>To change a shortcut, click the appropriate table entry and
450            press the keys you want associated with that command in the
451            resulting dialog box. The dialog box will warn you if the shortcut
452            is already assigned.</para>
453
454            <bridgehead> 2-key shortcut prefixes </bridgehead>
455
456            <para> Some shortcuts, such as C+e, C+m, and C+r, are prefixes for two-keystroke shortcuts. Another  keystroke may be used as a prefix in a 2-key shortcut, so for example, C+x can be redefined as a prefix to make it more emacs-like, by mapping any other action to a C+x prefixed shortcut.</para>
457
458            <para> Conversely, emacs users will notice at first that C+e can not be mapped as a single key shortcut to go to the end of the line, unless all of the other actions that contain C+e prefixed shortcuts are remapped to other shortcuts first. After that, C+e can be bound to end-of-line. </para>
459
460            <para> The default shortcuts can be found in  <literal>jedit_keys.props</literal>. </para>
461
462        </section>
463
464        <section id="status-bar-pane">
465            <title>The Status Bar Pane</title>
466
467            <para>The <guibutton>Status Bar</guibutton>, its API, and its coprresponding option pane were redesigned in jEdit 4.3. Now, the pane contains settings to customize which widgets are in the status bar, their order, and what separators exist between them. Or, you can disable it completely, for regular and/or plain views. See <xref linkend="status-bar" />.</para>
468
469            <para> From the <literal>Options</literal> tab, you can
470            customize information about the caret display in the lower
471            left corner. </para>
472
473            <para> Selecting the <literal>Widgets</literal> tab of this option pane shows you what widgets on the right, and their order. You can add or remove widgets and separators/labels here. </para>
474
475        </section>
476
477
478        <section id="syntax-hilite-pane">
479            <title>The Syntax Highlighting Pane</title>
480
481            <para>The <guibutton>Syntax Highlighting</guibutton> pane can be
482            used to customize the fonts and colors for syntax highlighting. See
483            <xref linkend="syntax-hilite" />.</para>
484        </section>
485
486        <section id="text-area-pane">
487            <title>The Text Area Pane</title>
488
489            <para>The <guibutton>Text Area</guibutton> pane contains settings to
490            customize the appearance of the text area. See <xref
491            linkend="overview" />.</para>
492        </section>
493
494        <section id="toolbar-pane">
495            <title>The Tool Bar Pane</title>
496
497            <para>The <guibutton>Tool Bar</guibutton> option pane lets you edit
498            the tool bar, or disable it completely. See <xref
499            linkend="views" />.</para>
500        </section>
501
502        <section id="view-pane">
503            <title>The View Pane</title>
504
505            <para>The <guibutton>View</guibutton> option pane lets you change
506            various settings related to the editor window's appearance,
507            including the arrangement of dockable windows, and if the search bar
508            and buffer switcher should be visible. See <xref
509            linkend="views" />.</para>
510        </section>
511
512        <section id="vfs-browser-pane">
513            <title>The File System Browser Panes</title>
514
515            <para>The <guibutton>File System Browser</guibutton> group contains
516            two option panes, <guibutton>General</guibutton> and
517            <guibutton>Colors</guibutton>. The former contains various file
518            system browser settings. The latter configures glob patterns used
519            for coloring the file list. See <xref linkend="vfs-browser" /> for
520            more information.</para>
521        </section>
522    </section>
523
524    <section id="settings-directory">
525        <title>The jEdit Settings Directory</title>
526
527        <para>jEdit stores settings, macros, and plugins as files inside the
528        <firstterm>settings directory</firstterm>. In most cases, editing these
529        files by hand is not necessary, since graphical tools and editor
530        commands can do the job. However, being familiar with the structure of
531        the settings directory still comes in handy in certain situations, for
532        example when you want to copy jEdit settings between computers.</para>
533
534        <para>The location of the settings directory is system-specific; it is
535        printed to the activity log
536        (<guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>Activity
537        Log</guimenuitem>). For example:</para>
538
539        <screen>[message] jEdit: Settings directory is /home/slava/.jedit</screen>
540
541        <para>Another way to find the location of your settings directory is to
542        use the "Utilities" menu, then the "Settings Directory" menu item. The
543        first item in the pullout menu is the location of your settings directory.
544        </para>
545
546        <para>Specifying the <userinput>-settings</userinput> switch on the
547        command line instructs jEdit to store settings in a directory other than
548        the default. For example, the following command will instruct jEdit to
549        store all settings in the <filename>jedit</filename> subdirectory of the
550        <filename>C:</filename> drive:</para>
551
552        <screen><prompt>C:\jedit&gt;</prompt> <userinput>jedit -settings=C:\jedit</userinput></screen>
553
554        <para>The <userinput>-nosettings</userinput> switch will force jEdit to
555        not look for or create a settings directory; default settings will be
556        used instead.</para>
557
558        <!-- para>
559   If you are using <application>jEditLauncher</application>
560   to start jEdit on Windows, these parameters cannot be specified on the
561   MS-DOS prompt command line when starting jEdit; they must be set as described
562   in <xref linkend="launcher-starting" />.
563  </para -->
564
565        <para>jEdit creates the following files and directories inside the
566        settings directory; plugins may add more:</para>
567
568        <itemizedlist>
569            <listitem>
570                <para><filename>abbrevs</filename> - a plain text file which
571                stores all defined abbreviations. See <xref
572                linkend="abbrevs" />.</para>
573            </listitem>
574
575            <listitem>
576                <para><filename>activity.log</filename> - a plain text file
577                which contains the full activity log. See <xref
578                linkend="activity-log" />.</para>
579            </listitem>
580
581            <listitem>
582                <para><filename>history</filename> - a plain text file which
583                stores history lists, used by history text fields and the
584                <guimenu>Edit</guimenu>&gt;<guimenuitem>Paste
585                Previous</guimenuitem> command. See <xref
586                linkend="text-transfer" /> and <xref
587                linkend="history" />.</para>
588            </listitem>
589
590            <listitem>
591                <para><filename>jars</filename> - this directory contains
592                plugins. See <xref linkend="using-plugins" />.</para>
593            </listitem>
594
595            <listitem>
596                <para><filename>jars-cache</filename> - this directory contains
597                plugin cache files which decrease the time to start jEdit. They
598                are automatically updated when plugins are installed or
599                updated.</para>
600            </listitem>
601
602            <listitem>
603                <para><filename>killring.xml</filename> - stores recently
604                deleted text. See <xref linkend="text-transfer" />.</para>
605            </listitem>
606
607            <listitem>
608                <para><filename>macros</filename> - this directory contains
609                macros. See <xref linkend="using-macros" />.</para>
610            </listitem>
611
612            <listitem>
613                <para><filename>modes</filename> - this directory contains
614                custom edit modes. See <xref
615                linkend="writing-modes-part" />.</para>
616            </listitem>
617
618            <listitem>
619                <para><filename>perspective.xml</filename> - an XML file that
620                stores the list of open buffers and views used to maintain
621                editor state between sessions.</para>
622            </listitem>
623
624            <listitem>
625                <para><filename>PluginManager.download</filename> - this
626                directory is usually empty. It only contains files while the
627                plugin manager is downloading a plugin. For information about
628                the plugin manager, see <xref linkend="using-plugins" />.</para>
629            </listitem>
630            <listitem><para>
631              <filename>pluginMgr-Cached.xml.gz</filename> -
632                this contains a cached copy of the last XML plugin list downloaded from plugin central. If you delete this file, a new one will be created next time you try to install a plugin via Plugin Manager. </para>
633            </listitem>
634
635            <listitem>
636                <para><filename>printspec</filename> - a binary file that stores
637                printing settings when running under Java 2 version 1.4.</para>
638            </listitem>
639
640            <listitem>
641                <para><filename>properties</filename> - a plain text file that
642                stores the majority of jEdit's and its plugins settings. For
643                more information see <xref linkend="propertiesfile" />.</para>
644            </listitem>
645
646            <listitem>
647                <para><filename>recent.xml</filename> - an XML file which stores
648                the list of recently opened files. jEdit remembers the caret
649                position and character encoding of each recent file, and
650                automatically restores those values when one of the files is
651                opened.</para>
652            </listitem>
653
654            <listitem>
655                <para><filename>registers.xml</filename> - an XML file that
656                stores register contents. See <xref linkend="registers" /> for
657                more information about registers.</para>
658            </listitem>
659
660            <listitem>
661                <para><filename>server</filename> - a plain text file that only
662                exists while jEdit is running. The edit server's port number and
663                authorization key is stored here. See <xref
664                linkend="starting" />.</para>
665            </listitem>
666
667            <listitem>
668                <para><filename>settings-backup</filename> - this directory
669                contains numbered backups of all automatically-written settings
670                files.</para>
671            </listitem>
672        </itemizedlist>
673
674        <section id="propertiesfile">
675            <title>The jEdit properties file</title>
676
677            <para>The jEdit <literal>properties</literal> file uses the Java
678            properties syntax to store key/value pairs. All of the values are
679            stored as strings, but are interpreted as other types (such as
680            integer or boolean) by plugins at runtime.</para>
681
682            <para>Do not edit this file while jEdit is running. If you do, it
683            is possible that your changes will be lost since jEdit writes to this
684            this file frequently.</para>
685        </section>
686
687        <section id="sitepropertiesfiles">
688            <title>Site Properties</title>
689            <para>
690                You may also put properties files in the "properties" directory in
691                the jEdit home directory (NOT the .jedit settings directory). You
692                can locate the jEdit home directory by going to the Utilities menu
693                directory, then the "jEdit Home Directory" menu item, and the first
694                item in the pullout menu will be the location of the jEdit home
695                directory. This is intended for site-wide settings and it is
696                useful for things like a set of custom key bindings that you might
697                want to share between different computers. This lets you keep your
698                custom properties separate from the jEdit properties, so they are
699                easier to find, edit, and move between machines. Note that your
700                custom properties files must have ".props" as the file name extension.
701            </para>
702            <para>
703                Site properties files are read in alphabetically by file name. This means
704                that if you have a property with the same name in more than one file,
705                the value for that property will be the value found in the last file
706                that was read.
707            </para>
708            <para>
709                You can edit these files inside jEdit - changes made to these files will not be re-read until the next time jEdit is started.
710            </para>
711        </section>
712    </section>
713</chapter>