[PATCH RFC stable] help: refer to user configuration file as hg configuration file

Brodie Rao brodie at bitheap.org
Wed Sep 1 10:51:35 CDT 2010


On Sep 1, 2010, at 3:12 AM, timeless wrote:

> Sorry, I was away for a longish weekend (and am shortly going to be
> away for much longer).
>
> My original comment from my mail backlog on this subject was (unsent
> since I wanted to see what happened before sending it):
>
> On Thu, Aug 26, 2010 at 11:00 AM, Martin Geisler <mg at lazybytes.net>  
> wrote:
>> "please specify your commit editor/username in your configuration  
>> file"
>
> in your _hg_ configuration file.
>
> The reason to use "hg configuration file" instead of "configuration
> file" is this pair of lines from contrib/pylintrc:
> # Specify a configuration file.
> #rcfile=
>
> Not all "configuration file"s in the codebase are hg configuration
> files. And similarly, googling for "configuration file" is not going
> to do anyone any good:
> http://www.google.com/search?q=%22configuration+file%22

Seems reasonable to me.

Though I do feel now that maybe it would be simpler and more  
consistent to just go with "hgrc". Not "$HOME/.hgrc", not "~/.hgrc",  
not ".hgrc" - just "hgrc". We wouldn't really be referring to any  
particular file path, just the general concept of hgrc. And it  
corresponds to the hgrc(5) man page.

> Note that I've intentionally force wrapped <hg configuration file>,
> while it's certainly technically wrong, i think it's somewhat
> important to somehow hint to people reading the code that the three
> words are essentially a technical term. This should also apply to
> localizers. I have no idea how to properly hint that. If we were using
> a markup based language, one would obviously mark up the string. The
> key is that localizers (and coders and those who might want to make
> later changes) need to understand that this triple should be
> consistently translated instead of merely free-translated. It's
> possible that none of the translators we have will make a mistake in a
> thing like this. However, I work in a commercial world where such
> mistakes are to be expected. (I also work in a number of open source
> projects where translators aren't perfect, my goal is to help
> translators avoid pitfalls.)

I'm not sure what you mean by forced wrapping being wrong. Are you  
suggesting that newlines should never be inserted between the three  
words?

