Browse files

Add Lua doc

  • Loading branch information...
1 parent a10eed2 commit 942235af8882b26919ab945570c59382c89de080 @nilnor nilnor committed Feb 11, 2012
Showing with 105 additions and 8 deletions.
  1. +6 −2 buffer_list.lua
  2. +36 −4 fs.lua
  3. +21 −0 hijack/init.lua
  4. +42 −2 init.lua
@@ -1,11 +1,15 @@
+The buffer list module provides a text based replacement for the standard
+TextAdept buffer list. Two differences compared to the stock one is the ability
+to close a buffer directly from the buffer list (bound to `Ctrl + d` by default),
+and the option of specifying the buffers to list via a provided function.
@author Nils Nordman <nino at>
@copyright 2011-2012
@license MIT (see LICENSE)
@module _M.textile.buffer_list
local tui_list = require 'textui.list'
-local keys = keys
local L = _L
local M = {}
@@ -71,7 +75,7 @@ end
--- Shows a list of the specified buffers, or _G.BUFFERS it not specified.
-- @param buffers Either nil, in which case all buffers within _G.BUFFERS
--- are displayed, or a function returning a table of buffers.
+-- are displayed, or a function returning a table of buffers to display.
buffer_source = buffers or function() return _BUFFERS end
@@ -1,9 +1,41 @@
textile.fs provides a text based file browser for TextAdept.
-It features conventional directory browsing, as well as snapopen functionality,
-and allows you to quickly get to the files you want by offering advanced
-narrow to search functionality.
+It features traditional directory browsing, snapopen functionality, completely
+keyboard driven interaction, and provides powerful narrow to search functionality.
+Some tips on using the file browser
+*Switching between traditional browsing and snapopen*
+As said above the file browser allows both traditional browsing as well as
+snapopen functionality. But it also allows you to seamlessly switch between
+the two modes (by default, `Ctrl + s` is assigned for this).
+*Quickly moving up one directory level*
+In traditional browsing mode, you can always select `..` to move up one directory
+level. But a quicker way of doing the same is to press `<backspace>` when you
+have an empty search. This also works when in snapopen mode.
+*Opening a sub directory in snapopen mode*
+In contrast with TextAdept snapopen, you will in snapopen mode also see sub
+directories in the listing. This is by design - you can select a sub directory
+to snapopen that directory.
+*Changing the styles used for different file types*
+If you don't like the default styles (colors, etc.) used by the file browser,
+you can easily change these by customizing any of the `style_<foo>` entries using
+the TextUI style module. As an example, to make directory entries underlined
+you would do something like the following:
+ = { underline = true }
+Please see the documentation for the TextUI style module for instructions on how
+to define styles.
@author Nils Nordman <nino at>
@copyright 2011-2012
@@ -411,7 +443,7 @@ The main differences are:
- `rel_path`: The path of the file relative to the currently displayed directory.
-@param directory The directory to open, in UTF-8 encoding
+@param directory The directory to open, in UTF-8 encoding.
@param filter The filter to apply. The format and semantics are the same as for
@param exclude_FILTER Same as for TextAdept: unless if not true then
@@ -1,3 +1,24 @@
+The hijack module provides the easiest, and most invasive, way of getting
+Textile functionality for TextAdept. It's a one-stop setup in the way that you
+don't really have to configure anything else to use Textile's functionality -
+the hijack module inserts Textile functionality anywhere it can and will
+automatically integrate with your existing key bindings as well as with the menu.
+How to use
+After installing the textile module (as well as it's dependency, the TextUI
+module) into your .textadept/modules directory, simple add the following to
+your .textadept/init.lua file:
+ require 'textile.hijack'
+@author Nils Nordman <nino at>
+@copyright 2012
+@license MIT (see LICENSE)
+@module _M.textile.hijack
_M.textile = require 'textile'
local fl = require 'textile.hijack.filteredlist'
@@ -1,5 +1,45 @@
-The Textile module offers a set of text based interfaces for TextAdept.
+The Textile module offers a set of text based replacement interfaces for
+It currently contains the following modules:
+- @{_M.textile.fs}. Contains text based interfaces for file io operations, i.e.
+open file, save file as well as snapopen functionality.
+- @{_M.textile.buffer_list}. A text based buffer list replacement, which in
+addition to being text based also offers an easy way to close buffers directly
+from the list.
+- @{_M.textile.hijack}. Hijacks TextAdept, replacing as much functionality as it
+can with text based counterparts. In addition to injecting the above modules in
+the menu and key bindings, it also replaces the traditional filtered list with
+a TextUI list for a number of operations.
+How to use it
+Textile depends on the TextUI module, and thus you need to install that along
+with the Textile module itself. Download and install both modules in your
+`.textadept/modules/' directory.
+Having installed it, there are two ways you can use Textile.
+1) Cherrypick the functionality you want from the different modules by assigning
+key bindings to the desired functions. As an example, if you would like to use
+the text based file browser and normally opens files using `Ctrl + o`, then the
+following code in your `init.lua` would do the trick:
+ _M.textile = require 'textile'
+ = _M.textile.fs.open_file
+2) If you can't get enough of text based interfaces and the joy they provide,
+then the @{_M.textile.hijack} module is for you. Simple place this in your
+ require 'textile.hijack'
+As the name suggest, Textile has now hijacked your environment. All your regular
+key bindings, as well as the menu etc. should now use Textile where applicable.
@author Nils Nordman <nino at>
@copyright 2011-2012

0 comments on commit 942235a

Please sign in to comment.