rrthomas
diff --git a/‎Cookbook.md‎
Lines changed: 1 addition & 1 deletion b/‎Cookbook.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎Filtering.md‎
Lines changed: 1 addition & 0 deletions b/‎Filtering.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎README.md‎
Lines changed: 6 additions & 10 deletions b/‎README.md‎
Lines changed: 6 additions & 10 deletions
diff --git a/‎README.nancy.md‎
Lines changed: 20 additions & 20 deletions b/‎README.nancy.md‎
Lines changed: 20 additions & 20 deletions
@@ -35,7 +35,7 @@ The basic page template looks something like this:
 <!DOCTYPE html>
 <html>
   <head>
-    <link rel="stylesheet" type="text/css" href="$paste{path-to-root.in.sh,$path}/style.css">
+    <link rel="stylesheet" type="text/css" href="$paste(path-to-root.in.sh,$path)/style.css">
     <title>$include{title.in.txt}</title>
   </head>
   <body>
 
@@ -0,0 +1 @@
+Change the syntax of `$include` to: `$include(command,arg,...){file}` (and similar for `$paste`). The semantics are that `file` is found and expanded, then the result is fed to `command arg...`'s stdin. If you omit the `{file}`, then you are just running a command and expanding/pasting its output.
@@ -110,25 +110,21 @@ a file.
 
 Nancy expands a template file as follows:
 
-1. Scan the file for commands. Expand any arguments to the command, run
-   each command, and replace the command by the result.
-2. Output the result.
+1. Scan the text for commands. Expand any arguments to the command, run each
+   command, and replace the command by the result, eliding any final
+   newline. (This elision may look tricky, but it almost always does what
+   you want, and makes `$include` behave better in various contexts.)
+2. Output the resultant text.
 
 A command takes the form `$COMMAND` or `$COMMAND{ARGUMENT, ...}`.
 
-Nancy treats its input as 8-bit ASCII, but command names and other
-punctuation only use the 7-bit subset. This means that any text encoding
-that is a superset of 7-bit ASCII can be used, such as UTF-8.
-
 ### Built-in commands
 
 Nancy recognises these commands:
 
 * *`$include{FILE}`* Look up the given source file in the input tree (see
   below); read its contents, then expand them (that is, execute any commands
-  it contains) and return the result, eliding any final newline. (This
-  elision may look tricky, but it almost always does what you want, and
-  makes $include behave better in various contexts.)
+  it contains) and return the result.
 * *`$paste{FILE}`* Like `$include`, but does not expand its result before
   returning it.
 * *`$path`* Expands to the file currently being expanded, relative to the
 
@@ -2,7 +2,7 @@
 
 ![logo](logo/nancy-small.png) _logo by Silvia Polverini_
 
-$paste{/bin/sh,-c,PYTHONPATH=. python -m nancy --version | tail +2 | head -2 | sed -e 's/$/  /'}
+$paste(/bin/sh,-c,PYTHONPATH=. python -m nancy --version | tail +2 | head -2 | sed -e 's/$/  /')
 
 Nancy is a simple templating system that copies a file or directory, filling
 in templates as it goes. It has just one non-trivial construct:
@@ -35,7 +35,7 @@ $ pip install nancy
 ## Invocation
 
 ```
-$paste{/bin/sh,-c,PYTHONPATH=. python -m nancy --help | sed -e 's/usage: nancy/nancy/'}
+$paste(/bin/sh,-c,PYTHONPATH=. python -m nancy --help | sed -e 's/usage: nancy/nancy/')
 ```
 
 ## Operation <a name="operation"></a>
@@ -99,7 +99,11 @@ Nancy expands a template file as follows:
    each command, and replace the command by the result.
 2. Output the result.
 
-A command takes the form `\$COMMAND` or `\$COMMAND{ARGUMENT, ...}`.
+A command is written as its name prefixed with a dollar sign: `\$COMMAND`.
+Some commands take an argument, given in braces: `\$COMMAND{ARGUMENT}`.
+Finally, some commands also take an optional external command and arguments:
+`\$COMMAND(EXTERNAL-COMMAND, ARGUMENT, …){ARGUMENT}`; the argument in braces
+is optional in this case.
 
 Nancy treats its input as 8-bit ASCII, but command names and other
 punctuation only use the 7-bit subset. This means that any text encoding
@@ -152,27 +156,24 @@ worked example.
 ### Running other programs
 
 In addition to the rules given above, Nancy also allows `\$include` and
-`\$paste` to take their input from programs. This can be useful in a variety
-of ways: to insert the current date or time, to make a calculation, or to
-convert a file to a different format.
+`\$paste` to run external programs, whose output becomes the result of the
+command. If an input is given, it is supplied to the program’s standard
+input. This can be useful in a variety of ways: to insert the current date
+or time, to make a calculation, or to convert a file to a different format.
 
-Nancy can run a program in two ways:
+Nancy looks for programs in two ways:
 
-1. If a file found by an `\$include` or `\$paste` command has the “execute”
-   permission, it is run.
+1. Using the same rules as for finding an `\$include` or `\$paste` input,
+   Nancy looks for a file which has the “execute” permission.
 
 2. If no file of the given name can be found using the rules in the previous
    section, Nancy looks for an executable file on the user’s `PATH` (the
-   list of directories specified by the `PATH` environment variable). If one
-   is found, it is run.
-
-In either case, arguments may be passed to the program: use
-`\$include{FILE,ARGUMENT_1,ARGUMENT_2,…}`, or the equivalent for `\$paste`.
+   list of directories specified by the `PATH` environment variable).
 
 For example, to insert the current date:
 
 ```
-\$paste{date,+%Y-%m-%d}
+\$paste(date,+%Y-%m-%d)
 ```
 
 See the [date example](Cookbook.md#date-example) in the Cookbook for more
@@ -188,14 +189,13 @@ To prevent a comma from being interpreted as an argument separator, put a
 backslash in front of it:
 
 ```
-\$include{cat,I\, Robot.txt,3 Rules of Robotics.txt}
+\$include(cat,I\, Robot.txt,3 Rules of Robotics.txt)
 ```
 
-This will run the `\$include` command with the following arguments:
+This will run the `cat` command with the following arguments:
 
-1. `cat`
-2. `I, Robot.txt`
-3. `3 Rules of Robotics.txt`
+1. `I, Robot.txt`
+2. `3 Rules of Robotics.txt`
 
 Note that the filenames supplied to `cat` refer not to the input tree, but
 to the file system.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Change the syntax of `$include` to: `$include(command,arg,...){file}` (and similar for `$paste`). The semantics are that `file` is found and expanded, then the result is fed to `command arg...`'s stdin. If you omit the `{file}`, then you are just running a command and expanding/pasting its output.