Documentation overhaul.

7 files changed, 358 insertions, 0 deletions

diff --git a/doc/manual/1_Introduction.md b/doc/manual/1_Introduction.md
new file mode 100644
index 00000000..57a16cb0
--- /dev/null
+++ b/doc/manual/1_Introduction.md
@@ -0,0 +1,84 @@
+# Introduction
+
+## Purpose
+
+This manual is not intended to be completely comprehensive.
+
+## Textadept's Philosophy
+
+Textadept is a text editor for programmers.
+
+In a world where code bloat is commonplace and application speed is second to
+its number of features, Textadept breaks that trend, aiming to stay minimalist
+and fast, but at the same time being ridiculously extensible. At its core lies
+less than 2000 lines of C code, and that's how it always will be. While other
+editors rely on recordable macros to speed up workflow, shell scripts to quickly
+transform text, and static side panes to manage your documents, files, and more,
+Textadept takes it to the extreme: it gives you complete control over the entire
+application using the embedded [Lua][Lua] language. Lua is nearly as fast as C,
+and has a very small footprint. In fact, most of Textadept is written in Lua.
+Its incredibly fast startup time and operation attest to Lua's worthiness.
+
+Tired of all those features you never use in other editors? With Textadept you
+can disable or remove anything you dislike or do not need. Wish you had an
+additional feature? Chances are you can add it yourself.
+
+Annoyed of recording complicated macros in other editors, only to find yourself
+re-recording them over and over with little changes each time? You may be
+surprised to find you can write the same commands in Lua, from moving the caret
+to replacing text, performing searches, and much more!
+
+Worried that your existing shell scripts for transforming text in other editors
+will not be compatible with Lua or Textadept? No need to be. You can tell Lua to
+run them in your shell.
+
+Wish that you could add a feature to another editor's document/file browser/etc.
+side pane? Textadept allows you to create as many different kinds of browsers
+for heirarchical data as you want.
+
+These are just some of Textadept's strengths. Textadept is not about
+constraining the user to a certain set of features while allowing minimal
+custimization and/or extensibility. Textadept is about allowing that
+customization and extensibility from the get-go; the features come after that.
+
+[Lua]: http://lua.org
+
+## Help
+
+Textadept has a [mailing list][mailing_list] and a [wiki][wiki]. You can also
+join us on IRC via [freenode.net][freenode] in `#textadept`.
+
+[mailing_list]: http://groups.google.com/group/textadept
+[wiki]: http://caladbolg.net/textadeptwiki
+[freenode]: http://freenode.net
+
+## Screenshots
+
+<div style="float: left;">
+Main window.<br />
+<a href="http://caladbolg.net/images/textadept/window.png"><img src="http://caladbolg.net/images/textadept/window_t.png" alt="Main" /></a>
+</div>
+<div style="float: left; margin-left: 50px;">
+Open Buffers.<br />
+<a href="http://caladbolg.net/images/textadept/buffers.png"><img src="http://caladbolg.net/images/textadept/buffers_t.png" alt="Buffers" /></a>
+</div>
+<div style="margin-left: 400px;">
+Lua Commands.<br />
+<a href="http://caladbolg.net/images/textadept/command.png"><img src="http://caladbolg.net/images/textadept/command_t.png" alt="Command" /></a>
+</div>
+<div style="float: left;">
+Project Manager.<br />
+<a href="http://caladbolg.net/images/textadept/project.png"><img src="http://caladbolg.net/images/textadept/project_t.png" alt="PM" /></a>
+</div>
+<div style="margin-left: 200px;">
+Extras.<br />
+<a href="http://caladbolg.net/images/textadept/extra.png"><img src="http://caladbolg.net/images/textadept/extra_t.png" alt="Extras" /></a>
+</div>
+<div style="float: left;">
+Windows OS.<br />
+<a href="http://caladbolg.net/images/textadept/win32.png"><img src="http://caladbolg.net/images/textadept/win32_t.png" alt="Win32" /></a>
+</div>
+<div style="margin-left: 200px;">
+Linux OS.<br />
+<a href="http://caladbolg.net/images/textadept/linux.png"><img src="http://caladbolg.net/images/textadept/linux_t.png" alt="Linux" /></a>
+</div>
diff --git a/doc/manual/2_Installation.md b/doc/manual/2_Installation.md
new file mode 100644
index 00000000..e83805d8
--- /dev/null
+++ b/doc/manual/2_Installation.md
@@ -0,0 +1,49 @@
+# Installation

