[Top][All Lists]

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

Re: printf-like output for gnunet-search

From: Alessio Vanni
Subject: Re: printf-like output for gnunet-search
Date: Sat, 12 Feb 2022 00:56:12 +0100
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux)

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

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.


reply via email to

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