Re: [PATCH 71/71] Change 'usually' to 'by default'

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Nov 25, 2014, 01:11 UTC
Message-ID: <CAPig+cQk-9VPAPxCUD+zz5AzNw=UfpgWGY3s6=32yKWXRMb3JQ@mail.gmail.com>
In-Reply-To: <1416863224-68392-1-git-send-email-richard.littauer@gmail.com>

On Mon, Nov 24, 2014 at 4:07 PM, Richard Littauer <richard.littauer@gmail.com> wrote:

Show 26 quoted lines

> I've been confused several times by the docs when running across
> the word 'usually'. It is difficult to know before hand if it
> means 'under normal conditions' or 'by default'. I've gone through
> the Documentation to identify specific cases where I think that 'by
> default' is more explanatory than 'usually'. I know that patches
> that touch too much code is unwelcome - as this is a small fix to
> very specific lines, I think this might be OK.
>
> For the majority of cases, usually works fine. However, especially
> for the docs concerning flags, it is good to know if 'usually' was
> just used by the documenter to mean 'unless your version has been
> exntensively modified' or if it mean "unless you've messed up."
> Hopefully, this isn't too pedantic.
>
> Signed-off-by: Richard Littauer <richard.littauer@gmail.com>
> ---
> diff --git a/Documentation/git-pack-refs.txt b/Documentation/git-pack-refs.txt
> index 154081f..c97e62a 100644
> --- a/Documentation/git-pack-refs.txt
> +++ b/Documentation/git-pack-refs.txt
> @@ -56,7 +56,7 @@ a repository with many branches of historical interests.
>
>  --no-prune::
>
> -The command usually removes loose refs under `$GIT_DIR/refs`
> +The command be default removes loose refs under `$GIT_DIR/refs`

s/be/by/

Show 13 quoted lines

>  hierarchy after packing them.  This option tells it not to.
>
>
> diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
> index ebe7a6c..dc07b64 100644
> --- a/Documentation/gitweb.conf.txt
> +++ b/Documentation/gitweb.conf.txt
> @@ -222,7 +222,7 @@ The values of these variables are paths on the filesystem.
>
>  $GIT::
>         Core git executable to use.  By default set to `$GIT_BINDIR/git`, which
> -       in turn is by default set to `$(bindir)/git`.  If you use Git installed
> +       in turn is defaulted to `$(bindir)/git`.  If you use Git installed

This would read better as:

    in turn defaults to ...

Show 13 quoted lines

>         from a binary package, you should usually set this to "/usr/bin/git".
>         This can just be "git" if your web server has a sensible PATH; from
>         security point of view it is better to use absolute path to git binary.
> @@ -633,10 +633,10 @@ override::
>         overridable, which means that it can be configured
>         (or enabled/disabled) on a per-repository basis.
>  +
> -Usually given "<feature>" is configurable via the `gitweb.<feature>`
> +Usually the given "<feature>" is configurable via the `gitweb.<feature>`
>  config variable in the per-repository Git configuration file.
>  +
> -*Note* that no feature is overridable by default.
> +*Note* that no feature is overridable usually.

This reads strangely and seems more ambiguous than the original text.

Show 16 quoted lines

>  sub::
>         Internal detail of implementation.  What is important is that
> diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt
> index 242a044..8c577ee 100644
> --- a/Documentation/technical/racy-git.txt
> +++ b/Documentation/technical/racy-git.txt
> @@ -38,10 +38,10 @@ files vs symbolic links) and executable bits (only for regular
>  files) from `st_mode` member, `st_mtime` and `st_ctime`
>  timestamps, `st_uid`, `st_gid`, `st_ino`, and `st_size` members.
>  With a `USE_STDEV` compile-time option, `st_dev` is also
> -compared, but this is not enabled by default because this member
> +compared, but this is not enabled usually because this member
>  is not stable on network filesystems.  With `USE_NSEC`
>  compile-time option, `st_mtim.tv_nsec` and `st_ctim.tv_nsec`
> -members are also compared, but this is not enabled by default
> +members are also compared, but this is not enabled usually

These reverse changes from "by default" to "usually" seem to make the text more ambiguous.

In fact, all the reverse changes from "by default" to "usually" throughout this patch make the text less clear. Your commit message does not explain this decision.

Show 12 quoted lines

>  because in-core timestamps can have finer granularity than
>  on-disk timestamps, resulting in meaningless changes when an
>  inode is evicted from the inode cache.  See commit 8ce13b0> diff --git a/gitweb/INSTALL b/gitweb/INSTALL
> index 408f285..23636b9 100644
> --- a/gitweb/INSTALL
> +++ b/gitweb/INSTALL
> @@ -140,7 +140,7 @@ You can specify the following configuration variables when building GIT:
>     gitweb.cgi script.  [No default]
>   * GITWEB_HOME_LINK_STR
>     String of the home link on top of all pages, leading to $home_link
> -   (usually main gitweb page, which means projects list).  Used as first
> +   (by default main gitweb page, which means projects list).  Used as first

In an earlier change in this patch, you inserted the word "the" to improve grammar. Such a change could be applied here:

   (by default, the main ...

>     part of gitweb view "breadcrumb trail": <home> / <project> / <view>.
>     [Default: projects]
>   * GITWEB_SITENAME