Minimum Profit README
=====================

 Minimum Profit - Programmer Text Editor
 Copyright (C) 1991-2005 Angel Ortega <angel@triptico.com>
 Home Page: http://www.triptico.com/software/mp.html
 Mailing List: mp-subscribe@lists.triptico.com

This software is GPL. NO WARRANTY. See file 'COPYING' for details.

Quick feature list
------------------

 - Multiple files can be edited at the same time and blocks copied
   and pasted among them.
 - Syntax highlighting for many popular languages / file formats: C, C++,
   Perl, Shell Scripts, Ruby, Php, SQL, Python, HTML...
 - Creative use of tags: tags created by the external utility _ctags_
   are used to move instantaneously to functions or variables inside
   your current source tree. Tags are visually highlighted (underlined),
   and symbol completion can be triggered to avoid typing your own function
   names over and over.
 - Intelligent help system: pressing F1 over any word of a text being edited
   triggers the underlying system help (calling _man_ when editing C or Shell
   files, _perldoc_ with Perl, _ri_ on Ruby, _winhelp_ on MS Windows...).
 - Understandable interface: drop-down menus, reasonable default key bindings.
 - Configurable keys, menus and colors.
 - Text templates can be easily defined / accessed.
 - Multiplatform: Console/curses, GTK+ (1.2 and 2.0), MS Windows.
 - Automatic indentation, word wrapping, internal _grep_, learning /
   repeating functions.
 - Search and replace using plain text or regular expressions (including
   a special function to replace text on all open files).
 - Small memory footprint.
 - Spellchecking support (via the ispell package).
 - Multilingual.
 - Password-protected, encrypted text files (using the ARCFOUR algorithm).
 - It helps you abandon vi, emacs and other six-legged freaks definitely.
 - Awesome easter egg.

Intro
-----

If you are reading this (you are), you probably know what a text editor
is and thus I won't explain what 'open file', 'search and replace',
'tab size' and things like those, means. Only the special or not-so-
intuitive features will be explained. In any other aspect, mp is just like
the text editor you were using until today, before you've found this unknown
jewel that will change your life.

Much of Minimum Profit's behaviour is changeable from a configuration file,
as key bindings, colors, the menu and other variables. Take a look at
mprc.sample for details. The configuration files for Unix systems are
/etc/mprc and $HOME/.mprc (see below to know how to set it in Win32).

Minimum Profit includes several interfaces:

 * curses: the good old text interface. You need any Unix (Linux, Solaris,
   IRIX, any BSD...) and the curses or ncurses library. It was also sucessfully
   compiled under BeOS (with a locally compiled ncurses) many years ago.
 * GTK: You need any X11 system with the GTK+ libraries installed. Support
   for GTK versions 1.2 and 2.0 is provided.
 * Win32: You need Microsoft Windows 95 or later and the lccwin32 compiler.

Compiling & Installing
----------------------

Under Unix flavours
~~~~~~~~~~~~~~~~~~~

To compile under any Unix flavour, just run

	 $ ./config.sh
	 $ make

The first step should automatically detect all usable interfaces and
additional libraries and leave a Makefile behind. Previous Minimum Profit
versions used to need GNU Make; this is no longer true. By running

	 $ ./config.sh --help

you can see a list of tweakable options. Also, a bunch of README.* files are
included with Minimum Profit's standard distribution with information
specific to many systems and cross-compilers. Notoriously, if you have
the mingw32 cross-compiler suite in your Unix system, you can build an
MS Windows binary pretty easily (README.mingw32).

To install just run (as root):

	 # make install

and it will be instaled in /usr/local/bin. You can select an alternate
installation directory in the configuration phase; for example, to install
it on /usr/bin, do

	$ ./config.sh --prefix=/usr/bin

Under MS Windows
~~~~~~~~~~~~~~~~

You'll need the lccwin32 compiler. To compile, just run the buildlcc.bat
batch file script.

Tags, functions and variables in your code
------------------------------------------

mp supports tags as in vi. This means that you can do

	 mp -t ShootPlasmaGun

and it will open the source code file that includes the definition of a
symbol (function or variable) called ShootPlasmaGun and that resides in the
current directory. As vi, mp uses the 'tags' file created by the program
'ctags'. There is an awesome version of this program, called
'Exuberant Ctags', that is able to recognize other languages that C, notably
Perl, Python and millions of other crap.

Note that mp just needs ctags for building the 'tags' file, not for using
it. This means that, though you don't have ctags in your win32 machine and
you cannot create the tags file, you can use one created in another
operating system.

Tags are searched as substrings; if more than one tag containing (in any
position) the string you pass is found, a list will be shown to allow you
to select the one you want. If you pass an empty string, all the tags in
the current directory will be shown, making mp look like a very sexy
code browser.

Symbol completion
~~~~~~~~~~~~~~~~~

Tags are also used for symbol completion. To use it, start typing a function
or variable name and hit Ctrl-S; if the partial name is unique, the complete
name will be immediately written. If more than one option is available, a
list will pop up to select the appropriate one.

Finding where a symbol is used (grep)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tags help to find where a function or variable is defined; mp's internal
grep function helps to find where a function or variable is used. Hit
Ctrl-N or select 'Search / Grep (find inside) files...' to do it.

Syntax highlighting
-------------------

Mp tries to detect the file type by looking inside its contents and,
if failed, by its extension. Run mp --help to see the complete list of
supported syntax highlight modes.