+

+## Requirements

+

+In its bid for minimalism, Textadept also needs very little to run. In fact, the

+only thing it needs is [GTK+ 2.0][GTK2]. It has it's own version of Lua compiled

+in.

+

+#### Linux

+

+Most Linux systems already have GTK+ installed. If not, it is probably available

+through your package manager. Otherwise, compile and install it from the

+[GTK+ website][GTK-Linux].

+

+#### Mac OSX

+

+There is a GTK+ [Mac OSX Framework][GTK-OSX] available in contrast to using GTK+

+from Fink or DarwinPorts/MacPorts in conjuction with X11. You will need to get

+the [latest TESTING framework][GTK-OSX-Latest] that supports versioning. Note

+that Textadept is designed for Intel Leopard Macs.

+

+#### Windows

+

+Windows systems need the [GTK+ 2.0 Runtime][GTK-Runtime] installed.

+

+[GTK2]: http://gtk.org

+[GTK-Linux]: http://www.gtk.org/download-linux.html

+[GTK-OSX]: http://gtk-osx.org

+[GTK-OSX-Latest]: http://people.imendio.com/richard/stuff/Gtk-Framework-2.14.3-2-test1.dmg

+[GTK-Runtime]: http://sourceforge.net/projects/gtk-win/

+

+## Download

+

+Textadept can be downloaded from the [project page][Download]. Select the

+appropriate package for your platform.

+

+[Download]: http://textadept.googlecode.com/

+

+## Installation

+

+#### Linux and Windows

+

+For Linux and Windows machines, simply unpack the archive anywhere and you are

+ready to go.

+

+#### Mac OSX

+

+For Mac OSX machines, unpack the archive and move `textadept.app` to your user

+or system `Applications` directory like any other application.

