PageRenderTime 98ms CodeModel.GetById 10ms RepoModel.GetById 0ms app.codeStats 0ms

/jEdit/tags/jedit-4-0-pre3/doc/users-guide/source-edit.xml

#
XML | 570 lines | 564 code | 4 blank | 2 comment | 0 complexity | 043ca78eb5d2b7c6d80d5be758478235 MD5 | raw file
Possible License(s): BSD-3-Clause, AGPL-1.0, Apache-2.0, LGPL-2.0, LGPL-3.0, GPL-2.0, CC-BY-SA-3.0, LGPL-2.1, GPL-3.0, MPL-2.0-no-copyleft-exception, IPL-1.0
  1. <!-- jEdit buffer-local properties: -->
  2. <!-- :tabSize=1:indentSize=1:noTabs=true: -->
  3. <chapter id="source-edit"><title>Editing Source Code</title>
  4. <sect1 id="modes"><title>Edit Modes</title>
  5. <para>
  6. An <firstterm>edit mode</firstterm> specifies syntax highlighting
  7. rules, auto indent behavior, and various other customizations for editing
  8. a certain file type. This section
  9. only covers using and selecting edit modes; information about writing your
  10. own can be found in <xref linkend="writing-modes-part" />.
  11. </para>
  12. <sect2 id="mode-selection"><title>Mode Selection</title>
  13. <para>
  14. When a file is opened, jEdit first checks the file name against a list
  15. of known patterns. For example, files whose names end with <quote>.c</quote>
  16. are edited in C mode, and files named <filename>Makefile</filename> are
  17. edited in Makefile mode. If a suitable match based on file name cannot be
  18. found, jEdit checks the first line of the file. For example, files whose
  19. first line is <quote>#!/bin/sh</quote> are edited in shell script mode.
  20. </para>
  21. <para>
  22. If automatic mode selection is not appropriate, the edit mode can
  23. be specified manually. The current buffer's edit mode can be set
  24. on a one-time basis in the
  25. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
  26. dialog box; see <xref linkend="buffer-opts" />. To set a buffer's edit mode
  27. for future editing sessions,
  28. place the following in one of the first 10 lines of the buffer,
  29. where <replaceable>edit mode</replaceable> is the name of the desired edit
  30. mode:
  31. </para>
  32. <screen>:mode=<replaceable>edit mode</replaceable>:</screen>
  33. </sect2>
  34. <sect2 id="syntax-hilite"><title>Syntax Highlighting</title>
  35. <para>
  36. Syntax highlighting is the display of programming language
  37. tokens using different fonts and colors. This makes code
  38. easier to follow and errors such as misplaced quotes easier to spot.
  39. All edit modes except for
  40. the plain text mode perform syntax highlighting.
  41. </para>
  42. <para>
  43. The colors and styles used to highlight syntax tokens can be changed
  44. in the <guibutton>Styles</guibutton> pane of the
  45. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
  46. dialog box; see <xref linkend="global-opts" />.
  47. </para>
  48. </sect2>
  49. </sect1>
  50. <sect1 id="abbrevs"><title>Abbreviations</title>
  51. <para>
  52. Using abbreviations reduces the time spent typing long but commonly used
  53. strings. For example, in Java mode, the abbreviation <quote>sout</quote> is
  54. defined to expand to <quote>System.out.println()</quote>, so to insert
  55. <quote>System.out.println()</quote> in a Java buffer, you only need to type
  56. <quote>sout</quote> followed by
  57. <keycombo><keycap>Control</keycap><keycap>;</keycap></keycombo>.
  58. Each abbreviation can either be global, in which case it will expand in all
  59. edit modes, or mode-specific. Abbreviations can be edited
  60. in the <guibutton>Abbreviations</guibutton> pane of the
  61. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
  62. dialog box; see <xref linkend="global-opts" />. The Java, SGML and VHDL edit
  63. modes include some pre-defined
  64. abbreviations you might find useful.
  65. </para>
  66. <para>
  67. <guimenu>Edit</guimenu>&gt;<guimenuitem>Expand Abbreviation</guimenuitem>
  68. (keyboard shortcut: <keycombo><keycap>Control</keycap><keycap>;</keycap></keycombo>)
  69. attempts to expand the word before the caret. If no expansion could
  70. be found, it will offer to define one.
  71. </para>
  72. <para>
  73. Automatic abbreviation expansion can be enabled in the
  74. <guibutton>Abbreviations</guibutton> pane of the
  75. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
  76. dialog box; see <xref linkend="global-opts" />. If enabled, pressing the
  77. space bar after entering an
  78. abbreviation will automatically expand it.
  79. </para>
  80. <para>
  81. If automatic expansion
  82. is enabled, a space can be inserted without expanding the word before
  83. the caret by pressing
  84. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  85. <keycap>V</keycap> <keycap>Space</keycap>.
  86. </para>
  87. <sect2 id="positional-params"><title>Positional Parameters</title>
  88. <para>
  89. Positional parameters are an advanced feature that make abbreviations much
  90. more useful. The best way to describe them is with an example.
  91. </para>
  92. <para>
  93. Suppose you have an abbreviation <quote>F</quote> that is set to expand to
  94. the following:
  95. </para>
  96. <programlisting>for(int $1 = 0; $1 &lt; $2; $1++)</programlisting>
  97. <para>
  98. Now, simply entering <quote>F</quote> in the buffer and expanding it will
  99. insert the above text as-is. However, if you expand
  100. <literal>F#j#array.length#</literal>,
  101. the following will be inserted:
  102. </para>
  103. <programlisting>for(int j = 0; j &lt; array.length; j++)</programlisting>
  104. <para>
  105. Expansions can contain up to nine positional parameters. Note that a
  106. trailing hash character (<quote>#</quote>) must be entered when expanding an
  107. abbreviation with parameters.
  108. </para>
  109. </sect2>
  110. </sect1>
  111. <sect1 id="bracket-matching"><title>Bracket Matching</title>
  112. <para>
  113. Misplaced and unmatched brackets are one of the most common syntax
  114. errors encountered when writing code. jEdit has several features
  115. to make brackets easier to deal with.
  116. </para>
  117. <para>
  118. Positioning the caret immediately after a bracket will highlight the
  119. corresponding closing or opening bracket (assuming it is visible)
  120. and draw a scope indicator in the gutter. If the highlighted bracket is
  121. not visible, the text of the matching line will be shown in the status
  122. bar. If the matching line consists of only whitespace and the bracket
  123. itself, the <emphasis>line before</emphasis> is shown instead. This
  124. feature is very useful for code with bracketes indented like so:
  125. </para>
  126. <programlisting>public void someMethod()
  127. {
  128. if(isOK)
  129. {
  130. doSomething();
  131. }
  132. }</programlisting>
  133. <para>
  134. Invoking
  135. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  136. Code</guisubmenu>&gt;<guimenuitem>Go to Matching
  137. Bracket</guimenuitem> (shortcut:
  138. <keycombo><keycap>Control</keycap><keycap>]</keycap></keycombo>), or
  139. clicking the scope indicator in the gutter moves the caret to the
  140. highlighted bracket.
  141. </para>
  142. <para>
  143. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  144. Code</guisubmenu>&gt;<guimenuitem>Select Code Block</guimenuitem>
  145. (shortcut: <keycombo><keycap>Control</keycap><keycap>[</keycap></keycombo>)
  146. selects all text between the two brackets surrounding the caret.
  147. </para>
  148. <para>
  149. Holding down <keycap>Control</keycap> while clicking the scope indicator
  150. or a bracket in the text area will select all text
  151. between the two matching brackets.
  152. </para>
  153. <para>
  154. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  155. Code</guisubmenu>&gt;<guimenuitem>Go to Previous
  156. Bracket</guimenuitem> (shortcut:
  157. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  158. <keycap>[</keycap>) moves the caret to the previous opening bracket.
  159. </para>
  160. <para>
  161. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  162. Code</guisubmenu>&gt;<guimenuitem>Go to Next Bracket</guimenuitem> (shortcut:
  163. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo> <keycap>]</keycap>)
  164. moves the caret to the next closing bracket.
  165. </para>
  166. <para>
  167. Bracket highlighting for the text area and gutter, respectively,
  168. can be disabled in the
  169. <guibutton>Text Area</guibutton> and <guibutton>Gutter</guibutton> panes of the
  170. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
  171. dialog box; see <xref linkend="global-opts" />.
  172. </para>
  173. <note>
  174. <para>
  175. jEdit's bracket matching algorithm only checks syntax tokens with the same
  176. type as the original bracket for matches. So brackets inside string
  177. literals and comments will not cause problems, as they will
  178. be skipped.
  179. </para>
  180. </note>
  181. </sect1>
  182. <sect1 id="indent"><title>Tabbing and Indentation</title>
  183. <para>
  184. jEdit makes a distinction between the <firstterm>tab width</firstterm>,
  185. which is is used when displaying tab characters, and the <firstterm>indent
  186. width</firstterm>, which is used when a level of indent is to be added or
  187. removed, for example by mode-specific smart indent routines. Both can be
  188. changed in one of several ways:
  189. </para>
  190. <itemizedlist>
  191. <listitem><para>On a global or mode-specific basis in
  192. <guibutton>Editing</guibutton> and <guibutton>Mode-Specific</guibutton> panes
  193. of the the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
  194. Options</guimenuitem> dialog box.
  195. </para></listitem>
  196. <listitem><para>In the current buffer
  197. for the duration of the editing session in the
  198. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
  199. dialog box; see <xref linkend="buffer-opts" />.</para></listitem>
  200. <listitem><para>In the current buffer
  201. for future editing sessions by placing the
  202. following in one of the first 10 lines of the buffer, where
  203. <replaceable>n</replaceable> is the desired tab width, and
  204. <replaceable>m</replaceable> is the desired indent width:
  205. </para>
  206. <screen>:tabSize=<replaceable>n</replaceable>:indentSize=<replaceable>m</replaceable>:</screen>
  207. </listitem>
  208. </itemizedlist>
  209. <para>
  210. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  211. Code</guisubmenu>&gt;<guisubmenu>Shift Indent Left</guisubmenu>
  212. (shortcut: <keycombo><keycap>Shift</keycap><keycap>Tab</keycap></keycombo>
  213. or <keycombo><keycap>Alt</keycap><keycap>Left</keycap></keycombo>)
  214. adds one level of indent to each selected line, or the current line
  215. if there is no selection.
  216. </para>
  217. <para>
  218. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  219. Code</guisubmenu>&gt;<guisubmenu>Shift Indent Right</guisubmenu>
  220. (shortcut: <keycombo><keycap>Alt</keycap><keycap>Right</keycap></keycombo>)
  221. removes one level of indent from each selected line, or the current line
  222. if there is no selection. Pressing <keycap>Tab</keycap> while a multi-line
  223. selection is active has the same effect.
  224. </para>
  225. <sect2 id="soft-tabs"><title>Soft Tabs</title>
  226. <para>
  227. Because files indented using tab characters may look less than ideal when
  228. viewed on a system with a different default tab size, it is sometimes
  229. desirable to use multiple spaces, known as <firstterm>soft tabs</firstterm>,
  230. instead of real tab characters, to indent code.
  231. </para>
  232. <para>
  233. Soft tabs can be enabled or disabled in one of several ways:
  234. </para>
  235. <itemizedlist>
  236. <listitem><para>On a global or edit mode-specific basis in the
  237. <guibutton>Editing</guibutton> and <guibutton>Mode-Specific</guibutton>
  238. panes of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
  239. Options</guimenuitem> dialog box.</para></listitem>
  240. <listitem><para>In the current buffer for
  241. the duration of the editing session in the
  242. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
  243. dialog box; see <xref linkend="buffer-opts" />.</para></listitem>
  244. <listitem><para>In the current buffer for
  245. future editing sessions by placing the following in one of the first
  246. 10 lines of the buffer, where <replaceable>flag</replaceable> is either
  247. <quote>true</quote> or <quote>false</quote>:
  248. </para>
  249. <screen>:noTabs=<replaceable>flag</replaceable>:</screen>
  250. </listitem>
  251. </itemizedlist>
  252. <para>
  253. Changing the soft tabs setting has no effect on existing tab characters;
  254. it only affects subsequently-inserted tabs.
  255. </para>
  256. <para>
  257. <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Spaces
  258. to Tabs</guimenuitem>
  259. converts soft tabs to hard tabs in the current selection.
  260. </para>
  261. <para>
  262. <guimenu>Edit</guimenu>&gt;<guisubmenu>Text</guisubmenu>&gt;<guimenuitem>Tabs
  263. to Spaces</guimenuitem>
  264. converts hard tabs to soft tabs in the current selection.
  265. </para>
  266. </sect2>
  267. <sect2 id="autoindent"><title>Automatic Indent</title>
  268. <para>
  269. The auto indent feature inserts the appropriate number of tabs or
  270. spaces at the beginning of a line.
  271. </para>
  272. <para>
  273. If indent on enter is enabled, pressing <keycap>Enter</keycap>
  274. will create a new line with the appropriate amount of
  275. indent automatically. If indent on tab is enabled, pressing
  276. <keycap>Tab</keycap> at the beginning of, or inside the leading
  277. whitespace of, a line will insert the appropriate amount of
  278. indentation. Pressing it again will insert a tab character.
  279. </para>
  280. <para>
  281. By default, both indent on enter and indent on tab is enabled.
  282. This can be changed in one of several ways:
  283. </para>
  284. <itemizedlist>
  285. <listitem><para>On a global or mode-specific
  286. basis in the <guibutton>Editing</guibutton> and
  287. <guibutton>Mode-Specific</guibutton> panes
  288. of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
  289. Options</guimenuitem> dialog box.</para></listitem>
  290. <listitem><para>In the current buffer for the duration of the editing
  291. session in the
  292. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
  293. dialog box; see <xref linkend="buffer-opts" />. </para></listitem>
  294. <listitem><para>In the current buffer for future editing sessions
  295. by placing the following in the first 10 lines of a buffer,
  296. where <replaceable>flag</replaceable> is either <quote>true</quote> or
  297. <quote>false</quote>:
  298. </para>
  299. <screen>:indentOnEnter=<replaceable>flag</replaceable>:indentOnTab=<replaceable>flag</replaceable>:</screen>
  300. </listitem>
  301. </itemizedlist>
  302. <para>
  303. Auto indent behavior is mode-specific. In most edit modes,
  304. the indent of the previous line is simply copied over.
  305. However, in C-like languages (C, C++, Java, JavaScript), curly
  306. brackets and language statements are taken into account and indent
  307. is added and removed as necessary.
  308. </para>
  309. <para>
  310. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  311. Code</guisubmenu>&gt;<guisubmenu>Indent Selected Lines</guisubmenu>
  312. (shortcut: <keycombo><keycap>Control</keycap><keycap>I</keycap></keycombo>)
  313. indents all selected lines, or the current line if there is no
  314. selection.
  315. </para>
  316. <para>
  317. To insert a literal tab or newline without performing
  318. indentation, prefix the tab or newline with
  319. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  320. <keycap>V</keycap>. For example,
  321. to create a new line without any indentation, type
  322. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  323. <keycap>V</keycap> <keycap>Enter</keycap>.
  324. </para>
  325. </sect2>
  326. </sect1>
  327. <sect1 id="commenting"><title>Commenting Out Code</title>
  328. <para>
  329. Most programming and markup languages support <quote>comments</quote>, or
  330. regions of code which are ignored by the compiler/interpreter. jEdit
  331. has commands which make inserting comments more convenient.
  332. </para>
  333. <para>
  334. Comment strings are mode-specific, and modes such as HTML where
  335. different parts of a buffer can have different comment strings
  336. (for example, in HTML text and inline JavaScript) are handled correctly.
  337. </para>
  338. <para>
  339. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  340. Code</guisubmenu>&gt;<guimenuitem>Range Comment</guimenuitem>
  341. (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  342. <keycombo><keycap>Control</keycap><keycap>C</keycap></keycombo>) encloses the
  343. selection with comment start and end strings, for example <literal>/*</literal>
  344. and <literal>*/</literal> in Java mode.
  345. </para>
  346. <para>
  347. <guimenu>Edit</guimenu>&gt;<guisubmenu>Source
  348. Code</guisubmenu>&gt;<guimenuitem>Line Comment</guimenuitem>
  349. (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  350. <keycombo><keycap>Control</keycap><keycap>K</keycap></keycombo>) inserts the
  351. line comment string, for example <literal>//</literal> in Java mode,
  352. at the start of each selected line.
  353. </para>
  354. </sect1>
  355. <sect1 id="folding"><title>Folding</title>
  356. <para>
  357. Program source code and other structured text files can be thought of
  358. as a hierarchy of sections, which themselves might contain sub-sections.
  359. The folding feature lets you selectively hide and show these sections,
  360. replacing hidden ones with a single line that serves as an
  361. <quote>overview</quote> of that section.
  362. </para>
  363. <para>
  364. Folding is disabled by default. To enable it, you must choose one of the
  365. two available <quote>folding modes</quote>. <quote>Indent</quote>
  366. mode creates folds based on a line's leading whitespace; the more
  367. leading whitespace a block of text has, the further down it is
  368. in the hierarchy. For example:
  369. </para>
  370. <screen>This is a section
  371. This is a sub-section
  372. This is another sub-section
  373. This is a sub-sub-section
  374. Another top-level section</screen>
  375. <para>
  376. <quote>Explicit</quote> mode folds away blocks of
  377. text surrounded with <quote>{{{</quote> and <quote>}}}</quote>.
  378. For example:
  379. </para>
  380. <screen>{{{ The first line of a fold.
  381. When this fold is collapsed, only the above line will be visible.
  382. {{{ A sub-section.
  383. With text inside it.
  384. }}}
  385. {{{ Another sub-section.
  386. }}}
  387. }}}</screen>
  388. <para>
  389. Both modes have distinct advantages and disadvantages; indent folding
  390. requires no changes to be made to a buffer's text and does a decent
  391. job with most program source. Explicit folding requires <quote>fold
  392. markers</quote> to be inserted into the text, but is more flexible in
  393. exactly what to fold away than indent folding.
  394. </para>
  395. <para>
  396. Folding can be enabled in one of several ways:
  397. </para>
  398. <itemizedlist>
  399. <listitem><para>On a global or mode-specific
  400. basis in the <guibutton>Editing</guibutton> and
  401. <guibutton>Mode-Specific</guibutton> panes
  402. of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
  403. Options</guimenuitem> dialog box.</para></listitem>
  404. <listitem><para>In the current buffer for the duration of the editing
  405. session in the
  406. <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
  407. dialog box; see <xref linkend="buffer-opts" />. </para></listitem>
  408. <listitem><para>In the current buffer for future editing sessions
  409. by placing the following in the first 10 lines of a buffer,
  410. where <replaceable>mode</replaceable> is either <quote>indent</quote> or
  411. <quote>explicit</quote>:
  412. </para>
  413. <screen>:folding=<replaceable>mode</replaceable>:</screen>
  414. </listitem>
  415. </itemizedlist>
  416. <sect2><title>Collapsing and Expanding Folds</title>
  417. <para>
  418. When folding is enabled, the first line of each fold has a triangle
  419. drawn next to it in the gutter (see <xref linkend="textarea"/> for
  420. more information about the gutter). The triangle points towards the
  421. line when the fold is collapsed, and downwards when the fold is
  422. expanded. The first line of a collapsed fold is also drawn
  423. with a different background color, and the number of lines in the
  424. fold is shown to the right of the line's text.
  425. </para>
  426. <para>
  427. Clicking a fold expansion triangle in the gutter collapses and
  428. expands the fold. Expanding a fold does not expand any sub-folds
  429. it contains unless the <keycap>Shift</keycap> key is held down
  430. while clicking.
  431. </para>
  432. <para>
  433. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Collapse
  434. Fold</guimenuitem> (keyboard shortcut:
  435. <keycombo><keycap>Alt</keycap><keycap>Backspace</keycap></keycombo>)
  436. collapses the fold
  437. containing the caret position.
  438. </para>
  439. <para>
  440. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
  441. Fold One Level</guimenuitem> (keyboard shortcut:
  442. <keycombo><keycap>Alt</keycap><keycap>Enter</keycap></keycombo>) expands the
  443. fold containing the caret position. Nested folds will remain collapsed.
  444. </para>
  445. <para>
  446. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
  447. Fold Fully</guimenuitem> (keyboard shortcut:
  448. <keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Enter</keycap></keycombo>)
  449. expands the fold
  450. containing the caret position, also expanding any nested folds.
  451. </para>
  452. <para>
  453. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Collapse
  454. All Folds</guimenuitem> (keyboard shortcut:
  455. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  456. <keycap>C</keycap>) collapses all folds in the buffer.
  457. </para>
  458. <para>
  459. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
  460. All Folds</guimenuitem> (keyboard shortcut:
  461. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  462. <keycap>X</keycap>)
  463. expands all folds, thus making all lines in the buffer visible.
  464. </para>
  465. </sect2>
  466. <sect2><title>Navigating Around With Folds</title>
  467. <para>
  468. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Parent
  469. Fold</guimenuitem> (keyboard shortcut:
  470. <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>) moves
  471. the caret to the fold containing the one at the caret position.
  472. </para>
  473. <para>
  474. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Previous
  475. Fold</guimenuitem> (keyboard shortcut:
  476. <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>) moves
  477. the caret to the fold immediately before the caret position.
  478. </para>
  479. <para>
  480. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Go to Next
  481. Fold</guimenuitem> (keyboard shortcut:
  482. <keycombo><keycap>Alt</keycap><keycap>Up</keycap></keycombo>) moves
  483. the caret to the fold immediately after the caret position.
  484. </para>
  485. </sect2>
  486. <sect2><title>Miscellaneous Folding Features</title>
  487. <para>
  488. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Add
  489. Explicit Fold</guimenuitem> (keyboard shortcut:
  490. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  491. <keycap>A</keycap>) is a convenience command that surrounds the
  492. selection with <quote>{{{</quote> and <quote>}}}</quote>. If the
  493. current buffer's edit mode defines comment strings (see
  494. <xref linkend="commenting" />) the explicit fold markers will
  495. automatically be commented out as well.
  496. </para>
  497. <para>
  498. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Select
  499. Fold</guimenuitem>
  500. (keyboard shortcut:
  501. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  502. <keycap>S</keycap>)
  503. selects all lines within the fold containing the caret position.
  504. <keycap>Control</keycap>-clicking a fold expansion triangle
  505. in the gutter on the left of the text area has the same effect.
  506. </para>
  507. <para>
  508. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
  509. Folds With Level</guimenuitem> (keyboard shortcut:
  510. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  511. <keycap>Enter</keycap> <keycap><replaceable>key</replaceable></keycap>)
  512. reads the next character entered at the keyboard, and
  513. expands all folds in the buffer
  514. with a fold level less than that specified, while collapsing all others.
  515. </para>
  516. <para>
  517. You can have all folds with a fold level higher than that specified
  518. be collapsed automatically when a buffer is loaded. This can be configured
  519. as follows:
  520. </para>
  521. <itemizedlist>
  522. <listitem><para>On a global or mode-specific
  523. basis in the <guibutton>Editing</guibutton> and
  524. <guibutton>Mode-Specific</guibutton> panes
  525. of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
  526. Options</guimenuitem> dialog box.</para></listitem>
  527. <listitem><para>In the current buffer for future editing sessions
  528. by placing the following in the first 10 lines of a buffer,
  529. where <replaceable>level</replaceable> is the desired fold level:
  530. </para>
  531. <screen>:collapseFolds=<replaceable>level</replaceable>:</screen>
  532. </listitem>
  533. </itemizedlist>
  534. </sect2>
  535. <sect2 id="narrowing"><title>Narrowing</title>
  536. <para>
  537. The narrowing feature temporarily <quote>narrows</quote> the display
  538. of a buffer to a specified region. Text outside the region is not
  539. shown, but is still present in the buffer. Both folding and
  540. narrowing are implemented using the same code internally.
  541. </para>
  542. <para>
  543. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Narrow
  544. Buffer to Fold</guimenuitem> (keyboard shortcut:
  545. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  546. <keycap>N</keycap> <keycap>N</keycap>) hides all lines the buffer except
  547. those in the fold containing the caret.
  548. When this command is invoked, a message is shown in the
  549. status bar explaining how to make the entire buffer visible again.
  550. </para>
  551. <para>
  552. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Narrow
  553. Buffer to Selection</guimenuitem> (keyboard shortcut:
  554. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  555. <keycap>N</keycap> <keycap>S</keycap>) hides all lines the buffer
  556. except those in the selection.
  557. </para>
  558. <para>
  559. <guisubmenu>Folding</guisubmenu>&gt;<guimenuitem>Expand
  560. All Folds</guimenuitem> (keyboard shortcut:
  561. <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
  562. <keycap>X</keycap>) will make visible any lines hidden by narrowing.
  563. </para>
  564. </sect2>
  565. </sect1>
  566. </chapter>