Inline help
-----------

If you press F1, mp takes the word below the cursor and, depending on the
type of the file you're editing, it tries to get help from the underlying
system. This is usually done by calling 'man', but also special cases are
tried as running 'perldoc' for Perl sources or 'ri' for Ruby ones.
If found, a new help page is opened in a new (read-only) window. You can
close it as a normal text or swap back to the original source. On Win32,
it's used differently: it spawns Winhelp.exe with the word as a parameter
to the .hlp file defined in the configuration variable win32_help_file.

Macro
-----

Macro (or learning) mode is activated when you hit F10 or Ctrl-F10 (you'll
notice that you are recording a macro by an 'R' letter in the status line).
Since then, any key you type will be recorded in an internal buffer. To stop
recording, just hit F10 again. To recall the recorded keys, go to wherever
you want, press F7 and they will be re-played from the current cursor position
(macros are silently limited to 1024 keystrokes). Any letter or cursor
movement key can be recorded.

Password-protecting files (encryption)
--------------------------------------

Minimum Profit includes support for password-protecting text files,
by using the ARCFOUR encryption algorithm. Just use the 'set-password'
editor command (or the 'Password protect...' option under the 'File'
default menu), enter a password twice and save the text file. Next time
the file is open, a password will be prompted to decrypt it.

The ARCFOUR algorithm is a symmetric key encrypt cipher that is fully
compatible with the RC4 encryption algorithm (a trademark of RSA Data
Security). To know more about it, see the next URL:

 http://en.wikipedia.org/wiki/RC4

The algorithm itself is believed to be rather secure, but no one has made any
cryptanalysis on this particular implementation, not even the less simple
tests. Don't keep any sensible information in these encrypted files. Always
keep another copy of your information elsewhere. Remember this software is
distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.

CAVEAT: There is a possible pitfall when using encrypted files; if you open
a file with the incorrect password, useless garbage will be open, as there
is no way of detecting incorrect passwords. But, if you later save the
garbage (probably accidentally), it will be re-encrypted with the (still
remembered) incorrect password, effectively destroying the original
information. Think of it as the same problem as opening a file, destroying
its content and then saving it.

Using mp with mutt
------------------

These are the options I use in my .muttrc:

	 set editor="mp --word-wrap 75 --col80 --mode mail"

This line forces mp execution with word wrapping on column 75 and
marking the 80th column for correct message formatting. The --mode mail
switch orders mp to bypass any syntax hilight detection and force it to treat
the file as a mail message, beautifying message headers and '>' quotes. Now
you can write / reply to all your spam in fancy colors.

Executing system commands
-------------------------

The 'System command...' menu option lets you run system commands. If you
run a program as is (for example, 'date'), mp just reads its standard
output and inserts it into cursor position. If you precede it by a |
(pipe) symbol (as in '|lpr') it runs the command sending the current file
being edited as the program's standard input. This is useful for printing
or sending a text by email. This doesn't work in win32.

Templates
---------

Aren't you fed up of filesystem travelling in search of a block of text
you usually insert into every file (like the license covering your
software)? I am. No more find && grep && cut && paste. Say no to it just now.

Mp templates are stored in $HOME/.mp_templates and have a name (a line of
text preceded by two % characters) and a body of text. When you hit
Ctrl-U, all template names you defined are showed on screen in a list for
you to just move over and push ENTER and by magical arts be inserted into
current opened file's cursor position. And for the sake of sloth, you can
edit the template file directly from the Edit menu.

Win32 version configuration
---------------------------

Several parameters could be set in the Win32 registry in previous versions
of Minimum Profit; now, there is only one value to register, as the other
ones can be defined in the configuration file: the HOME directory.
So, the only key is "HKEY_CURRENT_USER\Software\Minimum Profit\Home", and
is supposed to hold the drive:\path where the .mprc configuration file
can be found (so it can be shared between machines or even platforms).
All other run-time values can be configured there. The mp.reg file,
included in the source code or binary distribution package, can be used to
set this value.

Keys, functions and menus
-------------------------

Any editor function can be bound to any keystroke. To know the complete
list of keynames and funcnames, go to 'Options / Help on keys'. The whole
list of keystrokes and each associated funcname (if any) will be listed,
with a brief description of each one. After that, the funcnames not bound
to any keystroke follow. You can assign any function name to a keystroke
or to the menu via the configuration file (see mprc.sample). Also, you can
call an editor function from the 'Edit / Execute editor function' menu.

Search and replace in multiple files
------------------------------------

Anyone, in some occasion, has been in a need to search and replace a string
in a big set of text files. This operation, though relatively common, is
not satisfactory resolved by any known tool; one time more, Minimum Profit
comes to the rescue. Two specially crafted editor functions, called
replace-all (Replace in all) and sync (Save all modified texts), both accesible
from the menu, make this tedious operation as easy as a buch of keystrokes.

Mp_doccer does not live here anymore
------------------------------------

The mp_doccer C Source Documentation Generator tool is no longer distributed
with Minimum Profit. You can download it from its own page:

	http://www.triptico.com/software/mp_doccer.html

The easter egg
--------------

Finally, great programmer / puzzle solver extraordinaire Justin Bradford
found the easter egg that have been approx. 12 years uncovered inside
Minimum Profit's source code. All praise to him!

---
Angel Ortega http://www.triptico.com
