Patchwork help: avoid using "$n" parameter in revsetalias example

# HG changeset patch
# User Yuya Nishihara <yuya@tcha.org>
# Date 1458985856 -32400
#      Sat Mar 26 18:50:56 2016 +0900
# Node ID cead51b79a624d669d9333574b65498c60121d9d
# Parent  86db5cb55d46db3984e94600f3902f47a16437ae
help: avoid using "$n" parameter in revsetalias example

Because parsing "$n" requires a crafted tokenizer, it exists only for backward
compatibility (as documented in revset._tokenizealias.) This patch updates the
examples so that users are encouraged to use symbolic names instead of "$n"s.

I'm going to implement alias expansion in templater, which won't support "$n"
parameters to make my life easier. Templater is more complicated than revset
because tokenizer and parser call each other.

On 11/04/2016 16:36, Yuya Nishihara wrote:
> # HG changeset patch
> # User Yuya Nishihara <yuya@tcha.org>
> # Date 1458985856 -32400
> #      Sat Mar 26 18:50:56 2016 +0900
> # Node ID cead51b79a624d669d9333574b65498c60121d9d
> # Parent  86db5cb55d46db3984e94600f3902f47a16437ae
> help: avoid using "$n" parameter in revsetalias example
>
> Because parsing "$n" requires a crafted tokenizer, it exists only for backward
> compatibility (as documented in revset._tokenizealias.) This patch updates the
> examples so that users are encouraged to use symbolic names instead of "$n"s.
>
> I'm going to implement alias expansion in templater, which won't support "$n"
> parameters to make my life easier. Templater is more complicated than revset
> because tokenizer and parser call each other.
>
> diff --git a/mercurial/help/revsets.txt b/mercurial/help/revsets.txt
> --- a/mercurial/help/revsets.txt
> +++ b/mercurial/help/revsets.txt
> @@ -66,7 +66,7 @@ existing predicates or other aliases. An
>     <alias> = <definition>
>
>   in the ``revsetalias`` section of a Mercurial configuration file. Arguments
> -of the form `$1`, `$2`, etc. are substituted from the alias into the
> +of the form `$1`, `foo`, `BAR`, etc. are substituted from the alias into the
>   definition.

Would it be sensible to remove `$1` completely here, and replace with a 
symbolic name such as `a1`? I would expect that users who see $1 in the 
wild having seen a1 documented would work out that it's a literal 
parameter substitution, and by not documenting the $n form at all, we 
encourage new users to forget that it's possible.

Otherwise, this looks good to me.
>
>   For example,
> @@ -75,8 +75,8 @@ For example,
>
>     [revsetalias]
>     h = heads()
> -  d($1) = sort($1, date)
> -  rs($1, $2) = reverse(sort($1, $2))
> +  d(s) = sort(s, date)
> +  rs(s, k) = reverse(sort(s, k))
>
>   defines three aliases, ``h``, ``d``, and ``rs``. ``rs(0:tip, author)`` is
>   exactly equivalent to ``reverse(sort(0:tip, author))``.
> @@ -85,14 +85,14 @@ An infix operator ``##`` can concatenate
>   one string. For example::
>
>     [revsetalias]
> -  issue($1) = grep(r'\bissue[ :]?' ## $1 ## r'\b|\bbug\(' ## $1 ## r'\)')
> +  issue(n) = grep(r'\bissue[ :]?' ## n ## r'\b|\bbug\(' ## n ## r'\)')
>
>   ``issue(1234)`` is equivalent to ``grep(r'\bissue[ :]?1234\b|\bbug\(1234\)')``
>   in this case. This matches against all of "issue 1234", "issue:1234",
>   "issue1234" and "bug(1234)".
>
>   All other prefix, infix and postfix operators have lower priority than
> -``##``. For example, ``$1 ## $2~2`` is equivalent to ``($1 ## $2)~2``.
> +``##``. For example, ``n ## m~2`` is equivalent to ``(n ## m)~2``.
>
>   Command line equivalents for :hg:`log`::
>
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel@mercurial-scm.org
> https://urldefense.proofpoint.com/v2/url?u=https-3A__www.mercurial-2Dscm.org_mailman_listinfo_mercurial-2Ddevel&d=CwIGaQ&c=5VD0RTtNlTh3ycd41b3MUw&r=mEgSWILcY4c4W3zjApBQLA&m=6CMkL614rcIVyxyAhMJB-ZyRgkKZOdZ0qVL6QptvROI&s=ZGd8X3SGrkOhTu-o_uQcVbIP5s5co9xOHFsJixHBCWU&e=
>

On Mon, 11 Apr 2016 20:06:27 +0100, Simon Farnsworth wrote:
> On 11/04/2016 16:36, Yuya Nishihara wrote:
> > # HG changeset patch
> > # User Yuya Nishihara <yuya@tcha.org>
> > # Date 1458985856 -32400
> > #      Sat Mar 26 18:50:56 2016 +0900
> > # Node ID cead51b79a624d669d9333574b65498c60121d9d
> > # Parent  86db5cb55d46db3984e94600f3902f47a16437ae
> > help: avoid using "$n" parameter in revsetalias example
> >
> > Because parsing "$n" requires a crafted tokenizer, it exists only for backward
> > compatibility (as documented in revset._tokenizealias.) This patch updates the
> > examples so that users are encouraged to use symbolic names instead of "$n"s.
> >
> > I'm going to implement alias expansion in templater, which won't support "$n"
> > parameters to make my life easier. Templater is more complicated than revset
> > because tokenizer and parser call each other.
> >
> > diff --git a/mercurial/help/revsets.txt b/mercurial/help/revsets.txt
> > --- a/mercurial/help/revsets.txt
> > +++ b/mercurial/help/revsets.txt
> > @@ -66,7 +66,7 @@ existing predicates or other aliases. An
> >     <alias> = <definition>
> >
> >   in the ``revsetalias`` section of a Mercurial configuration file. Arguments
> > -of the form `$1`, `$2`, etc. are substituted from the alias into the
> > +of the form `$1`, `foo`, `BAR`, etc. are substituted from the alias into the
> >   definition.  
> 
> Would it be sensible to remove `$1` completely here, and replace with a 
> symbolic name such as `a1`? I would expect that users who see $1 in the 
> wild having seen a1 documented would work out that it's a literal 
> parameter substitution, and by not documenting the $n form at all, we 
> encourage new users to forget that it's possible.

Good point, `a1`, `a2` sounds better. I hesitated to remove `$1`, but maybe
I should do because I wanted to hide `$n` which won't be supported by template
aliases.