\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename moe.info
@settitle GNU Moe
@finalout
@c %**end of header

@set UPDATED 10 July 2009
@set VERSION 1.2

@dircategory Editors
@direntry
* Moe: (moe).                   A powerful and user-friendly text editor
@end direntry


@titlepage
@title GNU Moe
@subtitle A powerful and user-friendly text editor
@subtitle for Moe version @value{VERSION}, @value{UPDATED}
@author by Antonio Diaz Diaz

@page
@vskip 0pt plus 1filll
@end titlepage

@contents

@node Top
@top

This manual is for GNU Moe (version @value{VERSION}, @value{UPDATED}).

@menu
* Introduction::	Purpose and features of GNU Moe
* Basic concepts::	Buffers, buffer handles, files, windows, etc
* Invoking Moe::	Command line interface
* The moerc file::	The Moe configuration file
* The status line::	Filename, position, etc
* Keyboard commands::	Description of Moe's editing capabilities
* Other features::	Emergency save, binary files, etc
* Problems::		Reporting bugs
* Concept Index::	Index of concepts
@end menu

@sp 1
Copyright @copyright{} 2005, 2006, 2007, 2008, 2009 Antonio Diaz Diaz.

This manual is free documentation: you have unlimited permission
to copy, distribute and modify it.


@node Introduction
@chapter Introduction
@cindex introduction

GNU Moe is a powerful, 8-bit clean, text editor for ISO-8859 and ASCII
character encodings. It has a modeless, user-friendly interface, online
help, multiple windows, unlimited undo/redo capability, unlimited line
length, global search/replace (on all buffers at once), block
operations, automatic indentation, word wrapping, filename completion,
directory browser, duplicate removal from prompt histories, delimiter
matching, etc.

To have Moe used as your default editor you need to set the environment
variables @samp{EDITOR=moe} and/or @samp{VISUAL=moe} in your shell
initialization file ($HOME/.profile if you are using bash).


@node Basic concepts
@chapter Basic concepts
@cindex basic concepts

