/jEdit/tags/jedit-4-2-pre14/doc/FAQ/faq-use.xml

<!-- jEdit buffer-local properties:                      -->
<!-- :indentSize=4:noTabs=false:maxLineLen=72:tabSize=4: -->
<!-- :xml.root=faq.xml:                                  -->

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

<sect1 id="usage"><title>Usage Questions</title>
<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>&nbsp;
            <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>&nbsp;
            <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="dirty-file"><para>
            Why does the screen display continue to mark a file as
            <quote>dirty</quote> after I undo all changes made to the buffer?
        </para></question>
        <answer><para>
            This is a problem in jEdit 3.2.2 that has been fixed in version 4.0 or newer.
            You should upgrade.
         </para></answer>
     </qandaentry>

    <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>&#x20ac;</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>
            If you are using jEditLauncher, you associate the file extension with
            <replaceable>[full path]</replaceable><userinput>\jedit.exe
            &quot;%1&quot;</userinput>.
        </para>
        <para>
            The jEditLauncher package 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 or a Windows file menu.  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>

     <qandaentry>
        <question id="file-delete-recurse"><para>
            Can I recursively delete a directory's files in jEdit's
            File Browser?
        </para></question>
        <answer><para>
            No. The feature is being planned for inclusion in a future
            jEdit version.  The fastest way to do this in the current
            jEdit version is to use the Console plugin and a native
            command.
        </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="text-display-lucida">
		<para>
			With JDK 1.3 and Lucida Console font I have problems displaying syntax
			highlighting text. Sometimes the fonts become italicized or bold without any
			reason.
		</para>
	</question>
	<answer>
		<para>
			The Lucida Console font does not come in a bold style. Various platforms and
			native applications will render the bold style by overprinting, but this appears
			not to work correctly in your installation. Unfortunately, there is nothing
			jEdit can do about this, and the best thing to do is to select another font.
		</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>&quot;</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>
      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>&quot;</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>
			Beginning with version 4.0pre4, jEdit has soft wrap capability which 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>

<qandaentry>
	<question id="text-wrap">
		<para>
			When using soft wrap, why does it scroll per physical line and not screen line?
		</para>
	</question>
	<answer>
		<para>
			This will change in jEdit 4.2.
		</para>
	</answer>
</qandaentry>

</qandadiv>

<!--******************************************************* Printing -->
	
    <qandadiv id="text-print"><title>Printing text</title>

<qandaentry>
	<question id="text-print-improve">
		<para>
			What can I do to improve printing performance?
		</para>
	</question>
	<answer>
		<para>
			Prior to release of version 1.4 of the Java Development Kit (JDK), printing
      has been one of the weak
      areas of the Java platform. If you are using JDK version 1.3, here
      are a few suggestions on improving printing performance.
    </para>
    <para>
			One simple way to improve printing is to use the InfoViewer plugin to display and
      print a text file in your favorite Web browser. You can also write a macro that
      saves a buffer and then passes the buffer's file name (using the method
			<filename>buffer.getPath()</filename>) to an external print utility. The file
			<filename>prettyprint.bat</filename> in the
			Downloads section of <ulink url="http://community.jedit.org">jEdit
			Community</ulink> is an example of this approach using a
			Windows batch file and Ghostscript. You can then change the
			<keycombo action="simul"><keycap>CTRL</keycap><keycap>P</keycap></keycombo>
			keyboard shortcut to point to your printing macro.
		</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> shell in 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, and there are a
			number of abbreviations in the SGML mode that create pairs of DocBook tags on
			the fly. You can auto-complete closing tags with the XML plugin, and with the
			XInsert or Template plugin you can create multi-layered DocBook elements. The
			installation macro <filename>Insert_Tag.bsh</filename> is useful for creating
			or inserting tag pairs in existing text, and 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="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-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-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>