D1270: help: adding a topic on flags

[av6 (Anton Shestakov)]

av6 added inline comments.

INLINE COMMENTS

> flags.txt:7
> +Mercurial command-line flags can be strings, numbers, booleans, or lists of
> +strings.
> +

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").

> flags.txt:35
> +
> +For more information on hgrc files, see :hg:help:config.
> +

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`

> flags.txt:49
> +Some flags are not shown in a command's help by default - specifically, those
> +that are deemed to be experimental, deprecated or advanced. To show all flags,
> +add the --verbose flag for the help command::

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.

REPOSITORY
  rHG Mercurial

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

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