<?xml version="1.0" encoding="UTF-8"?>
<section id="usage">
		<title>Usage Questions</title>

		<!-- jEdit buffer-local properties:                      -->
		<!-- :indentSize=2:noTabs=false:tabSize=2:maxLineLen=90: -->
		<!-- :xml.root=faq.xml:                                  -->
		<!-- jEdit FAQ                                           -->

		<para>This section deals general usage of jEdit, including
		customisation.</para>

		<qandaset defaultlabel="qanda">
				<!--********************************************************* Abrevs -->
				<qandadiv id="text-abbrev">
						<title>Abbreviations</title>
						<qandaentry>
								<question id="abbrevs-create-onfly">
										<para>How can I create abbreviations <quote>on the
										fly</quote> as I type?</para>
								</question>
								<answer>
										<para>Type the form of abbreviation you wish to use, then
										without pressing the <keycap>SPACE</keycap> key, press
										<keycombo action="simul">
										<keycap>CTRL</keycap> <keycap>;</keycap> </keycombo>.
										A dialog will appear for entering text that
										goes before and after the editing caret. For example, you
										can insert an opening HTML or XML tag before the cursor and
										its corresponding closing tag after the cursor. Use the
										mouse to select <guilabel>Add global</guilabel> or
										<guilabel>Add mode-specific</guilabel>. The first choice
										makes the abbreviation available for all documents; the
										second makes it available only in documents with the same
										editing mode as the current document. In this way, you can
										add abbreviations that operate only a particular class of
										documents, for example, Java source files or XML markup.
										Either way, the abbreviation will be stored for future
										use.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="abbrevs-expand-type">
										<para>How can I have abbreviations expanded automatically as
										I type?</para>
								</question>

								<answer>
										<para>Select<guimenuitem>Global Options</guimenuitem>,
										<guimenuitem>Abbreviations</guimenuitem> option pane. You
										will see a checkbox option for <quote>Space bar expands
										abbrevs</quote>. Here you can also add, modify and delete
										abbreviations on a global basis or for individual editing
										modes.</para>
								</answer>
						</qandaentry>
				</qandadiv>

				<!--********************************************************* Clippy -->

				<qandadiv id="text-clipboard">
						<title>Clipboard features</title>

						<qandaentry>
								<question id="clip-multiple">
										<para>Can I copy selections from more than one location in a
										document (or more than one document) and paste the aggregate
										text in one operation?</para>
								</question>

								<answer>
										<para>The <guimenuitem>Cut Append</guimenuitem> (<keycombo
														action="simul">
														<keycap>CTRL</keycap>

														<keycap>E</keycap>
												</keycombo> <keycombo action="simul">
														<keycap>CTRL</keycap>

														<keycap>U</keycap>
												</keycombo>) and <guimenuitem>Copy Append</guimenuitem>
										(<keycombo action="simul">
														<keycap>CTRL</keycap>

														<keycap>E</keycap>
												</keycombo> <keycombo action="simul">
														<keycap>CTRL</keycap>

														<keycap>A</keycap>
												</keycombo>) both add the selected text to the existing
										contents of the Clipboard. A single
										<guimenuitem>Paste</guimenuitem> (<keycombo action="simul">
														<keycap>CTRL</keycap>

														<keycap>V</keycap>
												</keycombo>) command will insert the aggregated text at
										the cursor or in place of an existing selection.</para>
								</answer>
						</qandaentry>
				</qandadiv>

				<!--********************************************************* Attrib -->

				<qandadiv id="file-attributes">
						<title>File Attributes</title>

						<qandaentry>
								<question id="file-owner-preserve">
										<para>Does jEdit preserve file ownership and permissions
										when it saves files?</para>
								</question>

								<answer>
										<para>One reason this can be an issue is that by default,
										jEdit adopts the conservative approach of saving a file to a
										temporary name before renaming that file to the desired
										name. This procedure minimizes the risk of crashes causing
										loss of data, and works without reported problems on local
										file systems. However, when files are served remotely by
										FTP, Samba or other means, it may not be possible to
										preserve file attributes on the server because the newly
										created temporary file's owner may differ from the owner of
										the original file on the server.</para>

										<para>To avoid this problem, you can disable the two-step
										file saving routine. Select <guimenuitem>Global Options</guimenuitem>,
										then under <guimenuitem>Saving &amp; Backup</guimenuitem>, clear the checkbox for
										<guimenuitem>Two-stage save</guimenuitem>.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="file-linesep-choice">
										<para>Why does jEdit ignore my choice for line separator
										characters when I save a file?</para>
								</question>

								<answer>
										<para>When jEdit saves an existing file, it uses the line
										separator already used by the file. The line separator
										designated in the buffer options or elsewhere is used only
										for new files.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="file-autodetect-encoding">
										<para>Can jEdit auto-detect character encodings when it
										opens a file?</para>
								</question>

								<answer>

										<para> You can select the encoding you
										wish to use from <guisubmenu> Encoding</guisubmenu> in the
										<guimenu>Commands</guimenu> menu of the File System Browser.
										You can also designate a default encoding in the
										<ulink url="../users-guide/global-opts.html#encodings-pane">
										<guimenuitem>Encoding</guimenuitem></ulink> pane of the
										Global Options; if you do not, jEdit uses

										<emphasis role="bold">encoding autodetectors</emphasis> to decide
										which encoding to open a file in. You can change the encoding used to
										save an individual file by selecting
										<guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
										Options</guimenuitem> and changing the current buffer's properties.
										Finally, jEdit keeps track of the encodings used in the files named in
										the <guimenu>File</guimenu>&gt;<guimenuitem>Recent Files</guimenuitem>
										drop-down list.</para>

										<para>These features allow you to minimize the attention
										given to character encodings, but you must still pay some
										attention if you do not want to use default settings.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="file-euro-char">
										<para>I'm using the iso-8859-1 character encoding. How do I
										type and save the Euro sign (<quote>€</quote>)?</para>
								</question>

								<answer>

									<para>You need to use instead the iso-8859-15 character set, which is a
									modification of iso-8859-1 that includes the Euro sign and some Finnish
									and French characters. The Euro sign represents character value 0xA4 in
									this 8-bit set. To open a file manually using this encoding, select
									<guimenu>File</guimenu>&gt;<guimenuitem>Open... </guimenuitem>, and
									select <guimenuitem>ISO8859_15</guimenuitem> from <guimenu>
									Commands</guimenu>&gt;<guisubmenu>Enconding</guisubmenu> before opening
									the file.</para>

									<para>There is a startup script in the <quote>Downloads</quote> area of
									<ulink url="http://community.jedit.org">jEdit Community</ulink> named
									<filename>euro.bsh</filename> that can be used as a startup script to
									help simplify the insertion of the Euro symbol if your keyboard
									currently lacks a dedicated key.</para>
								</answer>
							</qandaentry>
						</qandadiv>

				<!--********************************************************** Files -->

				<qandadiv id="file-manage">
						<title>File Management</title>

						<qandaentry>
								<question id="open-dnd">
										<para>How can I open files in jEdit using drag and
										drop?</para>
								</question>

								<answer>
										<para>Try installing the Drag and Drop plugin using the
										Plugin Manager feature. It works with most (but not all)
										combinations of operating systems and current Java runtime
										environments.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="add-favorites">
										<para>How do I add and remove directories to the list of
										<quote>favorites</quote> in jEdit's File System
										Browser?</para>
								</question>

								<answer>
										<para>To add a directory to the list of favorites, navigate
										so that the directory is at the top of the tree displayed in
										the File System Browser window, click the
										<guimenuitem>Favorites</guimenuitem> button, and select
										<guimenuitem>Add to favorites</guimenuitem> from the
										resulting menu. To delete a directory from the favorites
										list, use the same menu to go to the favorites list.
										Right-click on the directory to be deleted and select
										<guimenuitem>Delete</guimenuitem>. This operation will
										delete the directory from the list of favorites but will
										have no effect on the directory itself.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="associate-files">
										<para>How do I associate particular file types with jEdit so
										I can open them by double clicking their icons in Windows
										Explorer?</para>
								</question>

								<answer>
										<para>You associate the file extension with
										<userinput><replaceable>&lt;jEdit installation
										directory&gt;</replaceable>\jedit.exe</userinput>.
										This can be done from the <guimenuitem>File Types</guimenuitem>
										tab in the Windows Explorer's <guimenuitem>Tools</guimenuitem>
										-&gt; <guimenuitem>Folder options...</guimenuitem> menu.</para>

										<para>The EXE-installer for Windows includes a
										custom context menu handler. It will provide menu items for
										using jEdit any time you right-click on a file icon in
										Windows Explorer. This feature does
										not interfere with any existing file associations.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="open-restrict-dir">
										<para>Can I restrict jEdit to opening and saving files in a
										single directory without changing file permissions?</para>
								</question>

								<answer>
										<para>The easiest way to get this kind of behavior is to use
										macros that open the Virtual File Browser to a specific,
										fixed directory, and then change the default keyboard
										shortcuts for opening and saving files to run these
										macros.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="filename-uc-to-lc">
										<para>On Windows, how can I change the name of my file from
										<filename>myfile.txt</filename> to
										<filename>MyFile.txt</filename>?</para>
								</question>

								<answer>
										<para>The Windows native file system deals with file names
										in a case-insensitive manner, so
										<filename>myfile.txt</filename> and
										<filename>MyFile.txt</filename> refer to the same file. As a
										result, the jEdit file browser treats both spellings
										identically and does not make a name change. Using our
										example, the easiest workaround is to rename the file in two
										steps: first to <filename>_myfile.txt</filename>, then to
										<filename>MyFile.txt</filename>.</para>
								</answer>
						</qandaentry>
				</qandadiv>

				<!--*********************************************************** Text -->

				<qandadiv id="text-format">
						<title>Formatting text</title>

			<qandaentry>
								<question id="toggle-auto-indent">
										<para>How do I toggle jEdit's auto-indent behavior? </para>
								</question>
								<answer>
									 <para> By default, the <literal>Return</literal> key is bound to
									 the <guimenuitem>Insert Newline and Indent</guimenuitem> action.
									 If you bind it to <guimenuitem>Insert Newline</guimenuitem> from
									 <guimenuitem>Global Options - Shortcuts</guimenuitem>, that will
									 disable the auto-indent behavior. There is no way to "toggle"
									 this feature. </para>
								</answer>
						</qandaentry>
						<qandaentry>
								<question id="text-indent">
										<para>How do I indent or unindent selections of text?</para>
								</question>

								<answer>
										<para>Using jEdit's default configuration, you can indent a
										selection of text by pressing <keycombo action="simul">
														<keycap>ALT</keycap>

														<keycap>RIGHT</keycap>
												</keycombo>. Unindent a selection by pressing <keycombo
														action="simul">
														<keycap>ALT</keycap>

														<keycap>LEFT</keycap>
												</keycombo>.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="text-line-numbers">
										<para>Is there a way to automatically view line numbers when
										a buffer is opened?</para>
								</question>

								<answer>
										<para>Select <guimenuitem>Global Options</guimenuitem>,
										<guimenuitem>Gutter</guimenuitem> option pane, and check the
										<guimenuitem>Line Numbering</guimenuitem> check box.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="smart-quote">
										<para>Does jEdit know smart quotes? In .tex files I would
										like to use <userinput>``</userinput> or
										<userinput>''</userinput> instead of
										<userinput>"</userinput>.</para>
								</question>

								<answer>
										<para>While jEdit can display any character provided by a
										supported encoding set and enter any character supported by
										a keyboard driver, it does not have the ability to insert
										<quote>smart quote</quote> pairs automatically as some word
										processors do. This would require a BeanShell macro to
										modify quoted text.</para>

										<para>The built-in Abbreviations feature (<guimenu>Global Options</guimenu> <guimenuitem>Abbreviations</guimenuitem>) as well as the Accents and CharacterMap plugins can also help you
										type international characters.</para>

										<para>You also have the option of using a TeX macro (or, in
										LaTeX, a pair of environment tags) to have the standard
										double quotation mark <userinput>"</userinput> transformed
										into the appropriate opening or closing smart quotes without
										the need to keep track of when quoted text opens or
										closes.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="text-display-spaces">
										<para>The display of spaces as a character in the editor is
										annoying. How can I disable those small square boxes?</para>
								</question>

								<answer>
										<para>This is controlled by the WhiteSpace plugin. To change
										your settings to disable display of whitespace characters,
										<guimenuitem>Plugin options&gt;WhiteSpace</guimenuitem>.
										You can separately configure the display of spaces, tabs, and other whitespace
										characters.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="text-i18n">
										<para>Does jEdit support i18n?</para>
								</question>

								<answer>
										<para>When editing text documents, jEdit supports any
										available encoding scheme, and can open files with a
										specified encoding other than the default encoding of your
										operating system using the
										<guimenu>File</guimenu>&gt;<guisubmenu>Reload with Encoding
										</guisubmenu> action.</para>

										<para>With respect to menu labels, message strings and other
										GUI elements, the jEdit project team now supports localization files for different languages.
										How well they are maintained is up to the individual members of the community who help to maintain them. </para>
								</answer>
						</qandaentry>
				</qandadiv>

				<!--********************************************************* Source -->

				<qandadiv id="source-compile">
						<title>Compiling source code</title>

			<qandaentry>
								<question id="jedit-compile">
										<para>How do you set the classpath for compiling Java files in jEdit?</para>
								</question>
								<answer>

									<para>The classpath can be set from ProjectViewer's project properties
									on a per-project basis. The <ulink
									url="/Classpath.jar!/index.html">ClassPath plugin</ulink> provides this
									option pane to ProjectViewer. JavaSideKick uses it for completion, and
									other Java plugins should also. </para>

								</answer>
						</qandaentry>

						<qandaentry>
								<question id="compile-java">
										<para>How do I compile my Java source in JEdit?</para>
								</question>

								<answer>
										<para>There are a number of plugins that you can use to
										compile Java source code. You can run a Java compiler on the
										command line in the <quote>System</quote> shell of the
										<application>Console</application> plugin. When JCompiler is updated,
										you can use that again. Many Java projects
										can be built with Apache Ant, and that is how we build jEdit.
										You can use the <quote>Ant</quote> commandos from the
										<application>Console</application> plugin to run ant from jEdit,
										and parse the error messages for ErrorList. Also, the
										<application>Antelope</application> or
										<application>AntFarm</application> plugins provide a more
										Eclipse-like GUI front-end for Apache Ant.
										Apache Ant uses a <filename>build.xml</filename> file to specify build
										commands and dependencies.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="source-new-editmode">
										<para>How do I create a new edit mode?</para>
								</question>

								<answer>
										<para>Take a look at the <quote>Writing Edit Modes</quote>
										section of the User's Guide. Basically, you have to write an
										XML file containing data on the mode's file extensions and
										buffer and syntax highlighting properties, then add
										information about the new mode file to a second XML file
										containing a catalog of modes.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="source-docbook">
										<para>Does jEdit support DocBook tags?</para>
								</question>

								<answer>
										<para>The application contains editing modes for both SGML
										and XML. Using jEdit abbreviations, you can quickly insert
										commonly-typed tags with a couple of keystroke. There are a
										number of abbreviations in the XML and SGML modes that
										create pairs of DocBook tags on the fly.</para>

										<para>You can get validation, tree-browsing, auto-complete,
										and auto-closing tags with the XML plugin, a very advanced
										XML editing tool.</para>

										<para>With whe XInsert or Template plugin you can create
										multi-layered DocBook elements.</para>

										<para>There are other macros targeting DocBook available
										from the <ulink url="http://community.jedit.org">jEdit
										Community</ulink> web site that you can use or adapt for
										your own purposes.</para>
								</answer>
						</qandaentry>
				</qandadiv>

				<!--******************************************************* Settings -->

				<qandadiv id="emacs-tricks">
						<title>Tips for Emacs users</title>

						<qandaentry>
								<question id="settings-emacsctrle">
										<para>How do I get Emacs-like key bindings out of the box? </para>
								</question>

								<answer>
										<para>As of jEdit 5.1, it is much easier than before:  <guimenuitem> Global Options - Shortcuts - Choose Keymap: Emacs</guimenuitem>. Customize it by setting your own shortcuts to make it more like your flavor of Emacs. Emacs macros are contributed by Brian Clapper.
										</para>
								</answer>
						</qandaentry>

				</qandadiv>

				<qandadiv id="customize-other">
						<title>Other Settings and Options</title>

						<qandaentry>
								<question id="settings-change-font">
										<para>How can I change the font used for menu labels and
										other elements of jEdit's user interface?</para>
								</question>

								<answer>
		<para>Select the <guimenuitem>Global Options</guimenuitem>,
		<guimenuitem>Appearance</guimenuitem> option pane. When you
		select the <quote>Metal</quote> look and feel you can also
		select the fonts used for various displayed items.</para>
								</answer>
						</qandaentry>
						<qandaentry>
								<question id="antialiased-text-everywhere">
										<para>How can I get antialiased text everywhere, even dockables and menus? </para>
								</question>
								<answer>
									<para>
										See the <ulink url="../users-guide/jvm-options.html">page on JVM options</ulink> in the users guide.
									</para>
					</answer>
						</qandaentry>
						<qandaentry>
								<question id="settings-add-classpath">
										<para>I want to add a directory to the classpath. I did this
										in the standalone BeanShell with ease by using the
										<classname>addClassPath(String)</classname> method. but this
										doesn't work in a macro. How could I manage the classpath in
										jEdit?</para>
								</question>

								<answer>
										<para>The implementation of BeanShell used in jEdit does not
										use BeanShell's class loader. The script method contained in
										loadJarClasses.bsh (found in the Downloads section of <ulink
										url="http://community.jedit.org">jEdit Community</ulink>)
										should work if you know the path to a specific class file or
										class archive.</para>
								</answer>
						</qandaentry>

						<qandaentry>
								<question id="settings-unlisted">
										<para>Are there any hidden features?</para>
								</question>

								<answer>
										<para>Yes. You can access them by binding a shortcut to the
										action in question. You will find a complete list of
										available commands under the
										<guimenuitem>Shortcuts</guimenuitem> area in the
										<guimenuitem>Global Options</guimenuitem>.</para>
								</answer>
						</qandaentry>
				</qandadiv>
		</qandaset>
</section>
