PageRenderTime 86ms CodeModel.GetById 41ms app.highlight 7ms RepoModel.GetById 33ms app.codeStats 0ms

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

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