[PATCH 3 of 5] extensions: improve the consistency of synopses

[Dirkjan Ochtman]

Okay, so I have some comments here... Sorry for the bikeshedding.

First, why are we wrapping everything at 70 chars? It makes comments
require more lines in the code, and it looks stupid in a
defaulting-to-80 terminal. For example, this means the description
line for share and zeroconf wrap to the next line when they really
don't need to, which looks ugly and feels stupid.

Second, while consistency is obviously a good thing, I'm not happy
with some of these changes. I also feel the scheme here (present tense
predicate, direct object) is not optimal in a bunch of cases. This
stems partly, I believe, from the fact that the description line
follows the extension name, which means a third-person verb form would
feel more natural here. Instead, the predicate now feels like a
commanding form. Another problem I have with this is that the
extensions themselves aren't consistent in what they do, so making
their descriptions consistent doesn't help in describing what they do.

Summarizing comments below:

- Providing hooks to do something does not equal doing that
- Providing commands to do something does not equal doing that, either
- Making non-obvious dependencies explicit is a good thing

Cheers,

Dirkjan

2009/6/22 Cédric Duval <cedricduval at free.fr>:
> # HG changeset patch
> # User Cédric Duval <cedricduval at free.fr>
> # Date 1245678488 -7200
> # Node ID b2f810ac55b0bfd0675fc4f9a9c6403a7d8144a6
> # Parent  ec27e54f7a93f73a10985869ccbb3c71f95bccc7
> extensions: improve the consistency of synopses
>
> Trying as much as possible to consistently:
>  - use a present tense predicate followed by a direct object
>  - verb referring directly to the functionality provided
>   (ie. not "add command that does this" but simple "do that")
>  - keep simple and to the point, leaving details for the long help
>   (width is tight, possibly even more so for translations)
>
> Thanks to timeless, Martin Geisler, Rafael Villar Burke, Dan Villiom
> Podlaski Christiansen and others for the helpful suggestions.
>
> diff --git a/hgext/acl.py b/hgext/acl.py
> --- a/hgext/acl.py
> +++ b/hgext/acl.py
> @@ -6,7 +6,7 @@
>  # GNU General Public License version 2, incorporated herein by reference.
>  #
>
> -'''provide simple hooks for access control
> +'''control access to a repository using simple hooks

The extension doesn't control access. Instead, it provides
functionality to implement access control, which is very different.
ISTR timeless didn't like "provide", but I'm not sure why.

>  This hook makes it possible to allow or deny write access to portions
>  of a repository when receiving incoming changesets.
> diff --git a/hgext/bookmarks.py b/hgext/bookmarks.py
> --- a/hgext/bookmarks.py
> +++ b/hgext/bookmarks.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''Mercurial bookmarks
> +'''track a line of development with movable markers
>
>  Bookmarks are local movable markers to changesets. Every bookmark
>  points to a changeset identified by its hash. If you commit a
> @@ -122,7 +122,7 @@
>     repo._bookmarkcurrent = mark
>
>  def bookmark(ui, repo, mark=None, rev=None, force=False, delete=False, rename=None):
> -    '''Mercurial bookmarks
> +    '''track a line of development with movable markers
>
>     Bookmarks are pointers to certain commits that move when
>     committing. Bookmarks are local. They can be renamed, copied and
> diff --git a/hgext/bugzilla.py b/hgext/bugzilla.py
> --- a/hgext/bugzilla.py
> +++ b/hgext/bugzilla.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''Bugzilla integration
> +'''integrate Mercurial with a Bugzilla bug tracker
>
>  This hook extension adds comments on bugs in Bugzilla when changesets
>  that refer to bugs by Bugzilla ID are seen. The hook does not change
> diff --git a/hgext/children.py b/hgext/children.py
> --- a/hgext/children.py
> +++ b/hgext/children.py
> @@ -8,7 +8,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''provides children command to show children changesets'''
> +'''display children changesets'''

This does not change display modes for any existing commands or pages
so that children are shown, which this seems to imply. Instead, it
adds a command to allow you to see children csets.

>
>  from mercurial import cmdutil
>  from mercurial.commands import templateopts
> diff --git a/hgext/churn.py b/hgext/churn.py
> --- a/hgext/churn.py
> +++ b/hgext/churn.py
> @@ -6,7 +6,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''command to show certain statistics about revision history'''
> +'''display statistics about repository history'''

