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

    <!-- jEdit buffer-local properties:                      -->

    <!-- :indentSize=4:noTabs=false:tabSize=4: -->

    <!-- :xml.root=faq.xml:                                  -->

    <!-- jEdit FAQ                                           -->

    <!-- Copyright (C) 2003 John Gellene, Kris Kopicki       -->

    <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
                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
                    Options</guimenuitem>, then select the
                    <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
                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
                    Options</guimenuitem>, then under <guimenuitem>Loading &amp;
                    Saving</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>Only Unicode can be detected when a file is loaded.
                    For other encodings, you must specify the encoding when the
                    file is loaded if you do not wish to use the default
                    encoding for your operating system.</para>

                    <para>There are a few features that can help you navigate
                    through encoding issues. 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
                    <guimenuitem>Loading &amp; Saving</guimenuitem> pane of the
                    Global Options dialog; if you do not, jEdit adopts your
                    operating system's default encoding as its own default. 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.bat</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="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><guimenuitem>Select Utilities&gt;Global
                    Options</guimenuitem>, and in the
                    <guimenuitem>Gutter</guimenuitem> option pane select 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 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-softwrap">
                    <para>Does jEdit have a <quote>soft</quote> wrap text
                    mode?</para>
                </question>

                <answer>
                    <para>jEdit's 4.3's soft wrap mode, and especially its wrap
                    to margin=0, is one of its many features that just works
                    better than it does in most other editing environments. Soft
                    Wrap with margin=0 was unavailable in jEdit 4.2, but users
                    of 4.1 will remember it well. When you set SOFT WRAP with a
                    margin=0, you don't need to use the horizontal scroller
                    anymore. It's just as simple as that.</para>

                    <para>jEdit wrap capability can be activated for a specific
                    buffer, specific editing modes, or for all documents by
                    default. In prior versions, both the text wrap feature and
                    the <guimenuitem>Edit&gt;Text&gt;Format
                    Paragraph</guimenuitem> command insert <quote>hard</quote>
                    end of line characters. This <quote>hard wrap</quote>
                    feature remains available as an option for buffers and
                    editing modes.</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,
                    select <guimenuitem>Utilities&gt;Global
                    Options</guimenuitem>, then select <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>Commands</guimenu>&gt;<guisubmenu>Encoding
                    </guisubmenu> from the File System Browser.</para>

                    <para>With respect to menu labels, message strings and other
                    GUI elements, the jEdit project team currently does not have
                    the resources to maintain multiple property sets in
                    languages other than English, particularly since the
                    development effort is continuing at a rapid pace. There has
                    not been great demand for this in any event. This may be
                    because jEdit is primarily a tool for programmers, and the
                    use of English as a common first or second language is
                    widespread in the global programming community. This
                    decision may be reconsidered when the application has
                    further matured and if more individuals express a
                    willingness to be involved in translation work.</para>
                </answer>
            </qandaentry>
        </qandadiv>

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

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

            <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. If you are using
                    the JCompiler plugin, you will have a
                    <quote>JCompiler</quote> shell in the
                    <application>Console</application> plugin, and you can run
                    the <userinput>compile</userinput> command for the current
                    file, or the <userinput>compilepkg</userinput> command on
                    all of the current directory's source code files. You can
                    also use the <quote>Ant</quote> commandos from the
                    <application>Console</application> plugin or the
                    <application>AntFarm</application> plugin to run complex
                    builds on a project of source code files, using 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>

            <para>For more emacs help, check out <ulink
            url="http://www.clapper.org/software/jedit/">this site</ulink> for
            more emacs macros.</para>

            <qandaentry>
                <question id="settings-emacstab">
                    <para>Can I have an emacs style tab key (tab anywhere in a
                    line re-indents it)?</para>
                </question>

                <answer>
                    <para>Yes. You can do this by rebinding the
                    <keycode>tab</keycode> key to <command>Indent Selected
                    Lines</command> in the <guimenuitem>Global
                    Options</guimenuitem>.</para>
                </answer>
            </qandaentry>

            <qandaentry>
                <question id="settings-emacsctrle">
                    <para>How do I map Ctrl-E to go to the end of the
                    line?</para>
                </question>

                <answer>
                    <para>jEdit has it set up as a 2-key shortcut. In order to
                    make Ctrl-E a one-key shortcut again, you first have to
                    redefine all of the Ctrl-E prefix shortcuts to mean
                    something else.</para>

                    <para><literal>jedit_keys.props</literal> shows you all of
                    the current keyboard bindings. As you can see, Ctrl-e is
                    used for many things in jEdit. If you want to redefine it to
                    be a single-key shortcut, first thing you need to do is
                    decide on another Ctrl-key to use as a prefix, to redefine
                    jEdit's fold features. I recommend using Ctrl-Q as the
                    prefix, and if you want to use Ctrl-Q to quit, you have to
                    hit Ctrl-Q twice. Cut and paste the below shortcuts into
                    your own properties file.</para>

                    <programlisting>
