D1270: help: adding a topic on flags

[rdamazio (Rodrigo Damazio Bovendorp)]

rdamazio added a comment.


  In https://phab.mercurial-scm.org/D1270#21058, @martinvonz wrote:
  
  > We're in code freeze for approximately two more days, so this will have to wait until ~Thursday. Still, thanks for the patch. I'm happy to include something like this. Things that struck me as missing:
  >
  > 1. Long vs short form (that e.g. "--verbose" and "-v" are equivalent if the refer to the same flag, which they do)
  > 2. Non-list, non-boolean flags that take arguments, such as "--rev", and that "--rev=tip", "--rev tip", "-r=tip", "-r tip", and "-rtip" are equivalent
  > 3. Short flags can be combined: "-pvr tip" is valid
  > 4. Later flags override earlier flags
  >
  >   We don't necessarily have to include all that in the first patch.
  
  
  Tried to address all of these.

INLINE COMMENTS

> av6 wrote in flags.txt:7
> This "lists of strings" caught my attention, but it took me some time to figure out what's the matter. I don't feel strongly, but here are some points:
> 
> 1. it's not clear what a "list of strings" is and how to specify it: is it a comma-separated list?
> 2. it's not a type that //one// command-line flag can take (i.e. no `--flag=foo,bar` or anything), you must use multiple flags on command line to build this list, so it's unlike the 3 previous types
> 3. I don't think we have anywhere (in the code) a list of integers or booleans right now, but nothing prevents this in future, or in an extension
> 
> I think this data type is a result of looking at the internals that allow some python variables (associated with handling command line flags in the code) to be lists, but because our CLI is not python, this phrase is more distracting than helpful. I think taking the note that's in `hg help` and explaining it is better: "[+] can be repeated" (essentially merging "​Specifying list flags" and "Overriding flag defaults").

That's the whole point of the "Specifying list flags" section below, and in fact what motivated me to send this patch.
I don't think the code supports parsing a list as numbers or booleans, right now.

> av6 wrote in flags.txt:35
> This is a weird-looking macro. Does it work when rendered into e.g. HTML (can be seen hgweb)? I've only seen this format:
> 
>   :hg:`help config`

Assume that I don't know what I'm doing, as far as the format of this file is concerned :) I just tried hgweb and fixed a few things.

> av6 wrote in flags.txt:49
> There are also global flags, they are hidden by default too. I guess you can put them into these 3 categories, but I don't think of --quiet or --verbose as advanced (much less experimental or deprecated). Just a nitpick.

--verbose is used to show those flags in hg help, it's not that that flag itself is advanced.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D1270

To: rdamazio, #hg-reviewers
Cc: av6, dlax, martinvonz, mercurial-devel