Similar to children, this does add statistics output to any existing
form of output.

>
>  from mercurial.i18n import _
>  from mercurial import patch, cmdutil, util, templater
> diff --git a/hgext/color.py b/hgext/color.py
> --- a/hgext/color.py
> +++ b/hgext/color.py
> @@ -16,7 +16,7 @@
>  # with this program; if not, write to the Free Software Foundation, Inc.,
>  # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
>
> -'''add color output to status, qseries, and diff-related commands
> +'''colorize output from some commands
>
>  This extension modifies the status command to add color to its output
>  to reflect file status, the qseries command to add color to reflect
> diff --git a/hgext/convert/__init__.py b/hgext/convert/__init__.py
> --- a/hgext/convert/__init__.py
> +++ b/hgext/convert/__init__.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''converting foreign VCS repositories to Mercurial'''
> +'''import from foreign VCS repositories into Mercurial'''

This does away with the object, which seems suboptimal. Should be
"import revisions ...", IMO.

>
>  import convcmd
>  import cvsps
> diff --git a/hgext/fetch.py b/hgext/fetch.py
> --- a/hgext/fetch.py
> +++ b/hgext/fetch.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''pulling, updating and merging in one command'''
> +'''pull, update and merge in one command'''
>
>  from mercurial.i18n import _
>  from mercurial.node import nullid, short
> diff --git a/hgext/gpg.py b/hgext/gpg.py
> --- a/hgext/gpg.py
> +++ b/hgext/gpg.py
> @@ -3,7 +3,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''GnuPG signing extension for Mercurial'''
> +'''sign and verify changesets'''

Again, this does not sign and verify your changesets by default, it
provides functionality to help you do so.

>
>  import os, tempfile, binascii
>  from mercurial import util, commands, match
> diff --git a/hgext/graphlog.py b/hgext/graphlog.py
> --- a/hgext/graphlog.py
> +++ b/hgext/graphlog.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''show revision graphs in terminal windows
> +'''show revision graphs in terminals

I feel like terminal is a UNIXism and "command line" or something like
that would be better here.

>
>  This extension adds a --graph option to the incoming, outgoing and log
>  commands. When this options is given, an ASCII representation of the
> diff --git a/hgext/hgcia.py b/hgext/hgcia.py
> --- a/hgext/hgcia.py
> +++ b/hgext/hgcia.py
> @@ -1,7 +1,7 @@
>  # Copyright (C) 2007-8 Brendan Cully <brendan at kublai.com>
>  # Published under the GNU GPL
>
> -"""CIA notification
> +"""integrate Mercurial with a CIA notification service

This doesn't integrate, it provides hooks to enable integration.

>
>  This is meant to be run as a changegroup or incoming hook.
>  To configure it, set the following options in your hgrc:
> diff --git a/hgext/hgk.py b/hgext/hgk.py
> --- a/hgext/hgk.py
> +++ b/hgext/hgk.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''browsing the repository in a graphical way
> +'''browse the repository in a graphical way
>
>  The hgk extension allows browsing the history of a repository in a
>  graphical way. It requires Tcl/Tk version 8.4 or later. (Tcl/Tk is not
> diff --git a/hgext/highlight/__init__.py b/hgext/highlight/__init__.py
> --- a/hgext/highlight/__init__.py
> +++ b/hgext/highlight/__init__.py
> @@ -8,7 +8,7 @@
>  # The original module was split in an interface and an implementation
>  # file to defer pygments loading and speedup extension setup.
>
> -"""syntax highlighting in hgweb, based on Pygments
> +"""syntax highlighting for hgweb

Does away with an external dependency. Since this is one of a few
extensions requiring a dependency and it's not entirely obvious, I
don't think that's a good idea. I'd propose to add "(requires
Pygments)" again.

>
>  It depends on the Pygments syntax highlighting library:
>  http://pygments.org/
> diff --git a/hgext/inotify/__init__.py b/hgext/inotify/__init__.py
> --- a/hgext/inotify/__init__.py
> +++ b/hgext/inotify/__init__.py
> @@ -6,8 +6,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''inotify-based status acceleration for Linux systems
> -'''
> +'''accelerate status report using system level services'''

