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 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 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 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