From 24fb307289750ec948dad249020d69143b98303a Mon Sep 17 00:00:00 2001
From: Dominic Cleal <dcleal@redhat.com>
Date: Mon, 2 Jun 2014 14:14:18 +0100
Subject: [PATCH] * man/augtool.pod: update man page with new commands

Fixes RHBZ#1100077

(cherry picked from commit 242acb210d87e94f6244d85f22301caa630885c0)

Conflicts:
	NEWS
	man/augtool.1
	man/augtool.pod

* man/augtool.pod: update man page with --span option

(cherry picked from commit 3c5a185afbfee4e3156ba9e0c6e2a5b32233b0cf)

Conflicts:
	NEWS
	man/augtool.1
---
 man/augtool.pod | 169 +++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 124 insertions(+), 45 deletions(-)

diff --git a/man/augtool.pod b/man/augtool.pod
index c145032..28f8563 100644
--- a/man/augtool.pod
+++ b/man/augtool.pod
@@ -92,6 +92,11 @@ creates no entries under C</augeas/load> whatsoever; to read any files,
 they need to be set up manually and loading must be initiated with a
 C<load> command. Using this option gives the fastest startup.
 
+=item B<--span>
+
+Load span positions for nodes in the tree, as they relate to the original
+file. Enables the use of the B<span> command to retrieve position data.
+
 =item B<--version>
 
 Print version information and exit. The version is also in the tree under
@@ -111,12 +116,69 @@ be distinguished by appending C<[N]> to their label to match the N-th
 sibling with such a label. The last sibling with a specific label can be
 reached as C<[last()]>. See L</EXAMPLES> for some examples of this.
 
+=head2 ADMIN COMMANDS
+
+The following commands control the behavior of Augeas and augtool itself.
+
 =over 4
 
+=item B<help>
+
+Print this help text
+
+=item B<load>
+
+Load files according to the transforms in C</augeas/load>.
+
 =item B<quit>
 
 Exit the program
 
+=item B<retrieve> E<lt>LENSE<gt> E<lt>NODE_INE<gt> E<lt>PATHE<gt> E<lt>NODE_OUTE<gt>
+
+Transform tree at PATH back into text using lens LENS and store the
+resulting string at NODE_OUT. Assume that the tree was initially read in
+with the same lens and the string stored at NODE_IN as input.
+
+=item B<save>
+
+Save all pending changes to disk. Unless either the B<-b> or B<-n>
+command line options are given, files are changed in place.
+
+=item B<store> E<lt>LENSE<gt> E<lt>NODEE<gt> E<lt>PATHE<gt>
+
+Parse NODE using LENS and store the resulting tree at PATH.
+
+=item B<transform> E<lt>LENSE<gt> E<lt>FILTERE<gt> E<lt>FILEE<gt>
+
+Add a transform for FILE using LENS. The LENS may be a module name or a
+full lens name.  If a module name is given, then "lns" will be the lens
+assumed.  The FILTER must be either "incl" or "excl".  If the filter is
+"incl",  the FILE will be parsed by the LENS.  If the filter is "excl",
+the FILE will be excluded from the LENS. FILE may contain wildcards.
+
+=back
+
+=head2 READ COMMANDS
+
+The following commands are used to retrieve data from the Augeas tree.
+
+=over 4
+
+=item B<dump-xml> I<[E<lt>PATHE<gt>]> I<[E<lt>FILENAMEE<gt>]>
+
+Print entries in the tree as XML. If PATH is given, printing starts there,
+otherwise the whole tree is printed. If FILENAME is given, the XML is saved
+to the given file.
+
+=item B<get> E<lt>PATHE<gt>
+
+Print the value associated with PATH
+
+=item B<label> E<lt>PATHE<gt>
+
+Get and print the label associated with PATH
+
 =item B<ls> E<lt>PATHE<gt>
 
 List the direct children of PATH
@@ -126,67 +188,91 @@ List the direct children of PATH
 Find all paths that match PATTERN. If VALUE is given, only the matching
 paths whose value equals VALUE are printed
 
-=item B<rm> E<lt>PATHE<gt>
+=item B<print> I<[E<lt>PATHE<gt>]>
 
-Delete PATH and all its children from the tree
+Print entries in the tree. If PATH is given, printing starts there,
+otherwise the whole tree is printed
 
-=item B<mv> E<lt>SRCE<gt> E<lt>DSTE<gt>
+=item B<span> E<lt>PATHE<gt>
 
-Move node SRC to DST. SRC must match exactly one node in the tree.  DST
-must either match exactly one node in the tree, or may not exist yet. If
-DST exists already, it and all its descendants are deleted. If DST does not
-exist yet, it and all its missing ancestors are created.
+Print the name of the file from which the node PATH was generated, as well
+as information about the positions in the file corresponding to the label,
+the value, and the entire node. PATH must match exactly one node.
 
-=item B<set> E<lt>PATHE<gt> E<lt>VALUEE<gt>
+You need to run 'set /augeas/span enable' prior to loading files to enable
+recording of span information. It is disabled by default.
 
-Associate VALUE with PATH. If PATH is not in the tree yet,
-it and all its ancestors will be created.
+=back
+
+=head2 WRITE COMMANDS
+
+The following commands are used to modify the Augeas tree.
+
+=over 4
 
 =item B<clear> E<lt>PATHE<gt>
 
 Set the value for PATH to NULL. If PATH is not in the tree yet, it and all
 its ancestors will be created.
 
-=item B<setm> E<lt>BASEE<gt> E<lt>SUBE<gt> E<lt>VALUEE<gt>
+=item B<clearm> E<lt>BASEE<gt> E<lt>SUBE<gt>
 
-Set multiple nodes in one operation.  Find or create a node matching SUB by
-interpreting SUB as a path expression relative to each node matching
+Clear multiple nodes values in one operation. Find or create a node matching SUB
+by interpreting SUB as a path expression relative to each node matching
 BASE. If SUB is '.', the nodes matching BASE will be modified.
 
-=item B<get> E<lt>PATHE<gt>
+=item B<ins> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
 
-Print the value associated with PATH
+Insert a new node with label LABEL right before or after PATH into the
+tree. WHERE must be either 'before' or 'after'.
 
-=item B<print> I<[E<lt>PATHE<gt>]>
+=item B<insert> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
 
-Print entries in the tree. If PATH is given, printing starts there,
-otherwise the whole tree is printed
+Alias of B<ins>.
 
-=item B<dump-xml> I<[E<lt>PATHE<gt>]> I<[E<lt>FILENAMEE<gt>]>
+=item B<mv> E<lt>SRCE<gt> E<lt>DSTE<gt>
 
-Print entries in the tree as XML. If PATH is given, printing starts there,
-otherwise the whole tree is printed. If FILENAME is given, the XML is saved
-to the given file.
+Move node SRC to DST. SRC must match exactly one node in the tree.  DST
+must either match exactly one node in the tree, or may not exist yet. If
+DST exists already, it and all its descendants are deleted. If DST does not
+exist yet, it and all its missing ancestors are created.
 
-=item B<ins> I<E<lt>LABELE<gt>> I<E<lt>WHEREE<gt>> I<E<lt>PATHE<gt>>
+=item B<move> E<lt>SRCE<gt> E<lt>DSTE<gt>
 
-Insert a new node with label LABEL right before or after PATH into the
-tree. WHERE must be either 'before' or 'after'.
+Alias of B<move>.
 
-=item B<save>
+=item B<rename> E<lt>SRCE<gt> E<lt>LBLE<gt>
 
-Save all pending changes to disk. Unless either the B<-b> or B<-n>
-command line options are given, files are changed in place.
+Rename the label of all nodes matching SRC to LBL.
 
-=item B<load>
+=item B<rm> E<lt>PATHE<gt>
 
-Load files according to the transforms in C</augeas/load>.
+Delete PATH and all its children from the tree
 
-=item B<defvar> E<lt>NAMEE<gt> E<lt>EXPRE<gt>
+=item B<set> E<lt>PATHE<gt> E<lt>VALUEE<gt>
 
-Define the variable NAME to the result of evaluating EXPR. The variable
-can be used in path expressions as $NAME. Note that EXPR is evaluated when
-the variable is defined, not when it is used.
+Associate VALUE with PATH. If PATH is not in the tree yet,
+it and all its ancestors will be created.
+
+=item B<setm> E<lt>BASEE<gt> E<lt>SUBE<gt> [E<lt>VALUEE<gt>]
+
+Set multiple nodes in one operation.  Find or create a node matching SUB by
+interpreting SUB as a path expression relative to each node matching
+BASE. If SUB is '.', the nodes matching BASE will be modified.
+
+=item B<touch> E<lt>PATHE<gt>
+
+Create PATH with the value NULL if it is not in the tree yet.  All its
+ancestors will also be created.  These new tree entries will appear
+last amongst their siblings.
+
+=back
+
+=head2 PATH EXPRESSION COMMANDS
+
+The following commands help when working with path expressions.
+
+=over 4
 
 =item B<defnode> E<lt>NAMEE<gt> E<lt>EXPRE<gt> [E<lt>VALUEE<gt>]
 
@@ -196,18 +282,11 @@ refer to it. If VALUE is given, this is the same as 'set EXPR VALUE'; if
 VALUE is not given, the node is created as if with 'clear EXPR' would and
 NAME refers to that node.
 
-=item B<span> E<lt>PATHE<gt>
-
-Print the name of the file from which the node PATH was generated, as well
-as information about the positions in the file corresponding to the label,
-the value, and the entire node. PATH must match exactly one node.
-
-You need to run 'set /augeas/span enable' prior to loading files to enable
-recording of span information. It is disabled by default.
-
-=item B<help>
+=item B<defvar> E<lt>NAMEE<gt> E<lt>EXPRE<gt>
 
-Print this help text
+Define the variable NAME to the result of evaluating EXPR. The variable
+can be used in path expressions as $NAME. Note that EXPR is evaluated when
+the variable is defined, not when it is used.
 
 =back