Fix spelling of member of struct num_format.

[adu.git] / select.ggo

diff --git a/select.ggo b/select.ggo
index 78d6d75b12afadf6b830c852993efdffd25925fa..d96609536e46865dd6134a918e185103e5c0c6ff 100644 (file)
--- a/select.ggo
+++ b/select.ggo
@@ -1,50 +1,118 @@
+option "user" u
+#~~~~~~~~~~~~~~
+"users to take into account"
+string typestr="user_name"
+optional
+multiple
+details="
+       This option may be given multiple times in which case all given
+       user names are considered admissible. See also --uid below.
+"

 
 

-option "uid" u
+option "uid" U

 #~~~~~~~~~~~~~
 "user id(s) to take into account"
 string typestr="uid_spec"
 optional
 details="
 #~~~~~~~~~~~~~
 "user id(s) to take into account"
 string typestr="uid_spec"
 optional
 details="

-       An uid specifier may be a single number, or a range of uids.
+       An uid specifier may be a single uid, a range of uids,
+       or a comma-separated list of single uids or ranges.

        Example:
 
        Example:
 

-       --uid 42    # only consider uid 42
-       --uid 42-   # only consider uids greater or equal than 42
-       --uid 23-42 # only consider uids between 23 and 42, inclusively.
-       --uid 23-42,666-777,88 # consider uids 23-42, 666-777 and 88.
+       Only consider uid 42:
+               --uid 42
+
+       Only consider uids greater or equal than 42:
+               --uid 42-
+
+       Only consider uids between 23 and 42, inclusively:
+               --uid 23-42
+
+       Consider uids 23-42, 666-777 and 88:
+               --uid 23-42,666-777,88
+
+       If no --user option is given and also --uid option is not given
+       (the default), all users are taken into account.

 "
 
 "
 

-option "limit" L
+option "limit" l

 #~~~~~~~~~~~~~~~
 "Limit output"
 #~~~~~~~~~~~~~~~
 "Limit output"

-int  typestr="num"
+int typestr="num"

 default="-1"
 optional
 details="
        Only print num lines of output. If negative (the default),
 default="-1"
 optional
 details="
        Only print num lines of output. If negative (the default),

-       print all lines.
+       print all lines. This option is honored in all select modes
+       except global_summary (which outputs only one single line).

 "
 
 "
 

-option "no-headers" -
-#~~~~~~~~~~~~~~~~~~~~
-"supress descriptions for listings/summaries"
-flag off
+option "pattern" p
+#~~~~~~~~~~~~~~~~~
+"only consider matching directories"
+string typestr="regex"
+optional
+details="
+       Regular expression that must match the directory name for
+       the directory to be considered for the output of the query.
+       See regex(7) for details.
+
+       Depending on whether --print-base-dir is given, the absolute
+       directory name or only the part of the directory name below
+       the base directory is matched against \"regex\".
+
+       If this option is not given (the default) all directories
+       are taken into account.
+
+       If \"regex\" starts with '!', directories are matched against
+       the remaining part of \"regex\" and the sense of matching is
+       reversed.
+"
+
+option "header" H
+#~~~~~~~~~~~~~~~~
+"use a customized header for listings/summaries"
+string typestr="string"
+optional
+details="
+       This option can be used to print any string instead of the
+       default header line (which depends on the selected mode).
+
+       In user_list mode the header is a format string which allows
+       to include the uid and the user name in the header. See the
+       --format option for more details.
+
+       It is possible to set this to the empty string to suppress
+       the header completely. This is mostly useful to feed the
+       output to scripts.
+"
+
+option "trailer" T
+#~~~~~~~~~~~~~~~~~
+"use a customized trailer for listings/summaries"
+string typestr="string"
+optional
+default=""

 details="
 details="

-       This is mostly useful to feed the output of adu to scripts.
+       This option can be used to print any string at the end of
+       the query output.
+
+       In user_list mode the trailer is a format string with the
+       same semantics like the header string.

 "
 
 option "select-mode" m
 #~~~~~~~~~~~~~~~~~~~~~
 "How to print the results of the query"
 enum typestr="<key>"
 "
 
 option "select-mode" m
 #~~~~~~~~~~~~~~~~~~~~~
 "How to print the results of the query"
 enum typestr="<key>"

-values="global_list","global_summary","user_list","user_summary"
-default="global_list"
+values="user_summary","user_list","global_summary","global_list"
+default="user_summary"

 optional
 details="
 optional
 details="

-       global_list: List of directories, regardless of owner.
-       global_summary: Only print totals.
+       user_summary: Print totals for each admissible uid.

        user_list: Print a list for each admissible uid.
        user_list: Print a list for each admissible uid.

-       user_summary Print totals for each admissible uid.
+       global_summary: Only print totals.
+       global_list: List of directories, regardless of owner.

 "
 
 option "list-sort" s
 "
 
 option "list-sort" s


@@ -62,11 +130,32 @@ details="
 option "output" o
 #~~~~~~~~~~~~~~~~
 "file to write output to"
 option "output" o
 #~~~~~~~~~~~~~~~~
 "file to write output to"

-string typestr="<path>"
+string typestr="path"

 optional
 default="-"
 details="
 optional
 default="-"
 details="

-       If empty, or not given, use stdout.
+       If empty, or not given, use stdout. The following conventions
+       cause the output to be written differently:
+
+       An output file name of \"-\" means stdout.
+
+       \"path\" may be prepended by '>' which instructs adu to
+       truncate the output file to length zero.  If \"path\" does
+       not start with '>' and \"path\" already exists, the select
+       query is being aborted. Otherwise, \"path\" is created and
+       output is written to \"path\".
+
+       If the first two characters of \"path\" are '>', the output
+       file (given by removing the leading \">>\" from \"path\")
+       is being opened in append mode. It is no error if the output
+       file does not exist but, as above, the output file name \">>\"
+       is considered invalid.
+
+       If the first character of \"path\" is '|', a pipe is created
+       and the rest of \"path\" is being executed with its standard in
+       redirected to the reading end of the pipe. The output of adu
+       is written to the writing end of the pipe. Again, specifying
+       only \"|\" is considered invalid and causes an error.

 "
 
 option "user-summary-sort" -
 "
 
 option "user-summary-sort" -


@@ -97,13 +186,14 @@ option "format" f
 string typestr="<format_string>"
 optional
 details="
 string typestr="<format_string>"
 optional
 details="

+

        A string that specifies how the output of the select query is
        A string that specifies how the output of the select query is

-       goint to be formated.  Depending on the chosen select-mode,
+       going to be formated. Depending on the chosen select-mode,

        several conversion specifiers are available and a different
        default value for this option applies.
 
        adu knows four different types of directives: string, id,
        several conversion specifiers are available and a different
        default value for this option applies.
 
        adu knows four different types of directives: string, id,

-       count and size.  These are explained in more detail below.
+       count and size. These are explained in more detail below.

 
        The general syntax for string and id directives is %(name:a:w)
        where \"name\" is the name of the directive, \"a\" specifies
 
        The general syntax for string and id directives is %(name:a:w)
        where \"name\" is the name of the directive, \"a\" specifies


@@ -113,24 +203,28 @@ details="
        The alignment specifier is a single character: Either \"l\",
        \"r\", or \"c\" may be given to specify left, right and
        centered alignment respectively. The with specifier is a
        The alignment specifier is a single character: Either \"l\",
        \"r\", or \"c\" may be given to specify left, right and
        centered alignment respectively. The with specifier is a

-       positive integer.  Both \"a\" and \"w\" are optional.
+       positive integer. Both \"a\" and \"w\" are optional.

 
 

-       A string directive supported by adu is \"dirname\" which is
-       subsitituted by the name of the directory. It is available
+       One string directive supported by adu is \"dirname\" which is
+       substituted by the name of the directory. It is available

        if either user_list or global_list mode was selected via
        --select-mode.
 
        Examples:
        if either user_list or global_list mode was selected via
        --select-mode.
 
        Examples:

+               Print dirname without any padding:

 
 

-               \"%(diname)\" # print dirname without any padding
-               \"%(dirname:c:20)\" # center dirname in a 20 chars wide field
+               \"%(diname)\"

 
 

-       The other two types of directives, count and size, are used
-       for numbers. The syntax for these is %(name:a:w:u). The \"a\"
-       and the \"w\" specifier have the same meaning as for the string
-       and id directives. The additional \"u\" specifier selects a unit
-       in which the number that corresponds to the directive should
-       be formated. All three specifiers are optional.
+               Center dirname in a 20 chars wide field:
+
+               \"%(dirname:c:20)\"
+
+       The count and size directives are used for non-negative
+       numbers. The syntax for these is %(name:a:w:u). The \"a\" and
+       the \"w\" specifiers have the same meaning as for the string
+       and id directives. The additional \"u\" specifier selects a
+       unit in which the number that corresponds to the directive
+       should be formated. All three specifiers are optional.

 
        Possible units are the characters of the set \" bkmgtBKMGT\"
        specifying bytes, kilobytes, megabytes, gigabytes and
 
        Possible units are the characters of the set \" bkmgtBKMGT\"
        specifying bytes, kilobytes, megabytes, gigabytes and


@@ -155,30 +249,35 @@ details="
        tab character for these combinations respectively.
 
        Examples:
        tab character for these combinations respectively.
 
        Examples:

+               Print size in gigabytes right-aligned:
+                       \"%(size:r::G)\"
+
+               As before, but use 5 char wide field:
+                       \"%(size:r5::G)\"
+
+               As before, but suppress trailing \"G\":
+                       \"%(size:r5::*G)\"
+
+
+       The following list contains all directives known to adu,
+       together with their types, and for which modes each of
+       them may be used.
+
+               pw_name (string): user name. Available for user_list,
+               user_summary and for the header in user_list mode.
+
+               uid (id): user id. Available for user_list,
+               user_summary and for the header in user_list mode.
+
+               files (count): number of files. Available for all
+               modes.
+
+               dirname (string): name of the directory. Available
+               for user_list and global_list.
+
+               size (size): total size/ directory size. Available
+               for all modes.

 
 

-               \"%(size:r::G)\" # print size in gigabytes right-aligned
-               \"%(size:r5::G)\" # as before, but use 5 char wide field
-               \"%(size:r5::*G)\" # as before, but supress trailing \"G\"
-
-       List of directives and types known to adu, together with their types:
-
-               name            type            meaning
-               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-               pw_name         string          user name
-               uid             id              user id
-               files           count           number of files
-               dirname         string          name of the directory
-               size            size            total size/ directory size
-               dirs            count           number of directories
-
-       Not all directives are available for each mode:
-
-               name            available in directives
-               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-               pw_name         user_list, user_summary
-               uid             user_list, user_summary
-               files           everywhere
-               dirname         user_list, global_list
-               size            everywhere
-               dirs            suer_summary, global_summary
+               dirs (count): number of directories. Available
+               for user_summary and global_summary.

 "
 "