diff --git a/doc/manual/3_Compiling.md b/doc/manual/3_Compiling.md
new file mode 100644
index 00000000..acd874d3
--- /dev/null
+++ b/doc/manual/3_Compiling.md
@@ -0,0 +1,86 @@
+# Compiling
+
+## Requirements
+
+The requirements for building Textadept are not quite so minimal.
+
+#### Linux
+
+Linux systems will need the GTK+ development libraries. Your package manager
+should allow you to install them. For Debian-based distributions, the package is
+typically called `gtk2.0-dev`. Otherwise, compile and install it from the
+[GTK+ website][GTK-Linux]. Additionally you will need the [GNU C compiler][GCC]
+(`gcc`) and [GNU Make][Make] (`make`). Both should be available for your Linux
+distribution through its package manager.
+
+#### Mac OSX
+
+[XCode][XCode] is needed for Mac OSX as well as the
+[GTK-OSX Framework][GTK-OSX-Latest].
+
+#### Windows
+
+Compiling Textadept on Windows is no longer supported. If you wish to do so
+however, you will need a C compiler that supports the C99 standard (Microsoft's
+does not) and the [GTK+ for Windows bundle][GTK-Win32] and win_iconv libraries.
+
+The preferred way to compile for Windows is cross-compiling from Linux. To do
+so, in addition to the GTK+ development libraries mentioned above, you will need
+[MinGW][MinGW] with the Windows header files and the Windows [bundle][GTK-Win32]
+along with win_iconv. The former should be available from your package manager.
+The latter you will have to download manually.
+
+[GTK-Linux]: http://www.gtk.org/download-linux.html
+[GCC]: http://gcc.gnu.org
+[Make]: http://www.gnu.org/software/make/
+[XCode]: http://developer.apple.com/TOOLS/xcode/
+[GTK-OSX-Latest]: http://people.imendio.com/richard/stuff/Gtk-Framework-2.14.3-2-test1.dmg
+[GTK-Win32]: http://www.gtk.org/download-windows.html
+[MinGW]: http://mingw.org
+
+## Download
+
+Download the `textadept_x.x.src.zip`, regardless of what platform you are on.
+
+## Compiling
+
+#### Linux
+
+For Linux systems, simply run `make` in the `src/` directory. The `textadept`
+executable will be created in the root directory. You can make a symlink from
+it to `/usr/bin/` or elsewhere in your `PATH`.
+
+#### Mac OSX
+
+In Mac OSX, open `xcode/textadept.xcodeproj` in XCode, change the active build
+configuration combo box from `Debug` to `Release` (if necessary), click `Build`,
+and copy the resulting `xcode/build/Release/textadept.app` to your user or
+system `Applications` folder.
+
+
+#### Windows (Cross-Compiling from Linux)
+
+When cross-compiling from within Linux, first unzip the GTK+ for Windows bundle
+into a new `src/win32gtk` directory. Then rename all the
+`src/win32gtk/lib/*.dll.a` files to `src/win32/gtk/lib/*.a`, removing the `.dll`
+part of the filename. Finally, modify the `CC`, `CPP`, and `WINDRES` variables
+in the `WIN32` block of `src/Makefile` to match your MinGW installation and run
+`make WIN32=1` to build `../textadept.exe`.
+
+## Problems
+
+#### Mac OSX
+
+In Mac OSX, if the build fails because of a
+
+    `redefinition of 'struct Sci_TextRange'`
+
+error, you will need to open `src/scintilla-st/include/Scintilla.h` and comment
+out the following lines (put `//` at the start of the line):
+
+    #define CharacterRange Sci_CharacterRange
+    #define TextRange Sci_TextRange
+    #define TextToFind Sci_TextToFind
+
+`src/scintilla-st/src/LexLPeg.cxx` may need to have `TextRange tr` changed to
+`Sci_TextRange tr` as well.
diff --git a/doc/manual/4_UserInterface.md b/doc/manual/4_UserInterface.md
new file mode 100644
index 00000000..60ed9a18
--- /dev/null
+++ b/doc/manual/4_UserInterface.md
@@ -0,0 +1,38 @@
+# User Interface
+
+Textadept's user interface was designed to be simple. It consists of an optional
+menubar, left-hand side pane, editor view, and initially hidden dialogs for
+find/replace and command entry. Below are brief descriptions of these features.
+More in-depth discussion about each of them is provided later in the manual.
+
+## Menubar
+
+The completely customizable (and optional!) menubar typically provides access to
+all of Textadept's features.
+
+## Side Pane
+
+From the beginning, the side pane has been called the Project Manager, or PM.
+This is a deceptive name though, as it can hold any hierarchical, treeview-based
+data structure, not just a list of files in a project. By default, Textadept can
+show opened buffers, a filesystem, and a list of Lua modules. (These can be seen
+in `core/ext/pm/`.) If you choose, you can resize and/or hide the PM.
+
+## Editor View
+
+The editor view is where you will spend most of your time in Textadept. It
+supports unlimited split views and is completely controllable by Lua.
+
+## Find/Replace Dialog
+
+This compact dialog is a great way to slice and dice through your document or
+directory of files. You can even find and replace text using Lua patterns. It is
+available when you need it and quickly gets out of your way when you do not,
+minimizing distractions.
+
+## Command Entry
+
+The versitile command entry functions as both a place to execute Lua commands
+with the internal Lua state and find text incrementally. You can extend it to do
+even more if you would like. Like the find/replace dialog, the command entry
+pops in and out as you wish.
diff --git a/doc/manual/5_FolderStructure.md b/doc/manual/5_FolderStructure.md
new file mode 100644
index 00000000..7cb0f4b3
--- /dev/null
+++ b/doc/manual/5_FolderStructure.md
@@ -0,0 +1,41 @@
+# Folder Structure
+
+Because Textadept is mostly written in Lua, these Lua files have to be stored in
+an organized folder structure.
+
+## Core
+
+Textadept's core Lua modules are contained in `core/`. These are absolutely
+necessary in order for Textadept to run. They are responsible for Textadept's
+Lua to C interface, event structure, file input/output, and localization.
+
+## Core Extension
+
+Core extension Lua modules are in `core/ext/`. These are optional and not
+required, but are stored in `core/` because they could be considered "core
+functionality". They are responsible for PM functionality and features like
+find/replace and the handling of key commands, menus, and file types.
+
+## Lexers
+
+Lexer Lua modules are responsible for the syntax highlighting of source code.
+They are located in `lexers/`.
+
+## Modules
+
+Editor Lua modules are contained in `modules/`. These provide advanced text
+editing capabilities and can be available for all programming languages or
+targeted at specific ones.
+
+## Themes
+
+Built-in themes to customize the look and behavior of Textadept are located in
+`themes/`.
+
+## User
+
+User Lua modules are contained in a `.textadept` folder in your home directory.
+In Linux and Mac OSX, your home directory is the location specified by the
+`HOME` environment variable (typically `/home/username` and `/Users/username`
+respectively). In Windows, it is the `USERPROFILE` environment variable. This
+directory will be denoted as `~/.textadept` from now on in the manual.
diff --git a/doc/manual/6_Startup.md b/doc/manual/6_Startup.md
new file mode 100644
index 00000000..c9103782
--- /dev/null
+++ b/doc/manual/6_Startup.md
@@ -0,0 +1,33 @@
+# Startup Process
+
+Textadept starts up ridiculously fast. On most computers it starts up around as
+fast as you can blink.
+
+## Core (`core/init.lua`)
+
+The key to Textadept's lightning fast start time is that it loads only its core
+modules before showing the window.
+
+#### Themes
+
+Textadept loads its theme during the Core startup process. Each theme is its
+own folder with three files: `buffer.lua`, `lexer.lua`, and `view.lua`. The
+buffer theme sets default buffer properties like tabs and indentation. The view
+theme sets default view properties like caret color and current line background
+color. Lexer themes set the color and style definitions used by most lexers. By
+default the `'light'` theme is used. A `'scite'` theme is provided for users
+accustomed to SciTE.
+
+To use a different theme, create a `~/.textadept/theme` file containing the
+name of the built-in theme you would like. If you have a custom theme, use the
+path to its directory instead. Any errors are printed to standard out.
+
+## Post-Core (`init.lua`)
+
+After loading the core modules, Textadept begins loading additional modules.
+It first checks for a `~/.textadept/init.lua` user module. If the module is
+found, it is run and skips loading the default modules specified in `init.lua`.
+Otherwise a mixture of core extension and generic modules are loaded.
+
+After loading the additional modules, Textadept parses command line arguments,
+or if none are specified, reloads the last saved session.
diff --git a/doc/manual/7_LuaInterface.md b/doc/manual/7_LuaInterface.md
new file mode 100644
index 00000000..f1e343d9
--- /dev/null
+++ b/doc/manual/7_LuaInterface.md
@@ -0,0 +1,27 @@
+# Lua Interface
+
+After startup, Textadept relinquishes control to Lua. At this point, having a
+Manual is pointless since all of Textadept's functionality is dynamic from here
+on out. This is where the most important resource for help comes in: the
+[LuaDoc][LuaDoc]. It contains not only documentation for Textadept's Lua API,
+but documentation for all of its modules and features as well. It is more up to
+date than a manual like this could ever be.
+
+[LuaDoc]: ../index.html
+
+## Global Variables
+
+The following global variables not mentioned in the LuaDoc are available in
+Textadept's Lua state:
+
+* `arg`: Table containing the command line arguments passed to Textadept.
+* `_HOME`: Path to the directory containing Textadept.
+* `WIN32`: If Textadept is running on Windows, this flag is `true`.
+* `MAC`: If Textadept is running on Mac OSX, this flag is `true`.
+* `_CHARSET`: The character set encoding of the filesystem. This is used in
+  [File I/O][file_io].
+* `RESETTING`: If [`textadept.reset()`][textadept_reset] has been called, this
+  flag is `true` while the Lua state is being re-initialized.
+
+[file_io]: ../modules/textadept.io.html
+[textadept_reset]: ../modules/textadept.html#reset