[PATCH] Documentation: fix --color option formatting

[PATCH] Documentation: fix --color option formatting

[Andrei Rybak]

Add missing colon in two places to fix formatting of options.

Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
---

Done on top of maint.

The earliest this patch applies is on top of commit aebd23506e ("Merge
branch 'jk/ui-color-always-to-auto-maint' into
jk/ui-color-always-to-auto", 2017-10-04), one commit away from the
commit that added both of the affected lines: 0c88bf5050 (provide
--color option for all ref-filter users, 2017-10-03).

I grepped the Documentation folder, and haven't found any other
similar typos.

---

 Documentation/git-for-each-ref.txt | 2 +-
 Documentation/git-tag.txt          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 085d177d97..901faef1bf 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -57,7 +57,7 @@ OPTIONS
 	`xx`; for example `%00` interpolates to `\0` (NUL),
 	`%09` to `\t` (TAB) and `%0a` to `\n` (LF).
 
---color[=<when>]:
+--color[=<when>]::
 	Respect any colors specified in the `--format` option. The
 	`<when>` field must be one of `always`, `never`, or `auto` (if
 	`<when>` is absent, behave as if `always` was given).
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 87c4288ffc..92f9c12b87 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -115,7 +115,7 @@ options for details.
 	variable if it exists, or lexicographic order otherwise. See
 	linkgit:git-config[1].
 
---color[=<when>]:
+--color[=<when>]::
 	Respect any colors specified in the `--format` option. The
 	`<when>` field must be one of `always`, `never`, or `auto` (if
 	`<when>` is absent, behave as if `always` was given).
-- 
2.18.0

Re: [PATCH] Documentation: fix --color option formatting

[Jeff King]

On Wed, Jul 18, 2018 at 07:37:48PM +0200, Andrei Rybak wrote:

> Add missing colon in two places to fix formatting of options.

Thanks for catching.

> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> index 085d177d97..901faef1bf 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -57,7 +57,7 @@ OPTIONS
>  	`xx`; for example `%00` interpolates to `\0` (NUL),
>  	`%09` to `\t` (TAB) and `%0a` to `\n` (LF).
>  
> ---color[=<when>]:
> +--color[=<when>]::
>  	Respect any colors specified in the `--format` option. The
>  	`<when>` field must be one of `always`, `never`, or `auto` (if
>  	`<when>` is absent, behave as if `always` was given).

This is obviously the right fix.

I am guilty of not always building the documentation and eye-balling the
output when I'm not specifically changing the formatting. I wonder if we
could provide tooling to make that easier, by showing a diff between the
text-formatted manpages before and after a series. I've manually hacked
stuff up like that in the past, but there's often a lot of noise around
date and version info in the footers.

-Peff

Re: [PATCH] Documentation: fix --color option formatting

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1604 bytes --]

On Wed, Jul 18, 2018 at 01:49:44PM -0400, Jeff King wrote:
> On Wed, Jul 18, 2018 at 07:37:48PM +0200, Andrei Rybak wrote:
> > diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> > index 085d177d97..901faef1bf 100644
> > --- a/Documentation/git-for-each-ref.txt
> > +++ b/Documentation/git-for-each-ref.txt
> > @@ -57,7 +57,7 @@ OPTIONS
> >  	`xx`; for example `%00` interpolates to `\0` (NUL),
> >  	`%09` to `\t` (TAB) and `%0a` to `\n` (LF).
> >  
> > ---color[=<when>]:
> > +--color[=<when>]::
> >  	Respect any colors specified in the `--format` option. The
> >  	`<when>` field must be one of `always`, `never`, or `auto` (if
> >  	`<when>` is absent, behave as if `always` was given).
> 
> This is obviously the right fix.
> 
> I am guilty of not always building the documentation and eye-balling the
> output when I'm not specifically changing the formatting. I wonder if we
> could provide tooling to make that easier, by showing a diff between the
> text-formatted manpages before and after a series. I've manually hacked
> stuff up like that in the past, but there's often a lot of noise around
> date and version info in the footers.

Both AsciiDoc 8.6.10 and Asciidoctor support SOURCE_DATE_EPOCH for
reproducible builds[0], which should reduce the date noise.  We could
also add a Makefile knob to set git_version to an empty string or an
--abbrev=0 equivalent for such a situation.

[0] https://reproducible-builds.org/specs/source-date-epoch/
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 867 bytes --]

Re: [PATCH] Documentation: fix --color option formatting

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> Both AsciiDoc 8.6.10 and Asciidoctor support SOURCE_DATE_EPOCH for
> reproducible builds[0], which should reduce the date noise.  We could
> also add a Makefile knob to set git_version to an empty string or an
> --abbrev=0 equivalent for such a situation.
>
> [0] https://reproducible-builds.org/specs/source-date-epoch/

I probably should take advantage of this feature and update the
install target of Documentation/Makefile, where I manually filter
out these noise changes between what is installed and what is going
to be.  That serves as my final sanity check before pushing out the
result of an integration cycle that updates the 'master' branch, as
that is when the pre-formatted html and man pages are updated, and
as part of that, "make install" for these two formats are run to
give me a chance to eyeball the differences.

Being able to lose the (impricise) manual filtering would be great.

Re: [PATCH] Documentation: fix --color option formatting

[Junio C Hamano]

Andrei Rybak <rybak.a.v@gmail.com> writes:

> Add missing colon in two places to fix formatting of options.
>
> Signed-off-by: Andrei Rybak <rybak.a.v@gmail.com>
> ---
>
> Done on top of maint.
>
> The earliest this patch applies is on top of commit aebd23506e ("Merge
> branch 'jk/ui-color-always-to-auto-maint' into
> jk/ui-color-always-to-auto", 2017-10-04), one commit away from the
> commit that added both of the affected lines: 0c88bf5050 (provide
> --color option for all ref-filter users, 2017-10-03).
>
> I grepped the Documentation folder, and haven't found any other
> similar typos.

Thanks.