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 [email protected].
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 [email protected].
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 <[email protected]> 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 [email protected].
> 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 <[email protected]>
> 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.
>>
>>
