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 <vanni...@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.
>
>
<<attachment: gnunet-search_shorter_help_page.zip>>