On the other hand, you could mark it up in the man page, and if it  
were just "hgrc", then it'd be obvious that it's associated with hgrc 
(5) and that you should look there for more info. You'd also avoid the  
translation issue with "hgrc" (though I think "hgrc configuration  
file" would be nice for longer/more in-depth docs).

> # HG changeset patch
> # User timeless <timeless at gmail.com>
> # Date 1283325057 -10800
> # Node ID 4bff50a7f7f1fdaadee77d28731c406816ed7ea6
> # Parent  4b9cec10330e6892bf7f85dec89374d829d46ae2
> help: refer to user configuration file as hg configuration file
>
> diff --git a/mercurial/commands.py b/mercurial/commands.py
> --- a/mercurial/commands.py
> +++ b/mercurial/commands.py
> @@ -1335,8 +1335,8 @@ def debuginstall(ui):
>     if patchproblems:
>         if ui.config('ui', 'patch'):
>             ui.write(_(" (Current patch tool may be incompatible  
> with patch,"
> -                       " or misconfigured. Please check your  
> configuration"
> -                       " file)\n"))
> +                       " or misconfigured. Please check your"
> +                       " hg configuration file)\n"))
>         else:
>             ui.write(_(" Internal patcher failure, please report  
> this error"
>                        " to http://mercurial.selenic.com/bts/\n"))
> @@ -1352,12 +1352,12 @@ def debuginstall(ui):
>     if not cmdpath:
>         if editor == 'vi':
>             ui.write(_(" No commit editor set and can't find vi in  
> PATH\n"))
> -            ui.write(_(" (specify a commit editor in your  
> configuration"
> -                       " file)\n"))
> +            ui.write(_(" (specify a commit editor in your"
> +                       " hg configuration file)\n"))
>         else:
>             ui.write(_(" Can't find editor '%s' in PATH\n") % editor)
> -            ui.write(_(" (specify a commit editor in your  
> configuration"
> -                       " file)\n"))
> +            ui.write(_(" (specify a commit editor in your"
> +                       " hg configuration file)\n"))
>             problems += 1
>
>     # check username
> @@ -1366,7 +1366,7 @@ def debuginstall(ui):
>         ui.username()
>     except util.Abort, e:
>         ui.write(" %s\n" % e)
> -        ui.write(_(" (specify a username in your configuration file) 
> \n"))
> +        ui.write(_(" (specify a username in your hg configuration  
> file)\n"))
>         problems += 1
>
>     if not problems:
> @@ -2728,8 +2728,8 @@ def paths(ui, repo, search=None):
>     show definition of all available names.
>
>     Path names are defined in the [paths] section of your
> -    configuration file and in ``/etc/mercurial/hgrc``. If run  
> inside a
> -    repository, ``.hg/hgrc`` is used, too.
> +    hg configuration file and in ``/etc/mercurial/hgrc``. If run  
> inside
> +    a repository, ``.hg/hgrc`` is used, too.
>
>     The path names ``default`` and ``default-push`` have a special
>     meaning.  When performing a push or pull operation, they are used
> diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt
> --- a/mercurial/help/config.txt
> +++ b/mercurial/help/config.txt
> @@ -1,7 +1,7 @@
> Mercurial reads configuration data from several files, if they exist.
> Below we list the most specific file first.
>
> -On Windows, these configuration files are read:
> +On Windows, these hg configuration files are read:
>
> - ``<repo>\.hg\hgrc``
> - ``%USERPROFILE%\.hgrc``
> @@ -22,7 +22,7 @@ On Unix, these files are read:
> - ``<install-root>/etc/mercurial/hgrc``
> - ``<install-root>/etc/mercurial/hgrc.d/*.rc``
>
> -If there is a per-repository configuration file which is not owned by
> +If there is a per-repository hg configuration file which is not  
> owned by
> the active user, Mercurial will warn you that the file is skipped::
>
>   not trusting file <repo>/.hg/hgrc from untrusted user USER, group  
> GROUP
> @@ -35,8 +35,8 @@ settings, the syntax is explained below:
> - ``trusted.users = USER``
> - ``trusted.groups = GROUP``
>
> -The configuration files for Mercurial use a simple ini-file format. A
> -configuration file consists of sections, led by a ``[section]``  
> header
> +The hg configuration files for Mercurial use a simple ini-file  
> format. A
> +hg configuration file consists of sections, led by a ``[section]``  
> header
> and followed by ``name = value`` entries::
>
>   [ui]
> diff --git a/mercurial/help/diffs.txt b/mercurial/help/diffs.txt
> --- a/mercurial/help/diffs.txt
> +++ b/mercurial/help/diffs.txt
> @@ -25,5 +25,5 @@ format for communicating changes.
>
> To make Mercurial produce the git extended diff format, use the --git
> option available for many commands, or set 'git = True' in the [diff]
> -section of your configuration file. You do not need to set this  
> option
> +section of your hg configuration file. You do not need to set this  
> option
> when importing diffs in this format or using them in the mq extension.
> diff --git a/mercurial/help/environment.txt b/mercurial/help/ 
> environment.txt
> --- a/mercurial/help/environment.txt
> +++ b/mercurial/help/environment.txt
> @@ -8,7 +8,7 @@ HG
> HGEDITOR
>     This is the name of the editor to run when committing. See EDITOR.
>
> -    (deprecated, use configuration file)
> +    (deprecated, use hg configuration file)
>
> HGENCODING
>     This overrides the default locale setting detected by Mercurial.
> @@ -29,13 +29,14 @@ HGMERGE
>     will be executed with three arguments: local file, remote file,
>     ancestor file.
>
> -    (deprecated, use configuration file)
> +    (deprecated, use hg configuration file)
>
> HGRCPATH
> -    A list of files or directories to search for configuration
> -    files. Item separator is ":" on Unix, ";" on Windows. If HGRCPATH
> -    is not set, platform default search path is used. If empty, only
> -    the .hg/hgrc from the current repository is read.
> +    A list of files or directories to search for
> +    hg configuration files. Item separator is ":" on Unix, ";" on
> +    Windows. If HGRCPATH is not set, platform default search path is
> +    used. If empty, only the .hg/hgrc from the current repository is
> +    read.
>
>     For each element in HGRCPATH:
>
> @@ -57,12 +58,12 @@ HGUSER
>     available values will be considered in this order:
>
>     - HGUSER (deprecated)
> -    - configuration files from the HGRCPATH
> +    - hg configuration files from the HGRCPATH
>     - EMAIL
>     - interactive prompt
>     - LOGNAME (with ``@hostname`` appended)
>
> -    (deprecated, use configuration file)
> +    (deprecated, use hg configuration file)
>
> EMAIL
>     May be used as the author of a commit; see HGUSER.
> diff --git a/mercurial/help/extensions.txt b/mercurial/help/ 
> extensions.txt
> --- a/mercurial/help/extensions.txt
> +++ b/mercurial/help/extensions.txt
> @@ -12,8 +12,8 @@ Mercurial. It is thus up to the user to
> needed.
>
> To enable the "foo" extension, either shipped with Mercurial or in the
> -Python search path, create an entry for it in your configuration  
> file,
> -like this::
> +Python search path, create an entry for it in your
> +hg configuration file, like this::
>
>   [extensions]
>   foo =
> @@ -23,8 +23,8 @@ You may also specify the full path to an
>   [extensions]
>   myfeature = ~/.hgext/myfeature.py
>
> -To explicitly disable an extension enabled in a configuration file of
> -broader scope, prepend its path with !::
> +To explicitly disable an extension enabled in a
> +hg configuration file of broader scope, prepend its path with !::
>
>   [extensions]
>   # disabling extension bar residing in /path/to/extension/bar.py
> diff --git a/mercurial/help/hgweb.txt b/mercurial/help/hgweb.txt
> --- a/mercurial/help/hgweb.txt
> +++ b/mercurial/help/hgweb.txt
> @@ -1,9 +1,9 @@
> Mercurial's internal web server, hgweb, can serve either a single
> repository, or a collection of them. In the latter case, a special
> -configuration file can be used to specify the repository paths to use
> +hg configuration file can be used to specify the repository paths  
> to use
> and global web configuration options.
>
> -This file uses the same syntax as hgrc configuration files, but only
> +This file uses the same syntax as hgrc hg configuration files, but  
> only

"hgrc hg configuration files" doesn't look right to me.

> the following sections are recognized:
>
>   - web
> diff --git a/mercurial/help/urls.txt b/mercurial/help/urls.txt
> --- a/mercurial/help/urls.txt
> +++ b/mercurial/help/urls.txt
> @@ -36,9 +36,9 @@ Some notes about using SSH with Mercuria
>       Compression yes
>
>   Alternatively specify "ssh -C" as your ssh command in your
> -  configuration file or with the --ssh command line option.
> +  hg configuration file or with the --ssh command line option.
>
> -These URLs can all be stored in your configuration file with path
> +These URLs can all be stored in your hg configuration file with path
> aliases under the [paths] section like so::
>
>   [paths]
> diff --git a/tests/test-install.t b/tests/test-install.t
> --- a/tests/test-install.t
> +++ b/tests/test-install.t
> @@ -17,7 +17,7 @@ hg debuginstall with no username
>   Checking commit editor...
>   Checking username...
>    no username supplied (see "hg help config")
> -   (specify a username in your configuration file)
> +   (specify a username in your hg configuration file)
>   1 problems detected, please check your install!
>
>   $ true



More information about the Mercurial-devel mailing list