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

<!-- jEdit buffer-local properties: -->
<!-- :tabSize=1:indentSize=1:noTabs=true: -->

<chapter id="files"><title>Working With Files</title>
 <sect1 id="creating"><title>Creating New Files</title>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>New</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>N</keycap></keycombo>) opens a new
   untitled buffer. When it is saved, a file will be created on disk.
   Another way to create a new file is to specify a non-existent file
   name when starting jEdit from your operating system's command line.
  </para>
 </sect1>
 <sect1 id="opening"><title>Opening Files</title>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Open</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>O</keycap></keycombo>) displays
   a file selector dialog box and loads the specified file into a new
   buffer. Multiple files can be opened at once by holding down
   <keycap>Control</keycap> while clicking on them in the file system browser.
   The file selector dialog box also supports auto-completion; when you begin
   typing a the name of an existing file in the file name field, jEdit will
   attempt to complete it; if the suggested completion is wrong, either select
   an alternative with the arrow keys or keep typing.
  </para>
  <para>
   Files that you do not have write access to are opened in read-only
   mode, and editing will not be permitted.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Insert</guimenuitem> displays
   a file selector dialog box and inserts the specified file into the current
   buffer.
  </para>
  <para>
   The <guimenu>File</guimenu>&gt;<guimenuitem>Recent Files</guimenuitem> menu
   lists recent files. When a recent file is opened, the caret
   is automatically moved to its previous location in that file.
   The number of recent files to remember can be changed and caret
   position saving can be disabled in the <guibutton>General</guibutton> pane of
   the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />.
  </para>
  <para>
   The <guimenu>Utilities</guimenu>&gt;<guimenuitem>Current Directory</guimenuitem>
   menu lists all files and directories in the current buffer's directory.
   Selecting a file opens it in a buffer for editing; selecting a directory
   opens it in the file system browser (see <xref linkend="vfs-browser" />).
  </para>
  <tip>
   <para>
    jEdit supports transparent editing of GZipped files; if a file begins with
    the GZip <quote>magic number</quote>, it is automatically decompressed
    before loading and compressed when saving. To compress an existing file,
    you need to change a setting in the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer Options</guimenuitem>
    dialog box; see <xref linkend="buffer-opts"/> for details.
   </para>
  </tip>
 </sect1>
 <sect1 id="saving"><title>Saving Files</title>
  <para>
   Changed made to a buffer do not affect the file on disk until the
   buffer is <firstterm>saved</firstterm>.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Save</guimenuitem> (shortcut:
   <keycombo><keycap>Control</keycap><keycap>S</keycap></keycombo>)
   saves the current buffer to disk.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Save All</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycombo><keycap>Control</keycap><keycap>S</keycap></keycombo>) saves all
   open buffers to disk, asking for confirmation first.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Save As</guimenuitem> saves the
   buffer to a different specified file on disk. The buffer is then
   renamed, and subsequent saves also save to the specified file. Note that
   using this command to save over an already open buffer will close that
   buffer, to avoid having two buffers open with the same path name.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Save a Copy As</guimenuitem> saves
   the buffer to a different specified file on disk, but doesn't rename the
   buffer, and doesn't clear the <quote>modified</quote> flag. Note that using
   this command to save over an already open buffer will automatically reload
   that buffer.
  </para>
  <sidebar><title>How files are saved</title>
   <para>
    To prevent data loss in the unlikely case that jEdit should crash in the
    middle of saving a file, files are first saved to
    <filename>#<replaceable>filename</replaceable>#save#</filename>. If this
    operation is successful, the original file is replaced with the temporary
    file.
   </para>
   <para>
    However, in some situations, this behavior is undesirable. For example,
    on Unix saving files this way will result in the owner and group of the
    file being reset. If this bothers you, you can disable this so-called
    <quote>two-stage save</quote> in the <guibutton>Loading and Saving</guibutton>
    pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box.
   </para>
  </sidebar>
  <sect2><title>Autosave and Crash Recovery</title>
   <para>
    The autosave feature protects your work from computer crashes and
    such. Every 30 seconds, all buffers with unsaved changes are
    written out to their respective file names, enclosed in hash
    (<quote>#</quote>) characters. For example, <filename>program.c</filename>
    will be autosaved to <filename>#program.c#</filename>.
   </para>
   <para>
    Saving a buffer using
    one of the commands in the previous section automatically deletes the
    autosave file, so they will only ever be visible in the unlikely
    event of a jEdit (or operating system) crash.
   </para>
   <para>
    If an autosave file is
    found while a buffer is being loaded, jEdit will offer to recover the
    autosaved data.
   </para>
   <para>
    The autosave feature can be configured
    in the <guibutton>Loading and Saving</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box; see <xref linkend="global-opts" />.
   </para>
  </sect2>
  <sect2><title>Backups</title>
   <para>
    The backup feature can be used to roll back to the previous version
    of a file after changes were made. When a buffer is saved
    for the first time after being opened, its original contents are
    <quote>backed up</quote> under a different file name.
   </para>
   <para>
    The default behavior is to back up the original contents
    to the buffer's file name suffixed with a tilde (<quote>~</quote>).
    For example, <filename>paper.tex</filename> will be backed up to
    <filename>paper.tex~</filename>.
   </para>
   <para>
    The backup feature can also be configured in
    the <guibutton>Loading and Saving</guibutton> pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box. It can be customized to do any of the following:
   </para>
   <itemizedlist>
    <listitem><para>
     Save numbered backups, named
     <filename><replaceable>filename</replaceable>~<replaceable>number</replaceable>~</filename>
    </para></listitem>
    <listitem><para>
     Add a prefix to the backed-up file name
    </para></listitem>
    <listitem><para>
     Adds a suffix to the backed-up file name (the default is <quote>~</quote>)
    </para></listitem>
    <listitem><para>
     Backups can optionally be saved in a specified backup directory, instead of
     the directory of the original file. This can reduce clutter
    </para></listitem>
    <listitem><para>
     Backups can also optionally be created every time a buffer is saved;
     as mentioned above, the default is to only create a backup the first
     time a buffer is saved after being opened.
    </para></listitem>
   </itemizedlist>
  </sect2>
 </sect1>
 <sect1 id="line-separators"><title>Line Separators</title>
  <para>
   The three major operating systems use different conventions to mark
   line endings in text files.
   The MacOS uses Carriage-Return characters (<literal>\r</literal> in
   Java-speak) for that purpose. Unix
   uses Newline characters (<literal>\n</literal>). Windows uses both
   (<literal>\r\n</literal>). jEdit can read and write files in all three formats.
  </para>
  <para>
   When loading a file, the line separator used within is automatically
   detected, and will be used when saving a file back to disk. The line
   separator used when saving the current buffer can be changed in the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
   Options</guimenuitem> dialog box; see <xref linkend="buffer-opts" />.
  </para>
  <para>
   By default, new files are saved with your operating system's native line
   separator. This can be changed in the
   <guibutton>Loading and Saving</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />. Note that changing this
   setting has no effect on existing files.
  </para>
 </sect1>
 <sect1 id="encodings"><title>Character Encodings</title>
  <para>
   If you edit files in different human languages, you will most likely be
   familiar with the concept of a <quote>character encoding</quote>. The gist
   of the idea is that there are several ways to store a particular character
   on disk. The current buffer's encoding is shown in the status
   bar.
  </para>
  <para>
   jEdit can use any
   encoding supported by the Java platform.
   The default encoding, used to load and save files for which no
   other encoding is specified, can be set in the <guibutton>Loading and
   Saving</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />. The setting is presented as
   an editable combo box; the combo box
   contains a few of the more frequently used encodings, but the Java platform
   defines practically hundreds more you can use.
  </para>
  <para>
   Unfortunately, there
   is no way to obtain a list of all supported encodings in Java, and the
   set is constantly changing with each Java version. So to play it safe, jEdit
   has a few pre-defined defaults, but allows you to use any other supported
   encoding, assuming you know its name.
  </para>
  <para>
   Unless you change the default encoding, jEdit will use your operating
   system's native default; <literal>MacRoman</literal> on the MacOS,
   <literal>Cp1252</literal> on Windows, and <literal>8859_1</literal> on
   Unix.
  </para>
  <para>
   To open a file stored in an encoding other than the default, select the
   encoding from the
   <guimenu>Commands</guimenu>&gt;<guisubmenu>Encoding</guisubmenu> menu of
   the open file dialog box or file system browser window, then open the file.
  </para>
  <para>
   The encoding to use when saving an open file
   can be set in the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Buffer
   Options</guimenuitem> dialog box.
  </para>
  <para>
   If a file is opened
   without an explicit encoding specified and it appears in the recent file list,
   jEdit will use the encoding last used
   when working with that file; otherwise the default encoding will be used.
  </para>
  <sect2><title>Commonly Used Encodings</title>
   <para>
    The most frequently-used character encoding is ASCII, or <quote>American 
    Standard Code for Information Interchange</quote>. ASCII encodes Latin
    letters used in English, in addition to numbers and a range of punctuation
    characters.
    The ASCII character set consists of 127 characters, and it is unsuitable
    for anything but English text (and other file types which only use English
    characters, like most program source). jEdit will load and save files as
    ASCII if the <literal>ASCII</literal> encoding is used.
   </para>
   <para>
    Because ASCII is unsuitable for international use, most operating
    systems use an 8-bit extension of ASCII, with the first 127 characters
    remaining the same, and the rest used to encode accents, umlauts, and
    various less frequently used typographical marks. Unfortunately, the three
    major
    operating systems all extend ASCII in a different way. Files written by
    Macintosh programs can be read using the <literal>MacRoman</literal>
    encoding; Windows text files are usually stored as
    <literal>Cp1252</literal>. In the Unix world, the <literal>8859_1</literal>
    (otherwise known as <literal>Latin1</literal>) character encoding has found
    widespread usage.
   </para>
   <para>
    Windows users are accustomed to dealing with files in a wide range of
    character sets, known as <firstterm>code pages</firstterm>. Java supports a
    large number of code pages; the encoding name consists of the text
    <quote>Cp</quote>, followed by a number.
   </para>
   <para>
    Raw Unicode files are quite rare, but can be read and written with the
    <literal>Unicode</literal> encoding.
    One reason raw Unicode has not found widespread usage for storing files on
    disk is that each character takes up 16 bits. Most other character sets
    devote 8 bits per character, which saves space. The <literal>UTF8</literal>
    encoding encodes frequently-used Unicode characters as 8 bits, with
    less-frequent ones stretching up to 24 bits. This saves space but allows the
    full range of Unicode characters to be represented.
   </para>
   <para>
    Many common cross-platform international character sets are supported;
    <literal>KOI8_R</literal> for Russian text, <literal>Big5</literal> and
    <literal>GBK</literal> for Chinese, and <literal>SJIS</literal> for
    Japanese.
   </para>
  </sect2>
 </sect1>
 <sect1 id="vfs-browser"><title>The File System Browser</title>
  <para>
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>File System
   Browser</guimenuitem> displays a file system browser.
   By default, the file system browser is shown in a floating window;
   it can be set to dock into the view in the <guibutton>Docking</guibutton>
   pane of the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
   Options</guimenuitem> dialog box; see <xref linkend="docking" />.
  </para>
  <para>
   The file system browser can be customized in the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box.
  </para>
  <sect2><title>Navigating the File System</title>
   <para>
    The directory to browse is specified in the <guibutton>Path</guibutton> text
    field. Clicking the mouse in the text field automatically selects its
    contents allowing a new path to be quickly typed in. If a relative path is
    entered, it will be resolved relative to the current path. This text field
    remembers previously entered strings; see <xref linkend="history" />.
    Previously browsed directories are also listed in the
    <guimenu>Utilities</guimenu>&gt;<guisubmenu>Recent Directories</guisubmenu>
    menu; selecting one opens it in the file system browser.
   </para>
   <para>
    To browse higher up in the directory hierarchy, click one of the parent
    directories in the parent directory list.
   </para>
   <para>
    Files and directories in the file list are shown in different colors
    depending on what glob patterns their names match. The patterns and colors
    can be customized in the
    <guibutton>File System Browser</guibutton>&gt;<guibutton>Colors</guibutton>
    pane of the
    <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
    dialog box.
   </para>
   <para>
    To browse a listed directory, double-click it (or if you have a three-button
    mouse, you can click the middle mouse button as well). Alternatively, click
    the disclosure
    widget next to a directory to list its contents in place.
   </para>
   <para>
    Open files in the file list are shown with their file names underlined.
    Single-clicking an open file will select the appropriate buffer in the current
    view. Unopened files can be opened for editing by double-clicking (or by
    clicking the middle mouse button). If you hold down <keycap>Shift</keycap>
    while double-clicking (or middle-clicking), the file will be opened in a new
    view.
   </para>
   <para>
    Clicking a file or directory with the right mouse button displays a popup
    menu containing file manipulation commands. Note that attempting to delete
    a directory containing files will give an error;
    only empty directories can be deleted.
   </para>
   <para>
    If you only want to see a specific set of files (for example,
    those whose names end with <filename>.java</filename>), enter a glob pattern
    in the <guibutton>Filter</guibutton> text field.
    See <xref linkend="globs" /> for information about glob patterns.
    This text fields remembers previously entered strings;
    see <xref linkend="history" />.
   </para>
   <tip>
    <para>
     The file list sorting algorithm used in jEdit handles numbers in file names
     in an intelligent manner. For example, a file named
     <filename>section10.xml</filename> will be placed after a file named
     <filename>section5.xml</filename>. A conventional letter-by-letter
     sort would have placed these two files in the wrong order.
    </para>
   </tip>
  </sect2>
  <sect2><title>The Tool Bar</title>
   <para>
    The file system browser has a tool bar containing a number of icons.
    These buttons correspond to the items in the <guibutton>Commands</guibutton>
    menu described below; the only menu item that does not have a corresponding
    tool bar button is <guimenuitem>Show Hidden Files</guimenuitem>.
   </para>
  </sect2>
  <sect2><title>The Commands Menu</title>
   <para>
    Clicking the <guibutton>Commands</guibutton> button displays a menu
    containing the following items:
   </para>
   <itemizedlist>
    <listitem><para><guimenuitem>Parent Directory</guimenuitem> - moves up in
    the directory hierarchy.</para></listitem>
    <listitem><para><guimenuitem>Reload Directory</guimenuitem> - reloads the
    file list from disk.</para></listitem>
    <listitem><para><guimenuitem>Local Drives</guimenuitem> - displays all
    local drives. On Windows, this will be a list of
    drive letters; on Unix, the list will only contain one entry, the
    root directory.</para></listitem>
    <listitem><para><guimenuitem>Home Directory</guimenuitem> - displays your
    home directory.</para></listitem>
    <listitem><para><guimenuitem>Directory of Current Buffer - displays the
    directory containing the currently active buffer.</guimenuitem></para></listitem>
    <listitem><para><guimenuitem>New File</guimenuitem> - opens an
    <filename>Untitled</filename> file in the current directory. The file will
    not actually be created on disk until it is saved.</para></listitem>
    <listitem><para><guimenuitem>New Directory</guimenuitem> - creates a new
    directory after prompting for the desired name.</para></listitem>
    <listitem><para><guimenuitem>Search in Directory</guimenuitem> -
    displays the
    search and
    replace dialog box for searching in all files in the current directory. If a
    file is selected, its extension becomes the file name filter for the search;
    otherwise, the file name filter entered in the browser is used.
    See <xref linkend="search-replace" /> for details.</para></listitem>
    <listitem><para><guimenuitem>Show Hidden Files</guimenuitem> - toggles if
    hidden files are to be shown in the file list.</para></listitem>
   </itemizedlist>
  </sect2>
  <sect2><title>The Plugins Menu</title>
   <para>
    Clicking the <guibutton>Plugins</guibutton> button displays a menu
    containing commands for browsing plugin file systems. For information
    about plugins, see <xref linkend="using-plugins" />.
   </para>
  </sect2>
  <sect2><title>The Favorites Menu</title>
   <para>
    Clicking the <guibutton>Favorites</guibutton> button displays a menu
    showing all directories in the favorites list, along with an
    <guimenuitem>Add to Favorites</guimenuitem> command that adds the current
    directory to the favorites, and an <guimenuitem>Edit Favorites</guimenuitem>
    command that shows the favorites list in the file system view, allowing items
    to be removed by right-clicking on them and selecting
    <guimenuitem>Delete</guimenuitem> from the resulting popup menu.
   </para>
  </sect2>
  <sect2><title>Keyboard Shortcuts</title>
   <para>
    The file system browser can be navigated from the keyboard:
   </para>
   <itemizedlist>
    <listitem><para><keycap>Enter</keycap> - opens the currently selected file or
    directory.</para></listitem>
    <listitem><para><keycap>Left</keycap> - goes to the current directory's parent.
    </para></listitem>
    <listitem><para><keycap>Up</keycap> - selects previous file in list.
    </para></listitem>
    <listitem><para><keycap>Down</keycap> - selects next file in list.
    </para></listitem>
    <listitem><para><keycap>/</keycap> - displays all
    local drives.</para></listitem>
    <listitem><para><keycap>~</keycap> - displays your home directory.
    </para></listitem>
    <listitem><para><keycap>-</keycap> - displays the directory containing
    the current buffer.</para></listitem>
    <listitem><para>Typing the first few characters of
    a file's name will select that file.
    </para></listitem>
   </itemizedlist>
   <para>
    The file system view, and not the <guibutton>Path</guibutton> or
    <guibutton>Filter</guibutton> text fields must have keyboard focus for these
    shortcuts to work.
   </para>
  </sect2>
 </sect1>
 <sect1 id="reloading"><title>Reloading Files</title>
  <para>
   If an open buffer is modified on disk by another application, a warning
   dialog box is displayed, offering to either continue editing
   (and lose changes made by the other application)
   or reload the buffer from disk (and lose any unsaved changes in jEdit). This
   feature can be disabled in the <guibutton>General</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Reload</guimenuitem> can be used to
   reload the current buffer from disk at any other
   time; a confirmation dialog box will be displayed first if the buffer
   has unsaved changes.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Reload All</guimenuitem>
   discards unsaved changes in all open buffers and reload them from disk,
   asking for confirmation first.
  </para>
 </sect1>
 <sect1 id="threaded-io"><title>Multi-Threaded I/O</title>
  <para>
   To improve responsiveness and perceived performance,
   jEdit executes all input/output operations asynchronously.
   While I/O is in progress, the status bar displays the number of
   remaining I/O operations.
   The <guimenu>Utilities</guimenu>&gt;<guisubmenu>Troubleshooting</guisubmenu>&gt;<guimenuitem>I/O
   Progress
   Monitor</guimenuitem> command displays a window with more detailed status
   information and progress meters. This window is floating by default, but
   it can be set to dock into the view in the
   <guibutton>Docking</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="docking" />. I/O requests can also be aborted in
   this window, however note that aborting a buffer save can result in data loss.
  </para>
  <para>
   By default, four I/O threads are created, which means that up
   to four buffers can be loaded or saved simultaneously. The number of
   threads can be changed in the
   <guibutton>Loading and Saving</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global Options</guimenuitem>
   dialog box; see <xref linkend="global-opts" />. Setting the number to zero
   disables multi-threaded I/O completely; doing this is not recommended.
  </para>
 </sect1>
 <sect1 id="printing"><title>Printing Files</title>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Print</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>P</keycap></keycombo>)
   will print the current buffer. By default, the printed output will have
   syntax highlighting, and each page will have a header with the file name,
   and a footer with the current date/time and page number. The appearance of
   printed output
   can be customized in the <guibutton>Printing</guibutton> pane of the
   <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
   Options</guimenuitem> dialog box. The following settings can be changed:
  </para>
  <itemizedlist>
   <listitem><para>The font to use when printing</para></listitem>
   <listitem><para>If a header with the file name should be printed on each
   page.</para></listitem>
   <listitem><para>If a footer with the page number and current date should be
   printed on each page.</para></listitem>
   <listitem><para>If line numbers should be printed.</para></listitem>
   <listitem><para>If the output should be colored according to the current
   mode's syntax highlighting rules (might look bad on gray-scale
   printers); otherwise, only syntax styles will be applied.</para></listitem>
   <listitem><para>The tab size to use when printing - this will usually be
   less than the text area tab size, to conserve space in the printed output.
   </para></listitem>
  </itemizedlist>
 </sect1>
 <sect1 id="closing-exiting"><title>Closing Files and Exiting jEdit</title>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Close</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>W</keycap></keycombo>)
   closes the current buffer. If it has unsaved changes, jEdit
   will ask if they should be saved first.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Close All</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>E</keycap></keycombo>
   <keycombo><keycap>Control</keycap><keycap>W</keycap></keycombo>)
   closes all buffers. If any buffers have unsaved
   changes, they will be listed in a dialog box where they can be saved
   or discarded. In the dialog box, multiple buffers to operate on at
   once can be selected by clicking on them in the list while holding
   down <keycap>Control</keycap>.
  </para>
  <para>
   <guimenu>File</guimenu>&gt;<guimenuitem>Exit</guimenuitem>
   (shortcut: <keycombo><keycap>Control</keycap><keycap>Q</keycap></keycombo>)
   will completely exit jEdit.
  </para>
 </sect1>
</chapter>