# emacs end of line
end.shortcut2=C+e
# Ctrl-Q twice to quit
exit.shortcut=C+q C+q
# C+q is our new C+e prefix
#{{{ C+q C+X

# Unused: f, h, q, y
copy-append.shortcut=C+q C+a
search-in-open-buffers.shortcut=C+q C+b
range-comment.shortcut=C+q C+c
search-in-directory.shortcut=C+q C+d
replace-and-find-next.shortcut=C+q C+g
ignore-case.shortcut=C+q C+i
scroll-to-current-line.shortcut=C+q C+j
line-comment.shortcut=C+q C+k
select-line-range.shortcut=C+q C+l
add-marker.shortcut=C+q C+m
center-caret.shortcut=C+q C+n
open-path.shortcut=C+q C+o
vertical-paste.shortcut=C+q C+p
replace-in-selection.shortcut=C+q C+r
save-all.shortcut=C+q C+s
toggle-line-numbers.shortcut=C+q C+t
cut-append.shortcut=C+q C+u
paste-previous.shortcut=C+q C+v
close-all.shortcut=C+q C+w
regexp.shortcut=C+q C+x
paste-deleted.shortcut=C+q C+y
redo.shortcut=C+q C+z
#}}}

#{{{ C+q C+non-alpha
left-docking-area.shortcut=C+q C+LEFT
top-docking-area.shortcut=C+q C+UP
right-docking-area.shortcut=C+q C+RIGHT
bottom-docking-area.shortcut=C+q C+DOWN

prev-marker.shortcut=C+q C+COMMA
next-marker.shortcut=C+q C+PERIOD
prev-bracket.shortcut=C+q C+OPEN_BRACKET
next-bracket.shortcut=C+q C+CLOSE_BRACKET
close-docking-area.shortcut=C+q C+BACK_QUOTE
#}}}

#{{{ C+q X
# Unused: b e g h j k m o q t y z
add-explicit-fold.shortcut=C+q a
collapse-all-folds.shortcut=C+q c
delete-paragraph.shortcut=C+q d
format-paragraph.shortcut=C+q f
find-previous.shortcut=C+q g
invert-selection.shortcut=C+q i
select-line.shortcut=C+q l
narrow-to-fold.shortcut=C+q n n
narrow-to-selection.shortcut=C+q n s
select-paragraph.shortcut=C+q p
remove-trailing-ws.shortcut=C+q r
select-fold.shortcut=C+q s
insert-literal.shortcut=C+q v
select-word.shortcut=C+q w
parent-fold.shortcut=C+q u
expand-all-folds.shortcut=C+q x
#}}}
</programlisting>
                </answer>
            </qandaentry>

            <qandaentry>
                <question id="emacs-ctrl-k">
                    <para>What about ctrl-K?</para>
                </question>

                <answer>
                    <para>Check out <literal>macros/Emacs_Ctrl_K.bsh</literal>.
                    Bind it to Ctrl-k from the shortcuts option pane.</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
                    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
                    Options</guimenuitem>, then the
                    <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="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>
</sect1>