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

[Tim Rühsen]

Hi nemo,

On 12/4/18 10:15 AM, Nemo wrote:
> 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.
> 
> 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.
> 
> I will gladly take this up if folks here agree.

Thanks for the heads up and for the offer to work on it. That would
improve readability/understanding for occasional users of Wget.

The HTML docs (as man pages and other formats) are generated from
doc/wget.texi. So please make the fixes there. Since this like won't be
a "trivial" change (less than 15 lines changed), you have to sign the
FSF copyright assignment. If you agree I'll send a copy to you via PM.

And for the fix itself... the idea of showing long flags while hovering
is good. But it wouldn't apply to other doc formats. Another approach
would be to just document both forms as alternatives. WDYT ?

Also it would be great to have a similar change for Wget2. See
https://gitlab.com/gnuwget/wget2, the changes would go into docs/wget2.md.

Regards, Tim

signature.asc
Description: OpenPGP digital signature