|
| From: | madmurphy |
| Subject: | Re: printf-like output for gnunet-search |
| Date: | Sun, 13 Feb 2022 07:39:07 +0000 |
So, a small recap. What help page is the right one for gnunet-search?
Option 1: The current version with only the header reduced:
gnunet-search [OPTIONS] KEYWORD1 KEYWORD2 ...
Search for files that have been published on GNUnet
Arguments mandatory for long options are also mandatory for short options.
-a, --anonymity=LEVEL set the desired LEVEL of receiver-anonymity
(default: 1)
-b, --bookmark-only do not search, print only the URI that points to
this search
-c, --config=FILENAME use configuration file FILENAME
-F, --dir-printf=FORMAT write search results for directories according to
FORMAT; the format specifiers supported here
are identical to those supported in the
--printf argument (please refer to it for more
information); if missing, --dir-printf defaults
to --printf; if --printf is missing too
--dir-printf defaults to `#%n:\ngnunet-download
-o "%f" -R %u\n\n`
-f, --printf=FORMAT write search results according to FORMAT, where
%a is the complete list of all the printable
metadata available (each member will be
displayed according to the --iter-printf
argument) - use %j for printing only one field
- %f is the file's name, %l is the file name's
length, %m is the file's mime type, %n is the
search result number, %s is the file's size in
bytes and %u is the file's URI; the %a and %j
specifiers optionally support metatype
filtering via hash sign (e.g. `%5#j` prints a
book title, if present - see libextractor's
metatypes for the complete list of numerical
identifiers); if missing, --printf defaults to
`#%n:\ngnunet-download -o "%f" %u\n\n`
-h, --help print this help
-i, --iter-printf=FORMAT when the %a or %j format specifiers appear in
--printf or --dir-printf, list each metadata
property according to FORMAT, where %p is the
property's content, %l is the content's length
in bytes, %t is the property type, %i is the
property type's unique identifier, %n is the
property number and %w is the name of the
plugin that provided the information; if
missing, --iter-printf defaults to ` %t: %p\n`
-L, --log=LOGLEVEL configure logging to use LOGLEVEL
-l, --logfile=FILENAME configure logging to write logs to FILENAME
-N, --results=VALUE automatically terminate search after VALUE
results are found
-n, --no-network only search the local peer (no P2P network
search)
-o, --output=FILENAME create a GNUnet directory with search results at
FILENAME (e.g. `gnunet-search
--output=commons.gnd commons`)
-s, --silent silent mode (requires the --output argument)
-t, --timeout=DELAY automatically terminate search after DELAY; the
value given must be a number followed by a
space and a time unit, for example "500 ms";
without a unit it defaults to microseconds -
1000000 = 1 second; if 0 or omitted it means to
wait for CTRL-C
-V, --verbose be verbose (append "%a\n" to the default --printf
and --dir-printf arguments - ignored when these
are provided by the user)
-v, --version print the version number
Report bugs to gnunet-developers@gnu.org.
Home page: http://www.gnu.org/s/gnunet/
General help using GNU software: http://www.gnu.org/gethelp/Option 2: The version further reduced after Alessio's comments
gnunet-search [OPTIONS] KEYWORD1 KEYWORD2 ...
Search for files that have been published on GNUnet
Arguments mandatory for long options are also mandatory for short options.
-a, --anonymity=LEVEL set the desired LEVEL of receiver-anonymity
(default: 1)
-b, --bookmark-only do not search, print only the URI that points to
this search
-c, --config=FILENAME use configuration file FILENAME
-F, --dir-printf=FORMAT write search results for directories according to
FORMAT; accepted placeholders are: %a, %f, %j,
%l, %m, %n, %s; defaults to the value of
--printf when omitted; if --printf is omitted
too defaults to `#%n:\ngnunet-download -o "%f"
-R %u\n\n`
-f, --printf=FORMAT write search results according to FORMAT;
accepted placeholders are: %a, %f, %j, %l, %m,
%n, %s; defaults to `#%n:\ngnunet-download -o
"%f" %u\n\n` when omitted
-h, --help print this help
-i, --iter-printf=FORMAT when the %a or %j format specifiers appear in
--printf or --dir-printf, list each metadata
property according to FORMAT; accepted
placeholders are: %i, %l, %n, %p, %t, %w;
defaults to ` %t: %p\n` when omitted
-L, --log=LOGLEVEL configure logging to use LOGLEVEL
-l, --logfile=FILENAME configure logging to write logs to FILENAME
-N, --results=VALUE automatically terminate search after VALUE
results are found
-n, --no-network only search the local peer (no P2P network
search)
-o, --output=FILENAME create a GNUnet directory with search results at
FILENAME (e.g. `gnunet-search
--output=commons.gnd commons`)
-s, --silent silent mode (requires the --output argument)
-t, --timeout=DELAY automatically terminate search after DELAY; the
value given must be a number followed by a
space and a time unit, for example "500 ms";
without a unit it defaults to microseconds -
1000000 = 1 second; if 0 or omitted it means to
wait for CTRL-C
-V, --verbose be verbose (append "%a\n" to the default --printf
and --dir-printf arguments - ignored when these
are provided by the user)
-v, --version print the version number
Report bugs to gnunet-developers@gnu.org.
Home page: http://www.gnu.org/s/gnunet/
General help using GNU software: http://www.gnu.org/gethelp/Option 3: Any other new proposal?
...
--madmurphy
Hi Alessio,
the line saying "The main reason is that it's so long to be basically unreadable." wasn't related only to the program's description, but to the whole output, sorry for the confusion.
[...]
Writing something like:
"Format output according to FORMAT.
Accepted placeholders: %j %l %f %u %n
Defaults to the value of --printf when omitted"
is perfectly fine.We can do that (see file attached), but the output would not become terribly smaller, and the reason is that the program accepts many arguments. The modified help page would look like this:
$ gnunet-search --help gnunet-search [OPTIONS] KEYWORD1 KEYWORD2 ... Search for files that have been published on GNUnet Arguments mandatory for long options are also mandatory for short options. -a, --anonymity=LEVEL set the desired LEVEL of receiver-anonymity (default: 1) -b, --bookmark-only do not search, print only the URI that points to this search -c, --config=FILENAME use configuration file FILENAME -F, --dir-printf=FORMAT write search results for directories according to FORMAT; accepted placeholders are: %a, %f, %j, %l, %m, %n, %s; defaults to the value of --printf when omitted; if --printf is omitted too defaults to `#%n:\ngnunet-download -o "%f" -R %u\n\n` -f, --printf=FORMAT write search results according to FORMAT; accepted placeholders are: %a, %f, %j, %l, %m, %n, %s; defaults to `#%n:\ngnunet-download -o "%f" %u\n\n` when omitted -h, --help print this help -i, --iter-printf=FORMAT when the %a or %j format specifiers appear in --printf or --dir-printf, list each metadata property according to FORMAT; accepted placeholders are: %i, %l, %n, %p, %t, %w; defaults to ` %t: %p\n` when omitted -L, --log=LOGLEVEL configure logging to use LOGLEVEL -l, --logfile=FILENAME configure logging to write logs to FILENAME -N, --results=VALUE automatically terminate search after VALUE results are found -n, --no-network only search the local peer (no P2P network search) -o, --output=FILENAME create a GNUnet directory with search results at FILENAME (e.g. `gnunet-search --output=commons.gnd commons`) -s, --silent silent mode (requires the --output argument) -t, --timeout=DELAY automatically terminate search after DELAY; the value given must be a number followed by a space and a time unit, for example "500 ms"; without a unit it defaults to microseconds - 1000000 = 1 second; if 0 or omitted it means to wait for CTRL-C -V, --verbose be verbose (append "%a\n" to the default --printf and --dir-printf arguments - ignored when these are provided by the user) -v, --version print the version number Report bugs to gnunet-developers@gnu.org. Home page: http://www.gnu.org/s/gnunet/ General help using GNU software: http://www.gnu.org/gethelp/As for the man page, I can think of a few example to add. But wouldn't putting all the format specifiers together create confusion, since
--printfand--iter-printfuse different format specifiers? I would use a unified section for the examples, but I would leave the specifier lists where they are.
--madmurphyOn Fri, Feb 11, 2022 at 11:56 PM Alessio Vanni <vannilla@firemail.cc> wrote:Before replying on your points, a correction: the line saying "The main
reason is that it's so long to be basically unreadable." wasn't related
only to the program's description, but to the whole output, sorry for
the confusion.
As for the rest:
> Man pages are not always installed by people, and a help page should
> be able to explain the bare minimum.
In my opinion, if people don't install man pages and then need them,
it's their own fault if then they don't know what to do. Of course, if
the OS doesn't come shipped with them it's not the user's fault, but it
still doesn't mean the description of the flag has to be a full paragraph.
I believe simply listing the accepted formats is enough, e.g.
"Format output according to FORMAT.
Accepted placeholders: %j %l %f %u %n"
That way people that know what they mean can see the full range of
accepted values — for example to make sure they are not adding useless
modifiers — without having to scan a long piece of text, while people
that don't know, either read the documentation somehow or experiment
using the listed letters.
> However, since when not specified --dir-printf defaults to --printf, a
> mention of --printf will always be there in a way or another.
Of course, I was mostly referring to the fact that explaining the
purpose of a flag _only_ as "works like <another flag>" without
providing any other explanation doesn't really make for a great
experience.
Writing something like:
"Format output according to FORMAT.
Accepted placeholders: %j %l %f %u %n
Defaults to the value of --printf when omitted"
is perfectly fine.
Regarding the man page, I believe you should add a dedicated section
before "EXAMPLES" where you describe all the formatting modifiers.
If you put them right under the flag, not only you duplicate shared
values, but it becomes hard to check the available flags since the page
becomes unnecessarily long.
Of course, there are plenty of other programs out there with a lot of
flags and with very long descriptions, so scrolling for screenfuls
becomes the norm, but most of the time it's the actual behaviour that
needs to be explained at length. In this case, the flags are very simple
in what they do, so I believe having formatting rules be in a dedicated
section is the best course of action.
These are my opinions as someone who can never remember the accepted
flags or how they work, and thus need to run programs with `--help' or
open up the manual before actually running the program.
Thanks,
A.V.
| [Prev in Thread] | Current Thread | [Next in Thread] |