gnunet-developers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: printf-like output for gnunet-search


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


On Sat, Feb 12, 2022 at 1:58 AM madmurphy <madmurphy333@gmail.com> wrote:

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 --printf and --iter-printf use different format specifiers? I would use a unified section for the examples, but I would leave the specifier lists where they are.

--madmurphy


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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]