PageRenderTime 119ms CodeModel.GetById 68ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-2-pre14/doc/users-guide/customizing.xml

#
XML | 391 lines | 387 code | 1 blank | 3 comment | 0 complexity | e5727d59aafad779b28ce13d0cce807f MD5 | raw file
  1<!-- jEdit buffer-local properties: -->
  2<!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
  3<!-- :xml.root=users-guide.xml: -->
  4
  5<chapter id="customizing"><title>Customizing jEdit</title>
  6 <sect1 id="buffer-opts"><title>The Buffer Options Dialog Box</title>
  7  <para>
  8   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
  9   displays a dialog box for changing editor settings on a per-buffer basis.
 10   Changes made in this dialog box are not retained after the buffer is
 11   closed.
 12  </para>
 13  <para>
 14   The following settings can be changed here:
 15  </para>
 16  <itemizedlist>
 17   <listitem><para>The line separator (see <xref linkend="line-separators" />)
 18   </para></listitem>
 19   <listitem><para>The character encoding (see <xref linkend="encodings" />)
 20   </para></listitem>
 21   <listitem><para>If the file should be GZipped on disk
 22   (see <xref linkend="opening" />)
 23   </para></listitem>
 24   <listitem><para>The edit mode (see <xref linkend="modes" />)</para></listitem>
 25   <listitem><para>The fold mode (see <xref linkend="folding" />)</para></listitem>
 26   <listitem><para>The wrap mode and margin (see <xref linkend="word-wrap" />)
 27   </para></listitem>
 28   <listitem><para>The tab width (see <xref linkend="indent" />)</para></listitem>
 29   <listitem><para>The indent width</para></listitem>
 30   <listitem><para>If soft tabs should be used
 31   (see <xref linkend="indent" />)
 32   </para></listitem>
 33  </itemizedlist>
 34 </sect1>
 35 <sect1 id="buffer-local"><title>Buffer-Local Properties</title>
 36  <para>
 37   Buffer-local properties provide an alternate way to change editor settings
 38   on a per-buffer basis. While changes made in the <guimenuitem>Buffer
 39   Options</guimenuitem> dialog box
 40   are lost after the buffer is closed, buffer-local properties take effect
 41   each time the file is opened, because they are embedded in the file
 42   itself.
 43  </para>
 44  <para>
 45   When jEdit loads a file, it checks the first and last 10 lines for
 46   colon-enclosed name/value pairs. For example, placing the following in
 47   a buffer changes
 48   the indent width to 4 characters, enables soft tabs, and activates the
 49   Perl edit mode:
 50  </para>
 51  <screen>:indentSize=4:noTabs=true:mode=perl:</screen>
 52  <para>
 53   Adding buffer-local properties to a buffer
 54   takes effect after the next time the buffer is saved.
 55  </para>
 56  <para>
 57   The following table describes each buffer-local property in detail.
 58  </para>
 59  <informaltable>
 60   <tgroup cols="2">
 61    <colspec colnum="1" colwidth="1.5in" />
 62    <thead>
 63     <row>
 64      <entry>Property name</entry>
 65      <entry>Description</entry>
 66     </row>
 67    </thead>
 68    <tbody>
 69     <row>
 70      <entry><varname>collapseFolds</varname></entry>
 71      <entry>Folds with a level of this or higher will be collapsed when the
 72      buffer is opened. If set to zero, all folds will be expanded initially.
 73      See <xref linkend="folding" />.</entry>
 74     </row>
 75     <row>
 76      <entry><varname>deepIndent</varname></entry>
 77      <entry>When set to <quote>true</quote>, multiple-line expressions delimited by parentheses are aligned like so:
 78      <programlisting>retVal.x = (int)(horizontalOffset
 79    + Chunk.offsetToX(info.chunks,
 80                      offset));</programlisting>
 81      With this setting disabled, the text would look like so:
 82      <programlisting>retVal.x = (int)(horizontalOffset
 83    + Chunk.offsetToX(info.chunks,
 84    offset));</programlisting>
 85      </entry>
 86     </row>
 87     <row>
 88      <entry><varname>folding</varname></entry>
 89      <entry>The fold mode; one of <quote>none</quote>, <quote>indent</quote>,
 90      <quote>explicit</quote>, or the name of a plugin folding mode.
 91      See <xref linkend="folding" />.</entry>
 92     </row>
 93     <row>
 94      <entry><varname>indentSize</varname></entry>
 95      <entry>The width, in characters, of one indent.
 96      Must be an integer greater than 0.
 97      See <xref linkend="indent" />.</entry>
 98     </row>
 99     <row>