@table @asis
@item Buffer
The buffer is the basic editing unit; one buffer corresponds to one text
being edited. You can have several buffers, but at any time you are
editing only one, the `current buffer', though several buffers (or
several parts of the same buffer) can be visible when you are using
multiple windows.

@item Buffer handle
The buffer handle is the data structure underlying a (possibly hidden)
window. It contains the window and cursor positions in the buffer. There
is no limit on the number of buffer handles that can refer to the same
buffer.

@item Current line
The line with the cursor.

@item File
Files are named units of text which are stored by the operating system
for you to retrieve later by name. To keep any text permanently you must
put it in a file.

When Moe loads a file, it creates a buffer, copies the contents of the
file into the buffer, and then displays the buffer for you to edit. If
you alter the text, you can save the new text in the file. This makes
the changes permanent by copying the altered buffer contents back into
the file. Until you save, the changes exist only inside Moe, and the
loaded file remains unaltered.

To create a file, just load the file as if it already existed. This
creates an empty buffer in which you can insert the text you want to put
in the file. The file is actually created when you save this buffer.

@item Window
Moe divides the screen into one or more windows, each of which can
display the contents of one buffer. The only limit to the number of
windows is screen size.

@end table


@node Invoking Moe
@chapter Invoking Moe
@cindex invoking Moe
@cindex options
@cindex usage
@cindex version

The format for running Moe is:

@example
moe [@var{global-options}] [ [+@var{line}] @var{filename} [@var{file-options}] ]...
@end example

Where @samp{global-options} are a mix of editor options and default
file-options. Use @samp{-} as a filename to read from standard input.
Note that the short option names use the same letters that the options
menu inside Moe. Most long option names have a negative form
@samp{--backup --no-backup}. Each filename may be preceded by
+@var{line} to start the cursor at the beginning of the specified line.

Moe supports the following editor options:

@table @code
@item --help
@itemx -h
Print an informative help message describing the options and exit.

@item --version
@itemx -V
Print the version number of Moe on the standard output and exit.

@item --auto-unmark
@itemx -u
Turn off highlighting after block copy or move.

@item --backup
@itemx -b
Create backup files (default).

@item --exit-ask
@itemx -e
Ask always for confirmation when closing or saving-and-closing a buffer.

@item --ignore-case
@itemx -i
Search in Moe is case sensitive by default. With this option you can
make it case insensitive by default.

@item --indent-step=@var{n}
@itemx -n @var{n}
Number of spaces to add or remove when indenting or unindenting a block.

@item --keep-lines=@var{n}
@itemx -k @var{n}
Number of lines to keep for PgUp/PgDn. -1 means half window.

@item --max-windows=@var{n}
@itemx -m @var{n}
Maximum number of windows to show at once on the screen. 0 means as many
as they fit.

@item --orphan
@itemx -1
Put extra files in orphaned buffers instead of in new windows.

@item --rectangle
@itemx -x
Turn on rectangular block mode. Provide basic rectangular block
operations, like copy or move. This mode won't work properly if there
are tabs in or at the left of the block.

@item --search-wrap
@itemx -s
Search wraps. If end of buffer is reached and no match is found, continue
the search from the beginning of the buffer.

@item --smart-home
@itemx -H
Normally, when you press the home key, the cursor moves to the beginning
of the line, and if you press it again, it remains there. With this
option, if the cursor is at the beginning of the line and you press
home, the cursor moves to the first non-blank character.

@sp 1
Moe also supports the following file options:

@item --auto-indent
@itemx -a
When auto indent is enabled and you press enter, or the text wraps at
the end of a line, the cursor moves under the first non-blank character
of the previous line instead of at the beginning of the line.

@item --lmargin=@var{col}
@itemx -l @var{col}
Set left margin to col. The first column is column 1.

@item --rmargin=@var{col}
@itemx -r @var{col}
Set right margin to col.

@item --read-only
@itemx -o
Make the buffer read only.

@item --overwrite
@itemx -O
Disable insert mode. Typed characters replace existing ones except at
end of line.

@item --word-wrap
@itemx -w
Automatically passes the current word to the next line when you type
past the right margin.

@end table


@node The moerc file
@chapter The moerc file
@cindex the moerc file

@file{moerc} is the runtime configuration file for Moe. In it you may
define default editor options, default file options and filename
dependent default file options. The @file{moerc} file is optional, so
that you can run Moe from the source directory without installing it.

The command line options override those specified in the @file{moerc}
file. The file options specified on the command line override those
specified in the filename dependent options section of the @file{moerc}
file.

You may copy the system @file{moerc} file @file{$@{sysconfdir@}/moerc}
to @file{$HOME/.moerc} and customize these options as you like. The file
syntax is fairly obvious and there are further instructions in it.


@node The status line
@chapter The status line
@cindex the status line

The status line is a line displayed in inverse video at the top of each
window, and contains the following information:

@itemize @bullet
@item
The keyboard status. Shows the already typed part of a multy-key
command.
@item
The status characters. @samp{I} for insert mode, @samp{O} for overwrite
mode, @samp{W} for word wrap, @samp{A} for auto indent, @samp{R} for
read-only, and @samp{X} for rectangular block mode.
@item
The name of the file being edited, or @samp{(Unnamed)} if the buffer has
not yet been named. If the buffer has been modified since it was last
saved or opened, an asterisk @samp{*} will be displayed before the name
and @samp{(Modified)} will be displayed after the name.
@item
The cursor position in the buffer (Line Column).
@item
The clock (with blinking dots).
@item
The help key (or the code of the character under the cursor).
@end itemize


@node Keyboard commands
@chapter Keyboard commands
@cindex keyboard commands

Moe tries to rationalize the keyboard commands. The @key{Alt} key is
used for harmless commands like cursor movements and scrolling. The
@key{Control} key is used for more "dangerous" commands like copying
text blocks, deleting lines, or exiting. The @key{Tab} key is used for
filename completion and also shows/hides the directory browser when Moe
asks for a filename to save or load. In any case, the unlimited
undo/redo capability of Moe makes very difficult to accidentally cause
an irreparable damage to your files.

Moe uses the function keys, so that the most frequent commands can be
issued with only one finger. The function key @key{F1} shows the online
help, and @key{F10} allows you to change the options. Believe it or not,
this paragraph and some experience with text editors is all you need to
use Moe just as well as an expert. Forget about @samp{learning curves};
there is nothing to learn.

The @key{Control} key is displayed in the online help as @samp{^}, while
the @key{Alt} key is displayed as @samp{^[}. In this manual
@kbd{Control-a} will be written as @kbd{C-a} and @kbd{Alt-a} as
@kbd{A-a}.

Some environments "swallow" the @key{Alt} key so that it never reaches
the application. If this happens, press the @key{Esc} key, then release
it and press the desired key.

@menu
* Function keys::	The most important functions are here
* Moving around::	Moving the cursor to the desired place
* Inserting text::	Inserting text by simply typing it
* Search::		Finding or replacing occurrences of a string
* Regexps::		Syntax of regular expressions
* Block commands::	Delimiting and operating on a region of text
* Exiting::		Terminating your editing session
* Other commands::	Commands for some special functions
@end menu


@node Function keys
@section Function keys
@cindex function keys

@table @kbd
@item @key{F1}
@itemx C-h
Show the online help. Press @key{Page_up} to see the previous help
screen or @key{Page_down} to see the next help screen. Press @key{F1}
or @kbd{C-h} again to return to the editor.

@item @key{F2}
Save the current buffer to a file, automatically creating any missing
parent directories. It will ask you to confirm the filename. You may
save the buffer with a different name, in which case the modified status
of the buffer being edited does not change. Moe makes a backup for a
file only the first time the file is saved from one buffer.

@item @key{F3}
Load (read) a file in a new buffer. Pressing @key{Tab} shows the
contents of the current directory, or completes the name if there is
only one possible name to show. If the filename starts with @file{~/},
the @file{~} will be expanded to specify your home directory (tilde
expansion).

@item @key{F4}
Toggle between showing only the current window or showing as many
windows as the screen can contain.

@item @key{F5}
Select the previous window.

@item @key{F6}
Select the next window.

@item @key{F7}
Undo the last change made to the current buffer. You may keep undoing
changes until there are no more changes to undo. The buffer will be then
exactly as when it was loaded.

@item @key{F8}
Redo the last change undone on the current buffer. The undo history is
linear. That is, if you undo some changes and then make another change,
this last change replaces the changes undone, so you can't redo them.

@item @key{F9}
Copy the selected block at the cursor position. This is a convenient
alias for the command @kbd{C-k c}.

@item @key{F10}
Show the options menu. This menu allows you to change some editor-wide
and current-buffer options, like auto indent, margins, word wrap, ask
before exit, etc.

@item @key{F11}
Show the buffers menu, a list of all the buffers being edited. This menu
allows you to select a buffer and make it the current buffer. Some
buffers may appear more that once in the list if they have more than one
buffer handle. The buffer names of modified buffers will be preceded by
an asterisk @samp{*}.

@item @key{F12}
Select the last buffer handle where you pressed @key{F12} and make its
buffer the current buffer. This allows you to switch between two
buffers, or between two places of the same buffer, by repeatedly
pressing @key{F12}.

@end table


@node Moving around
@section Moving around
@cindex moving around

The simplest way to move the cursor to the place where you want to edit
is with the arrow keys. Moe also provides commands to move to certain
points in the buffer.

@table @kbd
@item A-u
Move cursor to the beginning of the buffer.

@item A-v
Move cursor to the end of the buffer.

@item A-l
Prompt for a line number, and then move cursor to that line. Line 1 is
the first line.

@item A-c
Prompt for a column number, and then move cursor to that column.
Column 1 is the first column.

@item A-b
Move cursor to the begin of the selected block, if begin of block has
been set and is in the current buffer.

@item A-k
Move cursor to the end of the selected block, if end of block has been
set and is in the current buffer.

@item A-f
Move cursor to the matching @samp{(}, @samp{[}, @samp{@{}, @samp{<},
@samp{)}, @samp{]}, @samp{@}}, @samp{>}, @samp{"}, @samp{'}, @samp{/*}
or @samp{*/}. Default movement is forward for undirected delimiters. If
the cursor is not on a valid delimiter, Moe tries to guess what delimiter
to match.

@item A-g
Like @kbd{A-f}, but default movement is backward for undirected delimiters.

@item A-d
Center cursor. Scroll window so that the line with the cursor is
vertically centred.

@item A-w
Scroll window backward (scroll up) leaving @samp{keep-lines} of context,
or half screen if @samp{keep-lines} is -1.

@item A-z
Scroll window forward (scroll down) leaving @samp{keep-lines} of
context, or half screen if @samp{keep-lines} is -1.

@item A-a
Scroll window left 8 columns.

@item A-s
Scroll window right 8 columns.

@item C-k 0..9
(@kbd{Control-k} followed by a digit from 0 to 9).
Set one of the 10 user bookmarks at the cursor position.

@item A-0..9
(Keep the @key{Alt} key pressed while typing a digit from 0 to 9).
Move the cursor to one of the 10 user bookmarks.

@end table


@node Inserting text
@section Inserting text
@cindex inserting text

To insert printing characters into the text you are editing, just type
them. This inserts the characters you type into the buffer at the cursor.

The @key{Backspace} key deletes the character preceding the cursor,
while the @key{Delete} key deletes the character at cursor. You can
delete a whole line with the @kbd{C-y} command.

The @key{Return} key inserts a newline character in the buffer. If the
cursor is in the middle of a line, @key{Return} splits the line.

Moe can split lines automatically when you type past the right margin
if you turn on word wrap in the options menu (@pxref{Function keys}), or
from the command line when invoking Moe.

If you prefer to have text characters replace (overwrite) existing ones
rather than being inserted among them, you can activate overwrite mode
pressing the @key{Insert} key. Pressing again the @key{Insert} key
activates the normal insert mode.

To insert a control or special character in the buffer, use the command
@kbd{C-p}. It will prompt for a character code in a number of formats
and insert it at the cursor.


@node Search
@section Searching and replacing text
@cindex search

@noindent
The @kbd{C-f} command enters search mode. It will prompt for the text to
be searched for (the search string). The @key{F9} key will copy the
selected block in the string being entered. @key{F9} may be also used
when entering the replacement text.

@noindent
The @kbd{C-g} command repeats the previous search or replace.

@noindent
The @kbd{C-w} command searchs for the word at the cursor.

After entering the text to be searched, Moe will prompt for search
options. You may just hit @key{Return} to search forward with default
options or type one or more of the following options:

@table @kbd
@item i
Ignore the case of the text being searched.

@item n
Do not ignore the case of the text being searched. Use it when default
is set to ignore case.

@item r
Replace text. It will prompt for replacement text.

@item b
Search backward instead of forward.

@item g
Search globally. Extends the search to all the files being edited.

@item k
Block search. Restricts the search to the selected block.

@end table

@sp 1
If you chose @samp{r} (replace) among the options above, every time the
search string is found, you will be prompted whether to replace it with
the replacement text. The possible answers are: @kbd{y} (yes) to replace
and continue searching, @kbd{n} (no) to not replace this text, but
continue searching, or @kbd{r} (rest) to replace all the remaining
occurrences of the search string without asking for confirmation.


@node Regexps
@section Syntax of regular expressions
@cindex regular expressions

Regular expressions have a syntax in which a few characters are special
constructs and the rest are "ordinary". An ordinary character is a
simple regular expression which matches that same character and nothing
else. In Moe's regular expressions, all characters are ordinary
characters except @samp{\}, which is used to indicate a special
character or construct. Here is a list of those special constructs, also
known as "special search sequences".

@table @kbd
@item \\
Matches a single @samp{\}. See online help for more special characters.

@item \?
Matches any single character. For example, @samp{a\?b} will match an
@samp{a} followed by any character and then a @samp{b}.

@item \*
Matches zero or more characters. For example, @samp{a\*b} will match an
@samp{a} followed by any number of characters and then a @samp{b}.

@item \c
This works like @samp{\*}, but matches a C/C++ balanced expression. For
example, @samp{\<for\>\s(\c)} will match any @samp{for} loop, even if it
includes nested parentheses.

@item \+
Matches zero or more instances of the character inmediately following
the @samp{+}. For example, @samp{\+b} will match any number of @samp{b}s
(including no @samp{b}s). @samp{\+} may precede @samp{\[..]}, @samp{\w}
or @samp{\W}, matching any number of characters from those in set
(including the empty string). @samp{\+} may precede itself any number of
times, matching N-1 or more instances of the character inmediately
following the last @samp{+}. For example, @samp{\+\+\+b} will match two
or more @samp{b}s.

@item \[..]
Character set. This matches any single character between the brackets.
Ranges of characters may be specified by writing the starting and ending
characters with a @samp{-} between them. Thus, @samp{\[A-Z]} matches any
ASCII uppercase letter. @samp{-} may be specified by placing it first or
last. @samp{]} may be specified by placing it first. If the first
character after the left bracket is @samp{^} indicates a "complemented
set", which matches any character except the ones between the brackets.

@item \s
Matches zero or more whitespace characters. For example, @samp{a\sb}
will match an @samp{a} followed by any number of whitespace characters
(or none) and then a @samp{b}.

@item \S
Matches the longest possible non-empty sequence of whitespace
characters. For example, @samp{a\Sb} will match an @samp{a} followed by
any positive number of whitespace characters and then a @samp{b}.

@item \w
Matches any word-constituent character (letters, digits and the
underscore) of the ISO-8859-15 or ISO-8859-1 character encodings. Other
ISO-8859 encodings are not supported by this command.

@item \W
Matches any character that is not a word-constituent.

@item \^
@itemx \$
These match the beginning and end of a line. For example, @samp{\^foo\$}
matches @samp{foo} on a line by itself.

@item \<
@itemx \>
These match the beginning and end of a word. For example,
@samp{\<foo\*\>} will match any whole word beginning with @samp{foo}.

@end table

@sp 1
And here are the special replace sequences.

@table @kbd
@item \&
This is replaced with the text which matched the search string. For
example, @samp{(\&)} will place parentheses around the matched text.

@item \l
This is replaced with the text which matched the search string converted
to lowercase. For example, @samp{(\l)} will convert to lowercase the
matched text and place parentheses around it.

@item \u
Same as @kbd{\l}, but converts the matched text to uppercase.

@item \0 - \9
(Backslash followed by a digit from 0 to 9). These are replaced with the
text which matched the Nth special search sequence, except beginning/end
of line/word, in the search string.

@end table


@node Block commands
@section Block commands
@cindex block commands

Moe allows you to mark a region of text, the block, and then perform
some operations like deleting the block, moving it to another place (in
the same or another buffer), changing its encoding, etc. There can be
only one block at any given time. If you begin marking a block, any
existing block will be unmarked.

Here is a list of the block operations:

@table @kbd
@item C-@key{Space}
Mark the beginning of block, or the end of block if the beginning is
already marked. If pressed in an existing block, unmarks it.

@item C-k b
Mark the beginning of block.

@item C-k k
Mark the end of block.

@item C-k c
Copy the block at the cursor. The text inside the original block remains
unchanged.

@item C-k m
Move the block at the cursor. The text inside the original block is
deleted.

@item C-k y
Delete the text in the block.

@item C-k r
Read a block of text from a file and insert it at the cursor. This
operation ignores rectangular block mode.

@item C-k w
Write the block to a file. The text inside the original block remains
unchanged.

@item C-k i
Indent block. Add spaces at the beginning of every line in the block.

@item C-k u
Unindent block. Remove spaces from the beginning of every line in the block.

@item C-o 1
Encode Base64. Replace text in the block with its Base64-encoded
equivalent data.

@item C-o 2
Decode Base64. Replace Base64-encoded data in the block with its
corresponding plain text.

@item C-o 3
Encode Rot-13. Replace text in the block with its corresponding
Rot-13-encoded text.

@item C-o 4
Encode Rot-47. Replace text in the block with its corresponding
Rot-47-encoded text.

@item C-o 6
Decode Quoted-Printable. Replace Quoted-Printable-encoded text in the
block with its corresponding plain text.

@item C-o 8
Decode UTF-8. Replace UTF-8-encoded text in the block with its
corresponding ISO-8859-15 or ISO-8859-1 plain text. Other ISO-8859
encodings are not supported by this command.

@item C-o d
Remove all duplicate lines in the block leaving the first of each set.

@item C-o e
Remove all duplicate lines in the block leaving the last of each set.

@item C-o l
Convert all the letters in the block to lowercase.

@item C-o u
Convert all the letters in the block to uppercase.

@end table


@node Exiting
@section Terminating your editing session
@cindex exiting

@table @kbd
@item C-c
Close the current window without saving any changes. If the current
window is the only one for its buffer, and the buffer being edited has
been modified, or @samp{exit-ask} is enabled (@pxref{Invoking Moe}), it
will ask you before closing the window.

@item C-x
Save the buffer being edited (if it has been modified), and then close
the current window. If the current window is the only one for its
buffer, and @samp{exit-ask} is enabled (@pxref{Invoking Moe}), it will
ask you before saving the buffer or closing the window.

@item C-q x
Save and exit. Save all the modified buffers, and then exit completely.
It will always ask you before saving or closing anything.

@item C-q c
Exit completely without saving. It will always ask you before closing
anything.

@end table


@node Other commands
@section Commands for some special functions
@cindex other commands

@table @kbd
@item C-b
Reformat paragraph. Break it up into lines that fit between the margins.

@item C-h
Show the online help. @xref{Function keys}.

@item C-p
Insert a control or special character in the buffer.

@item C-y
Delete the current line.

@item C-o c
Centre the current line between the margins.

@item C-o n
Change the name of the current buffer preserving undo history, user
bookmarks, etc.

@item C-o r
Redraw the screen.

@item C-o s
Split the current window into two. The resulting windows share the same
buffer. To undo the split just close one of the two windows with @kbd{C-c}.

@item C-q @key{F2}
Save to files all the named buffers that have been modified. A named
buffer is one with an associated filename. This function is very useful
if you do a global replace on many buffers at once and want to save all
the modified buffers without pressing @key{F2} a lot of times.

@item C-q u
Update copyright notices in all files. For this to work, the copyright
notice format should be @w{@samp{Copyright <optional_text>
<list_of_years> Copyright_holder_name}}

@item C-s c
(Show character code). Show the code of the character at the cursor on
the status line. Repeat the command to revert to normal.

@item C-s g
(Show global status). Show the number of modified, unnamed and total
buffers being edited. Really it shows the number of buffer handles, so
the numbers may be greater than expected.

@item C-s i
(Show character info). Show the line, column, position in buffer and
code of the character at the cursor.

@item C-s v
Show Moe's version.

@end table


@node Other features
@chapter Other features
@cindex emergency save
@cindex binary files
@cindex DOS files

@table @asis
@item Emergency save
When Moe is interrupted by an abnormal event (a SIGTERM signal for
example), it will try to save all modified buffers in a file named
DEADMOE in the current directory.

@item Binary files
As Moe is 8-bit clean, it is able to edit binary files, though in a very
inconvenient way. If the file does not have any newline character, all
of it will be loaded as a single line. Use this "feature" in emergency
cases only.

@item DOS files
If Moe detects at load time that all the lines of a file are terminated
by a CR/LF pair, assumes it is a DOS file and removes all the CRs. The
CRs are restored later when saving the buffer to a file. If some, but
not all, of the lines are CR/LF terminated, no action is taken and CRs
are shown as control characters on the screen.

@end table


@node Problems
@chapter Reporting Bugs
@cindex bugs
@cindex getting help

There are probably bugs in Moe. There are certainly errors and omissions
in this manual. If you report them, they will get fixed. If you don't,
no one will ever know about them and they will remain unfixed for all
eternity, if not longer.

If you find a bug in Moe, please send electronic mail to
@email{bug-moe@@gnu.org}. Include the version number, which you can
find by running @w{@code{moe --version}}.


@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye
