Blame SOURCES/0024-man-augtool.pod-update-man-page-with-new-commands.patch

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