100      <entry><varname>maxLineLen</varname></entry>
101      <entry>The maximum line length and wrap column position.
102      Inserting text beyond this column will automatically insert a line
103      break at the appropriate position.
104      See <xref linkend="entering-text" />.</entry>
105     </row>
106     <row>
107      <entry><varname>mode</varname></entry>
108      <entry>The default edit mode for the buffer.
109      See <xref linkend="modes" />.</entry>
110     </row>
111     <row>
112      <entry><varname>noTabs</varname></entry>
113      <entry>If set to <quote>true</quote>, soft tabs (multiple space characters)
114      will be used instead of <quote>real</quote> tabs. See
115      <xref linkend="indent" />.</entry>
116     </row>
117     <row>
118      <entry><varname>noWordSep</varname></entry>
119      <entry>A list of non-alphanumeric characters that are
120      <emphasis>not</emphasis> to
121      be treated as word separators. Global default is <quote>_</quote>.</entry>
122     </row>
123     <row>
124      <entry><varname>tabSize</varname></entry>
125      <entry>The tab width. Must be an integer greater than 0.
126      See <xref linkend="indent" />.</entry>
127     </row>
128     <row>
129      <entry><varname>wordBreakChars</varname></entry>
130      <entry>Characters, in addition to spaces and tabs, at which lines may be
131      split when word wrapping.
132      See <xref linkend="entering-text" />.</entry>
133     </row>
134     <row>
135      <entry><varname>wrap</varname></entry>
136      <entry>The word wrap mode; one of <quote>none</quote>, <quote>soft</quote>,
137      or <quote>hard</quote>. See <xref linkend="word-wrap" />.</entry>
138     </row>
139    </tbody>
140   </tgroup>
141  </informaltable>
142 </sect1>
143 <sect1 id="global-opts"><title>The Global Options Dialog Box</title>
144  <para>
145   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
146   displays the global options dialog box. The dialog box is divided into
147   several panes, each pane containing a set of related options. Use the list
148   on the left of the dialog box to switch between panes. Only panes
149   created by jEdit are described here; some plugins add their own option
150   panes, and information about them can be found in the documentation
151   for the plugins in question.
152  </para>
153  <sect2 id="abbrevs-pane"><title>The Abbreviations Pane</title>
154  <para>
155   The <guibutton>Abbreviations</guibutton> option pane can be used to enable or
156   disable automatic abbreviation expansion, and to edit currently defined
157   abbreviations.
158  </para>
159  <para>
160   The combo box labeled <quote>Abbrev set</quote> selects the
161   abbreviation set to edit. The first entry, <quote>global</quote>, contains
162   abbreviations available in all edit modes. The subsequent
163   entries correspond to each mode's local set of abbreviations.
164  </para>
165  <para>
166   To change an abbreviation or its expansion, either double-click the appropriate
167   table entry, or click a table entry and then click the
168   <guibutton>Edit</guibutton> button. This will display a dialog box for
169   modifying the abbreviation.
170  </para>
171  <para>
172   The <guibutton>Add</guibutton> button displays a dialog box where you can
173   define a new abbreviation. The <guibutton>Remove</guibutton> button removes
174   the currently selected abbreviation from the list.
175  </para>
176  <para>
177   See <xref linkend="positional-params" /> for information about positional
178   parameters in abbreviations.
179  </para>
180  </sect2><sect2 id="appearance-pane"><title>The Appearance Pane</title>
181  <para>
182   The <guibutton>Appearance</guibutton> pane can be used to change the
183   appearance of user interface controls such as buttons, labels and menus. The number of items retained in history text fields can also be set here; see <xref linkend="history"/>.
184  </para>
185  <para>
186   Note that changes to certain settings such as the Swing look and feel require a restart of jEdit to take effect.
187  </para>
188  </sect2><sect2 id="autosave-backups-pane"><title>The Autosave and Backup Pane</title>
189  <para>
190   The <guibutton>Autosave</guibutton> option pane contains settings for the autosave and backup features. See <xref linkend="autosave" /> and
191   <xref linkend="backups"/>.
192  </para>
193  </sect2><sect2 id="context-pane"><title>The Context Menu Pane</title>
194  <para>
195   The <guibutton>Context Menu</guibutton> option pane edits the text
196   area's right-click context menu. See <xref linkend="views"/>.
197  </para>
198  </sect2>
199  <sect2 id="docking-pane"><title>The Docking Pane</title>
200  <para>
201   The <guibutton>Docking</guibutton> option pane specifies docking location for various dockable windows. Another way to specify docking locations is to use the popup menus associated with each dockable window; see <xref linkend="docking"/>.
202  </para>
203  </sect2>
204  <sect2 id="editing-pane"><title>The Editing Pane</title>
205  <para>
206   The <guibutton>Editing</guibutton> option pane contains settings such
207   as the tab size, syntax highlighting and soft tabs on a global or
208   mode-specific basis.
209  </para>
210  <para>
211   When changing mode-specific settings,
212   the <guibutton>File name glob</guibutton> and <guibutton>First line
213   glob</guibutton> text fields let you specify a glob pattern that names and
214   first lines of buffers will be matched against to determine the edit mode.
215   See <xref linkend="globs"/> for information about glob patterns.
216  </para>
217  <para>
218   This option pane does not change XML mode definition files on disk; it
219   merely writes values to the user properties file which override those set
220   in mode files. To find out how to edit mode files directly, see
221   <xref linkend="writing-modes-part" />.
222  </para>
223  </sect2><sect2 id="general-pane"><title>The General Pane</title>
224  <para>
225   The <guibutton>General</guibutton> pane contains various
226   miscellaneous settings, such as the default line separator and file encoding, the number of recent files to remember,
227   if the buffer list should be sorted, and so on.
228  </para>
229  </sect2><sect2 id="gutter-pane"><title>The Gutter Pane</title>
230  <para>
231   The <guibutton>Gutter</guibutton> option pane contains settings to
232   customize the appearance of the gutter. See <xref linkend="overview"/>.
233  </para>
234  </sect2><sect2 id="mouse-pane"><title>The Mouse Pane</title>
235  <para>
236   The <guibutton>Mouse</guibutton> option pane contains settings for toggling drag and drop of text, as well as gutter mouse click behavior.
237  </para>
238  </sect2><sect2 id="printing-pane"><title>The Printing Pane</title>
239  <para>
240   The <guibutton>Printing</guibutton> option pane contains settings to
241   control the appearance of printed output. Workarounds that might be needed for your Java version to print correctly can also be enabled here. See <xref linkend="printing"/>.
242  </para>
243  </sect2><sect2 id="pluginmgr-pane"><title>The Plugin Manager Pane</title>
244  <para>
245   The <guibutton>Plugin Manager</guibutton> pane contains a chooser for the desired download mirror, as well as various settings such as the directory where plugins are to be installed. See <xref linkend="using-plugins"/>.
246  </para>
247  </sect2><sect2 id="firewall-pane"><title>The Proxy Servers Pane</title>
248  <para>
249   The <guibutton>Proxy Servers</guibutton> option pane lets you specify HTTP
250   and SOCKS proxy servers to use when jEdit makes network connections, for
251   example when downloading plugins.
252  </para>
253  </sect2><sect2 id="shortcuts-pane"><title>The Shortcuts Pane</title>
254  <para>
255   The <guibutton>Shortcuts</guibutton> option pane associates keyboard shortcuts with commands. Each command can have up to two shortcuts
256   associated with it.
257  </para>
258  <para>
259   The combo box at the top of the option pane selects the command set
260   to edit. Command sets include the set of all built-in commands, the commands of each plugin, and the set of macros.
261  </para>
262  <para>
263   To change a shortcut, click the appropriate table entry and press the
264   keys you want associated with that command in the resulting dialog box.
265   The dialog box will warn you if the shortcut is already assigned.
266  </para>
267  </sect2><sect2 id="status-bar-pane"><title>The Status Bar Pane</title>
268  <para>
269   The <guibutton>Status Bar</guibutton> option pane contains settings to customize the
270   status bar, or disable it completely. See <xref linkend="status-bar"/>.
271  </para>
272  </sect2><sect2 id="syntax-hilite-pane"><title>The Syntax Highlighting Pane</title>
273  <para>
274   The <guibutton>Syntax Highlighting</guibutton> pane can be used to
275   customize the fonts and colors for syntax highlighting. See <xref linkend="syntax-hilite"/>.
276  </para>
277  </sect2><sect2 id="text-area-pane"><title>The Text Area Pane</title>
278  <para>
279   The <guibutton>Text Area</guibutton> pane contains settings to customize
280   the appearance of the text area. See <xref linkend="overview"/>.
281  </para>
282  </sect2><sect2 id="toolbar-pane"><title>The Tool Bar Pane</title>
283  <para>
284   The <guibutton>Tool Bar</guibutton> option pane lets you edit the tool bar,
285   or disable it completely. See <xref linkend="views"/>.
286  </para>
287  </sect2><sect2 id="view-pane"><title>The View Pane</title>
288  <para>
289   The <guibutton>View</guibutton> option pane lets you change various settings related to the editor window's appearance, including the arrangement of dockable windows, and if the search bar and buffer switcher should be visible. See <xref linkend="views"/>.
290  </para>
291  </sect2><sect2 id="vfs-browser-pane"><title>The File System Browser Panes</title>
292  <para>
293   The <guibutton>File System Browser</guibutton> group
294   contains two option panes, <guibutton>General</guibutton> and
295   <guibutton>Colors</guibutton>. The former contains various file system
296   browser settings. The latter configures glob patterns used for
297   coloring the file list. See <xref linkend="vfs-browser" />
298   for more information.
299  </para></sect2>
300 </sect1>
301 <sect1 id="settings-directory"><title>The jEdit Settings Directory</title>
302  <para>
303   jEdit stores settings, macros, and plugins as files
304   inside the <firstterm>settings directory</firstterm>. In most cases, editing
305   these files by hand is not necessary, since graphical tools and editor
306   commands can do the job. However, being familiar with the structure of the
307   settings directory still comes in handy
308   in certain situations, for example when you want to copy jEdit settings
309   between computers.
310  </para>
311  <para>
312   The location of the settings directory is system-specific; it is printed to
313   the activity log
314   (<guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>Activity
315   Log</guimenuitem>). For example:
316  </para>
317  <screen>[message] jEdit: Settings directory is /home/slava/.jedit</screen>
318  <para>
319   Specifying the <userinput>-settings</userinput> switch on the command line
320   instructs jEdit to store settings in a directory other than the default.
321   For example, the following command will instruct jEdit to
322   store all settings
323   in the <filename>jedit</filename> subdirectory of the <filename>C:</filename>
324   drive:
325  </para>
326  <screen><prompt>C:\jedit&gt;</prompt> <userinput>jedit -settings=C:\jedit</userinput></screen>
327  <para>
328   The <userinput>-nosettings</userinput> switch will force jEdit to not look for
329   or create a settings directory; default settings will be used instead.
330  </para>
331  <para>
332   If you are using <application>jEditLauncher</application>
333   to start jEdit on Windows, these parameters cannot be specified on the
334   MS-DOS prompt command line when starting jEdit; they must be set as described
335   in <xref linkend="launcher-starting" />.
336  </para>
337  <para>
338   jEdit creates the following files and directories
339   inside the settings directory; plugins may add more:
340  </para>
341  <itemizedlist>
342   <listitem><para><filename>abbrevs</filename> - a plain text file which
343   stores all defined abbreviations. See <xref linkend="abbrevs" />.
344   </para></listitem>
345   <listitem><para><filename>activity.log</filename> - a plain text file which
346   contains the full activity log. See <xref linkend="activity-log" />.
347   </para></listitem>
348   <listitem><para><filename>history</filename> - a plain text file which
349   stores history lists, used by history text fields and the
350   <guimenu>Edit</guimenu>&gt;<guimenuitem>Paste Previous</guimenuitem> command.
351   See <xref linkend="text-transfer" /> and <xref linkend="history" />.
352   </para></listitem>
353   <listitem><para><filename>jars</filename> - this directory contains
354   plugins. See <xref linkend="using-plugins" />.</para></listitem>
355   <listitem><para><filename>jars-cache</filename> - this directory contains
356   plugin cache files which decrease the time to start jEdit. They are automatically updated when plugins are installed or updated.</para></listitem>
357   <listitem><para><filename>killring.xml</filename> - stores recently deleted text. See <xref linkend="text-transfer" />.</para></listitem>
358   <listitem><para><filename>macros</filename> - this directory contains
359   macros. See <xref linkend="using-macros" />.</para></listitem>
360   <listitem><para><filename>modes</filename> - this directory contains custom
361   edit modes. See <xref linkend="writing-modes-part" />.
362   </para></listitem>
363   <listitem><para><filename>perspective.xml</filename> - an XML file that stores the list of open buffers and views used to maintain editor state between sessions.</para></listitem>
364   <listitem><para><filename>PluginManager.download</filename> - this directory
365   is usually empty. It only contains files while the plugin manager is
366   downloading a plugin. For information about the plugin manager,
367   see <xref linkend="using-plugins" />.</para></listitem>
368   <listitem><para><filename>printspec</filename> - a binary file that
369   stores printing settings when running under Java 2 version 1.4.
370   </para></listitem>
371   <listitem><para><filename>properties</filename> - a plain text file that
372   stores the majority of jEdit's settings.</para></listitem>
373   <listitem><para><filename>recent.xml</filename> - an XML file which stores
374   the list of recently opened files. jEdit remembers the caret position and
375   character encoding of each recent file, and
376   automatically restores those values when one of the files is opened.
377   </para></listitem>
378   <listitem><para><filename>registers.xml</filename> - an XML file that stores
379   register contents. See <xref linkend="registers"/> for more information
380   about registers.
381   </para></listitem>
382   <listitem><para><filename>server</filename> - a plain text file that only
383   exists while jEdit is running. The edit server's port number and
384   authorization key is stored here. See <xref linkend="starting" />.
385   </para></listitem>
386   <listitem><para><filename>settings-backup</filename> - this directory
387   contains numbered backups of all automatically-written settings files.
388   </para></listitem>
389  </itemizedlist>
390 </sect1>
391</chapter>