[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
signature.asc
Description: PGP signature