[Top][All Lists]

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

Re: [Wget-dev] [docs] Suggestion: Using --long-flags in documentation

From: Darshit Shah
Subject: Re: [Wget-dev] [docs] Suggestion: Using --long-flags in documentation
Date: Tue, 4 Dec 2018 11:28:43 +0100
User-agent: NeoMutt/20180716

* Nemo <address@hidden> [181204 10:29]:
> Hi,
> While the wget man page is very detailed, and the one-page-manual is great,
> there are lots of places in the documentation[0] where it uses short flags.
> For eg (from the --page-requisites section):
> > this author likes to use a few options in addition to ‘-p’:
> > wget -E -H -k -K -p http://site/document
> In order for a reader to understand that invocation, it becomes a game of
> search and hunt. To make this worse, most modern browsers don't give an
> option of doing a case-sensitive search, so searching for -k vs -K is pretty
> difficult as well.
> As a suggestion, I propose that we only use --long-flags in all examples
> used within the docs. I picked this up from a Changelog.com suggestion on
> scripting[1] and I think it applies equally well to documentation.

Thanks for the suggestion. This seems like quite a valid request. However, I am
not entirely confident if always using the long forms is the best idea. It
*may* make some examples too long to read. But, I am still open to the idea of
doing it.

> One fix might be to show long flags on hover in the HTML docs wherever it is
> used. Could be accomplished by abusing `<abbr>` so that we don't use JS.

This could work. I don't know much about the <abbr> tag and how it works / how
well it is supported in modern browsers. Anyways, the documentation is
generated using the gendocs script which is a part of gnulib. Any changes to
the script, should be taken up with gnulib at: address@hidden
> I will gladly take this up if folks here agree.
> --
> nemo
> [0]: https://www.gnu.org/software/wget/manual/wget.html
> [1]: https://changelog.com/posts/use-long-flags-when-scripting

Thanking You,
Darshit Shah
PGP Fingerprint: 7845 120B 07CB D8D6 ECE5 FF2B 2A17 43ED A91A 35B6

Attachment: signature.asc
Description: PGP signature

reply via email to

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