PageRenderTime 67ms CodeModel.GetById 58ms app.highlight 4ms RepoModel.GetById 1ms app.codeStats 0ms

/jEdit/tags/jedit-4-3-pre5/doc/users-guide/customizing.xml

#
XML | 397 lines | 383 code | 5 blank | 9 comment | 0 complexity | 6550d0759f1d451f4f1903c6e251d985 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">
154  <title>The Abbreviations Pane</title>
155
156  <indexterm><primary>Abbreviations</primary> <secondary> creating and editing </secondary> </indexterm>
157  
158
159  
160  <para>
161   The <guibutton>Abbreviations</guibutton> option pane can be used to enable or
162   disable automatic abbreviation expansion, and to edit currently defined
163   abbreviations.
164  </para>
165  <para>
166   The combo box labelled <quote>Abbrev set</quote> selects the
167   abbreviation set to edit. The first entry, <quote>global</quote>, contains
168   abbreviations available in all edit modes. The subsequent
169   entries correspond to each mode's local set of abbreviations.
170  </para>
171  <para>
172   To change an abbreviation or its expansion, either double-click the appropriate
173   table entry, or click a table entry and then click the
174   <guibutton>Edit</guibutton> button. This will display a dialog box for
175   modifying the abbreviation.
176  </para>
177  <para>
178   The <guibutton>Add</guibutton> button displays a dialog box where you can
179   define a new abbreviation. The <guibutton>Remove</guibutton> button removes
180   the currently selected abbreviation from the list.
181  </para>
182  <para>
183   See <xref linkend="positional-params" /> for information about positional
184   parameters in abbreviations.
185  </para>
186  </sect2><sect2 id="appearance-pane"><title>The Appearance Pane</title>
187  <para>
188   The <guibutton>Appearance</guibutton> pane can be used to change the
189   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"/>.
190  </para>
191  <para>
192   Note that changes to certain settings such as the Swing look and feel require a restart of jEdit to take effect.
193  </para>
194  </sect2><sect2 id="autosave-backups-pane"><title>The Autosave and Backup Pane</title>
195  <para>
196   The <guibutton>Autosave</guibutton> option pane contains settings for the autosave and backup features. See <xref linkend="autosave" /> and
197   <xref linkend="backups"/>.
198  </para>
199  </sect2><sect2 id="context-pane"><title>The Context Menu Pane</title>
200  <para>
201   The <guibutton>Context Menu</guibutton> option pane edits the text
202   area's right-click context menu. See <xref linkend="views"/>.
203  </para>
204  </sect2>
205  <sect2 id="docking-pane"><title>The Docking Pane</title>
206  <para>
207   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"/>.
208  </para>
209  </sect2>
210  <sect2 id="editing-pane"><title>The Editing Pane</title>
211  <para>
212   The <guibutton>Editing</guibutton> option pane contains settings such
213   as the tab size, syntax highlighting and soft tabs on a global or
214   mode-specific basis.
215  </para>
216  <para>
217   When changing mode-specific settings,
218   the <guibutton>File name glob</guibutton> and <guibutton>First line
219   glob</guibutton> text fields let you specify a glob pattern that names and
220   first lines of buffers will be matched against to determine the edit mode.
221   See <xref linkend="globs"/> for information about glob patterns.
222  </para>
223  <para>
224   This option pane does not change XML mode definition files on disk; it
225   merely writes values to the user properties file which override those set
226   in mode files. To find out how to edit mode files directly, see
227   <xref linkend="writing-modes-part" />.
228  </para>
229  </sect2><sect2 id="general-pane"><title>The General Pane</title>
230  <para>
231   The <guibutton>General</guibutton> pane contains various
232   miscellaneous settings, such as the default line separator and file encoding, the number of recent files to remember,
233   if the buffer list should be sorted, and so on.
234  </para>
235  </sect2><sect2 id="gutter-pane"><title>The Gutter Pane</title>
236  <para>
237   The <guibutton>Gutter</guibutton> option pane contains settings to
238   customize the appearance of the gutter. See <xref linkend="overview"/>.
239  </para>
240  </sect2><sect2 id="mouse-pane"><title>The Mouse Pane</title>
241  <para>
242   The <guibutton>Mouse</guibutton> option pane contains settings for toggling drag and drop of text, as well as gutter mouse click behavior.
243  </para>
244  </sect2><sect2 id="printing-pane"><title>The Printing Pane</title>
245  <para>
246   The <guibutton>Printing</guibutton> option pane contains settings to
247   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"/>.
248  </para>
249  </sect2><sect2 id="pluginmgr-pane"><title>The Plugin Manager Pane</title>
250  <para>
251   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"/>.
252  </para>
253  </sect2><sect2 id="firewall-pane"><title>The Proxy Servers Pane</title>
254  <para>
255   The <guibutton>Proxy Servers</guibutton> option pane lets you specify HTTP
256   and SOCKS proxy servers to use when jEdit makes network connections, for
257   example when downloading plugins.
258  </para>
259  </sect2><sect2 id="shortcuts-pane"><title>The Shortcuts Pane</title>
260  <para>
261   The <guibutton>Shortcuts</guibutton> option pane associates keyboard shortcuts with commands. Each command can have up to two shortcuts
262   associated with it.
263  </para>
264  <para>
265   The combo box at the top of the option pane selects the command set
266   to edit. Command sets include the set of all built-in commands, the commands of each plugin, and the set of macros.
267  </para>
268  <para>
269   To change a shortcut, click the appropriate table entry and press the
270   keys you want associated with that command in the resulting dialog box.
271   The dialog box will warn you if the shortcut is already assigned.
272  </para>
273  </sect2><sect2 id="status-bar-pane"><title>The Status Bar Pane</title>
274  <para>
275   The <guibutton>Status Bar</guibutton> option pane contains settings to customize the
276   status bar, or disable it completely. See <xref linkend="status-bar"/>.
277  </para>
278  </sect2><sect2 id="syntax-hilite-pane"><title>The Syntax Highlighting Pane</title>
279  <para>
280   The <guibutton>Syntax Highlighting</guibutton> pane can be used to
281   customize the fonts and colors for syntax highlighting. See <xref linkend="syntax-hilite"/>.
282  </para>
283  </sect2><sect2 id="text-area-pane"><title>The Text Area Pane</title>
284  <para>
285   The <guibutton>Text Area</guibutton> pane contains settings to customize
286   the appearance of the text area. See <xref linkend="overview"/>.
287  </para>
288  </sect2><sect2 id="toolbar-pane"><title>The Tool Bar Pane</title>
289  <para>
290   The <guibutton>Tool Bar</guibutton> option pane lets you edit the tool bar,
291   or disable it completely. See <xref linkend="views"/>.
292  </para>
293  </sect2><sect2 id="view-pane"><title>The View Pane</title>
294  <para>
295   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"/>.
296  </para>
297  </sect2><sect2 id="vfs-browser-pane"><title>The File System Browser Panes</title>
298  <para>
299   The <guibutton>File System Browser</guibutton> group
300   contains two option panes, <guibutton>General</guibutton> and
301   <guibutton>Colors</guibutton>. The former contains various file system
302   browser settings. The latter configures glob patterns used for
303   coloring the file list. See <xref linkend="vfs-browser" />
304   for more information.
305  </para></sect2>
306 </sect1>
307 <sect1 id="settings-directory"><title>The jEdit Settings Directory</title>
308  <para>
309   jEdit stores settings, macros, and plugins as files
310   inside the <firstterm>settings directory</firstterm>. In most cases, editing
311   these files by hand is not necessary, since graphical tools and editor
312   commands can do the job. However, being familiar with the structure of the
313   settings directory still comes in handy
314   in certain situations, for example when you want to copy jEdit settings
315   between computers.
316  </para>
317  <para>
318   The location of the settings directory is system-specific; it is printed to
319   the activity log
320   (<guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>Activity
321   Log</guimenuitem>). For example:
322  </para>
323  <screen>[message] jEdit: Settings directory is /home/slava/.jedit</screen>
324  <para>
325   Specifying the <userinput>-settings</userinput> switch on the command line
326   instructs jEdit to store settings in a directory other than the default.
327   For example, the following command will instruct jEdit to
328   store all settings
329   in the <filename>jedit</filename> subdirectory of the <filename>C:</filename>
330   drive:
331  </para>
332  <screen><prompt>C:\jedit&gt;</prompt> <userinput>jedit -settings=C:\jedit</userinput></screen>
333  <para>
334   The <userinput>-nosettings</userinput> switch will force jEdit to not look for
335   or create a settings directory; default settings will be used instead.
336  </para>
337  <!-- para>
338   If you are using <application>jEditLauncher</application>
339   to start jEdit on Windows, these parameters cannot be specified on the
340   MS-DOS prompt command line when starting jEdit; they must be set as described
341   in <xref linkend="launcher-starting" />.
342  </para -->
343  <para>
344   jEdit creates the following files and directories
345   inside the settings directory; plugins may add more:
346  </para>
347  <itemizedlist>
348   <listitem><para><filename>abbrevs</filename> - a plain text file which
349   stores all defined abbreviations. See <xref linkend="abbrevs" />.
350   </para></listitem>
351   <listitem><para><filename>activity.log</filename> - a plain text file which
352   contains the full activity log. See <xref linkend="activity-log" />.
353   </para></listitem>
354   <listitem><para><filename>history</filename> - a plain text file which
355   stores history lists, used by history text fields and the
356   <guimenu>Edit</guimenu>&gt;<guimenuitem>Paste Previous</guimenuitem> command.
357   See <xref linkend="text-transfer" /> and <xref linkend="history" />.
358   </para></listitem>
359   <listitem><para><filename>jars</filename> - this directory contains
360   plugins. See <xref linkend="using-plugins" />.</para></listitem>
361   <listitem><para><filename>jars-cache</filename> - this directory contains
362   plugin cache files which decrease the time to start jEdit. They are automatically updated when plugins are installed or updated.</para></listitem>
363   <listitem><para><filename>killring.xml</filename> - stores recently deleted text. See <xref linkend="text-transfer" />.</para></listitem>
364   <listitem><para><filename>macros</filename> - this directory contains
365   macros. See <xref linkend="using-macros" />.</para></listitem>
366   <listitem><para><filename>modes</filename> - this directory contains custom
367   edit modes. See <xref linkend="writing-modes-part" />.
368   </para></listitem>
369   <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>
370   <listitem><para><filename>PluginManager.download</filename> - this directory
371   is usually empty. It only contains files while the plugin manager is
372   downloading a plugin. For information about the plugin manager,
373   see <xref linkend="using-plugins" />.</para></listitem>
374   <listitem><para><filename>printspec</filename> - a binary file that
375   stores printing settings when running under Java 2 version 1.4.
376   </para></listitem>
377   <listitem><para><filename>properties</filename> - a plain text file that
378   stores the majority of jEdit's settings.</para></listitem>
379   <listitem><para><filename>recent.xml</filename> - an XML file which stores
380   the list of recently opened files. jEdit remembers the caret position and
381   character encoding of each recent file, and
382   automatically restores those values when one of the files is opened.
383   </para></listitem>
384   <listitem><para><filename>registers.xml</filename> - an XML file that stores
385   register contents. See <xref linkend="registers"/> for more information
386   about registers.
387   </para></listitem>
388   <listitem><para><filename>server</filename> - a plain text file that only
389   exists while jEdit is running. The edit server's port number and
390   authorization key is stored here. See <xref linkend="starting" />.
391   </para></listitem>
392   <listitem><para><filename>settings-backup</filename> - this directory
393   contains numbered backups of all automatically-written settings files.
394   </para></listitem>
395  </itemizedlist>
396 </sect1>
397</chapter>