Added filter-through module for shell commands.

3 files changed, 20 insertions, 2 deletions

diff --git a/doc/manual/10_Advanced.md b/doc/manual/10_Advanced.md
index 86387fca..3295110a 100644
--- a/doc/manual/10_Advanced.md
+++ b/doc/manual/10_Advanced.md
@@ -30,6 +30,23 @@ example of this is [incremental
 search](../modules/gui.find.html#find_incremental). See
 `modules/textadept/find.lua` for the implementation.
 
+## Shell Commands and Filtering Text
+
+Sometimes it is easier to use an existing shell command to manipulate text
+instead of using the command entry. An example would be sorting all text in a
+buffer (or a selection). You could do the following from the command entry:
+
+    ls={}; for l in buffer:get_text():gmatch('[^\n]+') do ls[#ls+1]=l end;
+    table.sort(ls); buffer:set_text(table.concat(ls, '\n'))
+
+A simpler way would be to press `Alt+R` (`Ctrl+Apple+R` on Mac OSX), enter the
+shell command `sort`, and hit `Enter`.
+
+For shell commands, if text is selected, all text on the lines containing the
+selection is used as the standard input (stdin) to the command. Otherwise the
+entire buffer is used. Either the selected text or buffer is replaced with the
+standard output (stdout) of the command.
+
 ## File Encoding
 
 Textadept represents all characters and strings internally as UTF-8. You will
diff --git a/doc/manual/14_Appendix.md b/doc/manual/14_Appendix.md
index 67a5feb7..ff9791cb 100644
--- a/doc/manual/14_Appendix.md
+++ b/doc/manual/14_Appendix.md
@@ -68,6 +68,7 @@
   <tr><td>F2</td><td>F2</td><td>Focus Lua command entry</td></tr>
   <tr><td>Ctrl+R</td><td>Ctrl+R</td><td>Run file</td></tr>
   <tr><td>Ctrl+Shift+R</td><td>Ctrl+Shift+R</td><td>Compile file</td></tr>
+  <tr><td>Alt+R</td><td>Ctrl+Alt+R</td><td>Filter through shell command</td></tr>
   <tr><td>Tab</td><td>Tab</td><td>Expand snippet or next placeholder or indent text</td></tr>
   <tr><td>Shift+Tab</td><td>Shift+Tab</td><td>Previous snippet placeholder or dedent text</td></tr>
   <tr><td>Ctrl+Alt+I</td><td>Ctrl+Apple+I</td><td>Cancel current snippet</td></tr>
diff --git a/doc/manual/1_Introduction.md b/doc/manual/1_Introduction.md
index 7affdd30..f3fb61f9 100644
--- a/doc/manual/1_Introduction.md
+++ b/doc/manual/1_Introduction.md
@@ -30,8 +30,8 @@ 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.
+will not be compatible with Lua or Textadept? No need to be. You can run those
+scripts from within the editor or Lua.
 
 These are just some of Textadept's strengths. Textadept is not about
 constraining the user to a certain set of features while allowing minimal