[PATCH] Documentation: make formatting more consistent

[PATCH] Documentation: make formatting more consistent

[Андрей Рыбак]

Documentation/git.txt: enclose all Environment Variables in single quotes.

Signed-off-by: Andrey Rybak <rybak.a.v@gmail.com>
---
Documentation/git.txt is not consistent in the way it stylizes mentions
of Environment Variables. Most of them are enclosed in single quotes,
some are enclosed in backticks, some are not enclosed.

 Documentation/git.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index c2e2a94..900272b 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -1056,7 +1056,7 @@ of clones and fetches.
  cloning of shallow repositories.
  See 'GIT_TRACE' for available trace output options.

-GIT_LITERAL_PATHSPECS::
+'GIT_LITERAL_PATHSPECS'::
  Setting this variable to `1` will cause Git to treat all
  pathspecs literally, rather than as glob patterns. For example,
  running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
@@ -1065,15 +1065,15 @@ GIT_LITERAL_PATHSPECS::
  literal paths to Git (e.g., paths previously given to you by
  `git ls-tree`, `--raw` diff output, etc).

-GIT_GLOB_PATHSPECS::
+'GIT_GLOB_PATHSPECS'::
  Setting this variable to `1` will cause Git to treat all
  pathspecs as glob patterns (aka "glob" magic).

-GIT_NOGLOB_PATHSPECS::
+'GIT_NOGLOB_PATHSPECS'::
  Setting this variable to `1` will cause Git to treat all
  pathspecs as literal (aka "literal" magic).

-GIT_ICASE_PATHSPECS::
+'GIT_ICASE_PATHSPECS'::
  Setting this variable to `1` will cause Git to treat all
  pathspecs as case-insensitive.

@@ -1087,7 +1087,7 @@ GIT_ICASE_PATHSPECS::
  variable when it is invoked as the top level command by the
  end user, to be recorded in the body of the reflog.

-`GIT_REF_PARANOIA`::
+'GIT_REF_PARANOIA'::
  If set to `1`, include broken or badly named refs when iterating
  over lists of refs. In a normal, non-corrupted repository, this
  does nothing. However, enabling it may help git to detect and
@@ -1098,7 +1098,7 @@ GIT_ICASE_PATHSPECS::
  an operation has touched every ref (e.g., because you are
  cloning a repository to make a backup).

-`GIT_ALLOW_PROTOCOL`::
+'GIT_ALLOW_PROTOCOL'::
  If set, provide a colon-separated list of protocols which are
  allowed to be used with fetch/push/clone. This is useful to
  restrict recursive submodule initialization from an untrusted
-- 
2.5.3.windows.1

Re: [PATCH] Documentation: make formatting more consistent

[Jeff King]

On Wed, Nov 11, 2015 at 06:47:25PM +0300, Андрей Рыбак wrote:

> Documentation/git.txt: enclose all Environment Variables in single quotes.

This tells "what", but we can already see that from the diff. The more
interesting part is "why". Later you say:

> Signed-off-by: Andrey Rybak <rybak.a.v@gmail.com>
> ---
> Documentation/git.txt is not consistent in the way it stylizes mentions
> of Environment Variables. Most of them are enclosed in single quotes,
> some are enclosed in backticks, some are not enclosed.

which I think is the more interesting bit, and should go into the commit
message (but parts after the "---" generally do not). I've grabbed it
manually in this case.

I know we've discussed this particular spot before, and I think there
may have been some disagreement about which style was the best. But
since clearly no patch came out of the last discussion, and since
an inconsistent set of styles is probably worse than consistent use of
any of the choices, this makes sense to me as an incremental step.

If we want to move to all-backticks (for example) later on, we can
easily do so (or we can leave this as the final state).

> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index c2e2a94..900272b 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -1056,7 +1056,7 @@ of clones and fetches.
>   cloning of shallow repositories.
>   See 'GIT_TRACE' for available trace output options.

Your patch seems whitespace-damaged (the leading tabs were converted to
spaces). It was pretty easy to fix up in this case, so I did so (i.e.,
no need to re-send), but please check your mailer settings.

Thanks.

-Peff

Re: [PATCH] Documentation: make formatting more consistent

[Jeff King]

On Wed, Nov 11, 2015 at 04:41:06PM -0500, Jeff King wrote:

> I know we've discussed this particular spot before, and I think there
> may have been some disagreement about which style was the best. But
> since clearly no patch came out of the last discussion, and since
> an inconsistent set of styles is probably worse than consistent use of
> any of the choices, this makes sense to me as an incremental step.
> 
> If we want to move to all-backticks (for example) later on, we can
> easily do so (or we can leave this as the final state).

Andrey helpfully dug up that thread off-list:

  http://thread.gmane.org/gmane.comp.version-control.git/267990/

If we want to move to backticks, we probably want to also turn on
MAN_BOLD_LITERAL by default, or it's a step backwards for some folks.

As I was the person who suggested backticks back in that thread, and I
do not want to spend the time myself on figuring out if MAN_BOLD_LITERAL
is safe to use everywhere, I somewhat retract my suggestion.

I've queued this patch as-is for now, but I'd be happy to hear other
opinions, or if people want to dig into the MAN_BOLD_LITERAL thing.

-Peff