[PATCH] extensions: allow replacing command synopsis

[Ryan McElroy]

On 2/11/2015 11:53 AM, Gregory Szorc wrote:
> On Wed, Feb 11, 2015 at 8:32 AM, Ryan McElroy <rm at fb.com 
> <mailto:rm at fb.com>> wrote:
>
>
>     On 2/11/2015 6:37 AM, Augie Fackler wrote:
>
>         On Feb 10, 2015, at 10:43 PM, Ryan McElroy <rm at fb.com
>         <mailto:rm at fb.com>> wrote:
>
>             # HG changeset patch
>             # User Ryan McElroy <rm at fb.com <mailto:rm at fb.com>>
>             # Date 1423508565 28800
>             #      Mon Feb 09 11:02:45 2015 -0800
>             # Node ID dac1fbb56786c2033e188e7b762a9429cd7ff621
>             # Parent  ff5caa8dfd993680d9602ca6ebb14da9de10d5f4
>             extensions: allow replacing command synopsis
>
>         Hm, interesting. Can you give a sample reason why we should
>         support this?
>
>     In general, this will allow extensions that wrap/extend commands
>     to be better integrated.
>
>     Specifically, in the remotenames extension, we're adding some new
>     flags to commands -- some examples are --to to the push command,
>     and --all and --remote to bookmarks. Today, you can't edit the
>     synopsis string in the command tuple because tuples and strings
>     are both immutable. The list of args is extensible because it's a
>     list (and editing a list doens't change the tuple that contains
>     it). However, we are unable to add the new flags to the command
>     synopsis. This would allow us to do that.
>
>     I can update the commit message to include these reasons and send
>     out a V2 -- let me know.
>
>
> Instead of direct docstring manipulation, how about an API to add 
> extension-specific "sections" to the docstring. This could result in 
> something like the following, without concerns that extensions would 
> interfere with each other.
>
> hg push [-f] [-r REV]... [-e CMD] [--remotecmd CMD] [DEST]
>
> push changes to the specified destination
>
>     Push changesets from the local repository to the specified 
> destination.
>
>     ...
>
>     Returns 0 if push was successful, 1 if nothing to push.
>
>     pushrebase extension
>
>         pushrebase will enable "hg push" to automatically rebase 
> pushed changes on the server.
>
>     firefoxtree extension
>
>         firefoxtree changes the behavior of pushes to Firefox 
> repositories so the default push revision is ".". This will prevent
>         attempted pushes of multiple heads, which would only get 
> rejected due to a server-side hook.
>
> options ([+] can be repeated):
>
>  -f --force                 force push
>  -r --rev REV [+]           a changeset intended to be included in the
>
Note that this patch doesn't touch docstrings, only synopses, which are 
the shorter version of help.

However, you are right -- the "correct" way to do this is to introduce 
ways for extensions to more intelligently manipulate both the synopsis 
and the docstring, most likely through appending (but an argument might 
be made to allow other manipulations as well).

For now, appending will suffice for my needs, so I'll send out a series 
that enables appending only to both the synopsis and the docstring.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20150211/528af2fb/attachment.html>