Again, this is still Linux-only for now, so I think "using system
level services" (which I think requires a hypen between system and
level, anyway) should be replaced by "Linux's inotify service".

>
>  # todo: socket permissions
>
> diff --git a/hgext/keyword.py b/hgext/keyword.py
> --- a/hgext/keyword.py
> +++ b/hgext/keyword.py
> @@ -26,7 +26,7 @@
>  #
>  # Run "hg help keyword" and "hg kwdemo" to get info on configuration.
>
> -'''keyword expansion in tracked files
> +'''expand keywords in tracked files

I feel like "expands" would be better than "expand" here.

>
>  This extension expands RCS/CVS-like or self-customized $Keywords$ in
>  tracked text files selected by your configuration.
> diff --git a/hgext/mq.py b/hgext/mq.py
> --- a/hgext/mq.py
> +++ b/hgext/mq.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''patch management and development
> +'''work with a stack of patches

I think "work with" is much vaguer than "management and development".
I'd propose "manage a stack of patches".

>
>  This extension lets you work with a stack of patches in a Mercurial
>  repository. It manages two stacks of patches - all known patches, and
> diff --git a/hgext/notify.py b/hgext/notify.py
> --- a/hgext/notify.py
> +++ b/hgext/notify.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''hook extension to email notifications on commits/pushes
> +'''send e-mail notifications for commits/pushes

Again, it doesn't. It only provides hooks to set something like that up.

>
>  Subscriptions can be managed through hgrc. Default mode is to print
>  messages to stdout, for testing and configuring.
> diff --git a/hgext/pager.py b/hgext/pager.py
> --- a/hgext/pager.py
> +++ b/hgext/pager.py
> @@ -12,7 +12,7 @@
>  #
>  # Run "hg help pager" to get info on configuration.
>
> -'''browse command output with external pager
> +'''browse command output with an external pager
>
>  To set the pager that should be used, set the application variable:
>
> diff --git a/hgext/parentrevspec.py b/hgext/parentrevspec.py
> --- a/hgext/parentrevspec.py
> +++ b/hgext/parentrevspec.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''use suffixes to refer to ancestor revisions
> +'''interpret suffixes to refer to ancestor revisions

"interprets" would feel better here, I think.

>
>  This extension allows you to use git-style suffixes to refer to the
>  ancestors of a specific revision.
> diff --git a/hgext/patchbomb.py b/hgext/patchbomb.py
> --- a/hgext/patchbomb.py
> +++ b/hgext/patchbomb.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''sending Mercurial changesets as a series of patch emails
> +'''send Mercurial changesets as a series of patch e-mails

It doesn't, it just adds a command.

>
>  The series is started off with a "[PATCH 0 of N]" introduction, which
>  describes the series as a whole.
> diff --git a/hgext/purge.py b/hgext/purge.py
> --- a/hgext/purge.py
> +++ b/hgext/purge.py
> @@ -23,7 +23,7 @@
>  # along with this program; if not, write to the Free Software
>  # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
>
> -'''enable removing untracked files only'''
> +'''delete files not tracked from the working directory'''

"files not tracked" would be better as "untracked files". Also just
provides a command.

>
>  from mercurial import util, commands, cmdutil
>  from mercurial.i18n import _
> diff --git a/hgext/record.py b/hgext/record.py
> --- a/hgext/record.py
> +++ b/hgext/record.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''interactive change selection during commit or qrefresh'''
> +'''interactively select which sets of changes to commit/qrefresh'''

Just a command.

>
>  from mercurial.i18n import gettext, _
>  from mercurial import cmdutil, commands, extensions, hg, mdiff, patch
> diff --git a/hgext/share.py b/hgext/share.py
> --- a/hgext/share.py
> +++ b/hgext/share.py
> @@ -3,7 +3,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''provides the hg share command'''
> +'''share a common history between several working directories'''

