Updated documentation

Author: Chris White

L1.md

@@ -0,0 +1,121 @@
+# NAME
+
+XML::Axk::Core::L1 - ack-like XML processor, language 1
+
+# EXAMPLE
+
+    L1
+    on { xpath(q<//item>) } run {say "$NOW: " . $E->getTagName}, CIAO
+        # "CIAO" can also be "HI" or "BYE" (default HI).
+        # "entering" is a synonym for "on" with no HI/BYE/CIAO.
+    whenever { xpath(q<//item>) } run {say "$NOW: " . $E->getTagName};
+        # the same as the "on ... CIAO" line
+    leaving { xpath(q<//item>) } run {say "$NOW: " . $E->getTagName};
+
+# PATTERNS AND ACTIONS
+
+## `on {<matcher>} run {<action>} [, <when>]`
+
+Whenever `<matcher>` says that a node matches, run `<action>`.
+The optional `<when>` parameter says when in the course of processing to
+run `<action>`:
+
+- `HI`
+
+    When the node is first reached, before any of its children are processed
+
+- `BYE`
+
+    After all of the node's children have been processed.
+
+- `CIAO`
+
+    Both `HI` and `BYE`.  Suggestions for alternative terminology are welcome.
+
+## `entering`, `whenever` `leaving`
+
+    entering {<matcher>} run {<action>}
+    whenever {<matcher>} run {<action>}
+    leaving {<matcher>} run {<action>}
+
+The same as `on {} run {}`, with `when` set to `HI`, `CIAO`, or `BYE`
+respectively.
+
+## `perform { <action> } <matcher> [, <when>]`
+
+If you prefer RPN, or you want to save some characters, you can put the
+`<matcher>` after the `<action>` using `perform`.  For example,
+the following two lines have exactly the same effect:
+
+    on { xpath(q<//item>) } run {say "$NOW: " . $E->getTagName}, CIAO
+    perform {say "$NOW: " . $E->getTagName} xpath(q<//item>), CIAO
+
+# VARIABLES
+
+When an `<action>` is running, it has access to predefined variables
+that hold the state of the element being matched.  This is similar to `$0`,
+`$1`, ... in awk.
+
+- **$D**
+
+    The current XML document
+
+- **$E**
+
+    The XML element that was matched
+
+- **$NOW**
+
+    The current phase, as a human-readable string: `entering` for `HI`,
+    `leaving` for `BYE`, and `BOTH` for `CIAO`.
+
+# MATCHERS
+
+## `xpath('xpath expression')`
+
+Match nodes that match the given XPath expression.  Remember that Perl will
+interpolate `@name` in double-quotes, so single-quote or `q{}` your XPath
+expressions.
+
+## `sel('selector')`
+
+Match nodes that match the given selector.
+
+## `always`, `never`
+
+Always or never match, respectively.
+
+# SPECIAL ACTIONS
+
+## `pre_all {<block>}`
+
+Run `<block>` before any file is processed.
+
+## `pre_file {<block>}`
+
+Run `<block>($filename)` before each file is processed.
+
+## `post_file {<block>}`
+
+Run `<block>($filename)` after each file is processed.
+
+## `post_all {<block>}`
+
+Run `<block>` after all files have been processed.
+
+# AUTHOR
+
+Christopher White, `cxwembedded at gmail.com`
+
+# CONTACT
+
+For any bug reports, feature requests, or questions, please see the
+information in [XML::Axk](https://metacpan.org/pod/XML::Axk).
+
+# LICENSE AND COPYRIGHT
+
+Copyright (c) 2018 Christopher White.  All rights reserved.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of the the Artistic License (2.0). Details are in the LICENSE
+file accompanying this distribution.

MANIFEST.SKIP

@@ -1,5 +1,8 @@
 # MANIFEST.SKIP for Text::PerlPP
 
+# Markdown files that we keep for GitHub, but don't need on CPAN
+^L1.md
+
 # Avoid version control files.
 \bRCS\b
 \bCVS\b

README.md

@@ -13,28 +13,26 @@ To install this module, run the following commands:
 
 After installation, run `axk`.  Options are similar to `awk`.  Input scripts
 are Perl 5.18 with functions to, e.g., run on any node matching a given XPath.
+See [L1.md](L1.md) for more details.  For example, the script
 
-## SUPPORT AND DOCUMENTATION
-
-After installing, you can find documentation for this module with the
-perldoc command.
+    L1
+    on { xpath(q<//item>) } run { say "$NOW: " . $E->getTagName };
 
-    perldoc XML::Axk
+or the equivalent command line
 
-You can also look for information at:
+    axk -e 'on { xpath(q<//item>) } run { say "$NOW: " . $E->getTagName }' t/ex/ex1.xml
 
-    RT, CPAN's request tracker (report bugs here)
-        http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-Axk
+will print the tag name of each `//item` node in the input, along with an
+indication (`$NOW`) of whether the action is being run when `entering` or
+`leaving` the node.
 
-    AnnoCPAN, Annotated CPAN documentation
-        http://annocpan.org/dist/XML-Axk
-
-    CPAN Ratings
-        http://cpanratings.perl.org/d/XML-Axk
+## SUPPORT AND DOCUMENTATION
 
-    Search CPAN
-        http://search.cpan.org/dist/XML-Axk/
+After installing, you can find documentation for this module with the
+perldoc command:
 
+ - `perldoc XML::Axk::App` for command-line usage instructions
+ - `perldoc XML::Axk::L1` for the language reference
 
 ## LICENSE AND COPYRIGHT