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

[Darshit Shah]

* 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

signature.asc
Description: PGP signature