Just a command.

>
>  import os
>  from mercurial.i18n import _
> diff --git a/hgext/transplant.py b/hgext/transplant.py
> --- a/hgext/transplant.py
> +++ b/hgext/transplant.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''patch transplanting tool
> +'''transplant changesets from another branch

Just a command.

>
>  This extension allows you to transplant patches from another branch.
>
> diff --git a/hgext/win32mbcs.py b/hgext/win32mbcs.py
> --- a/hgext/win32mbcs.py
> +++ b/hgext/win32mbcs.py
> @@ -9,7 +9,7 @@
>  # GNU General Public License version 2, incorporated herein by reference.
>  #
>
> -"""allow to use MBCS path with problematic encoding.
> +'''allow the use of MBCS paths with problematic encoding

Shouldn't encodings be a plural form here?

>
>  Some MBCS encodings are not good for some path operations (i.e.
>  splitting path, case conversion, etc.) with its encoded bytes. We call
> @@ -36,8 +36,7 @@
>  Path encoding conversion are done between Unicode and
>  encoding.encoding which is decided by Mercurial from current locale
>  setting or HGENCODING.
> -
> -"""
> +'''
>
>  import os
>  from mercurial.i18n import _
> diff --git a/hgext/win32text.py b/hgext/win32text.py
> --- a/hgext/win32text.py
> +++ b/hgext/win32text.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''LF <-> CRLF/CR translation utilities
> +'''perform automatic newline conversion

Active form -> "performs"?

>
>  To perform automatic newline conversion, use:
>
> diff --git a/hgext/zeroconf/__init__.py b/hgext/zeroconf/__init__.py
> --- a/hgext/zeroconf/__init__.py
> +++ b/hgext/zeroconf/__init__.py
> @@ -5,7 +5,7 @@
>  # This software may be used and distributed according to the terms of the
>  # GNU General Public License version 2, incorporated herein by reference.
>
> -'''zeroconf support for Mercurial repositories
> +'''discover and advertise repositories on the local network

This fails to convey how this is done, which I think is very relevant here.

>
>  Zeroconf enabled repositories will be announced in a network without
>  the need to configure a server or a service. They can be discovered
> diff --git a/tests/test-keyword.out b/tests/test-keyword.out
> --- a/tests/test-keyword.out
> +++ b/tests/test-keyword.out
> @@ -1,5 +1,5 @@
>  % help
> -keyword extension - keyword expansion in tracked files
> +keyword extension - expand keywords in tracked files
>
>  This extension expands RCS/CVS-like or self-customized $Keywords$ in
>  tracked text files selected by your configuration.
> @@ -55,9 +55,9 @@
>
>  enabled extensions:
>
> - keyword   keyword expansion in tracked files
> - mq        patch management and development
> - notify    hook extension to email notifications on commits/pushes
> + keyword   expand keywords in tracked files
> + mq        work with a stack of patches
> + notify    send e-mail notifications for commits/pushes
>
>  use "hg -v help keyword" to show aliases and global options
>  % hg kwdemo
> diff --git a/tests/test-mq.out b/tests/test-mq.out
> --- a/tests/test-mq.out
> +++ b/tests/test-mq.out
> @@ -1,5 +1,5 @@
>  % help
> -mq extension - patch management and development
> +mq extension - work with a stack of patches
>
>  This extension lets you work with a stack of patches in a Mercurial
>  repository. It manages two stacks of patches - all known patches, and
> @@ -53,7 +53,7 @@
>
>  enabled extensions:
>
> - mq   patch management and development
> + mq   work with a stack of patches
>
>  use "hg -v help mq" to show aliases and global options
>  adding a
> diff --git a/tests/test-notify.out b/tests/test-notify.out
> --- a/tests/test-notify.out
> +++ b/tests/test-notify.out
> @@ -1,4 +1,4 @@
> -notify extension - hook extension to email notifications on commits/pushes
> +notify extension - send e-mail notifications for commits/pushes
>
>  Subscriptions can be managed through hgrc. Default mode is to print
>  messages to stdout, for testing and configuring.
>
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel
>