threads / patch / 48909

patchDocumentation: fix --color option formatting

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

## tl;dr

5 messages between Jul 18, 2018 and Jul 20, 2018. Diffs are folded; open one to read it.

replies: 4people: 4as markdown or json

Andrei Rybak· Jul 18, 2018, 17:37 UTC · lore
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(-)
Show changes to 2 files +2 −0

Documentation/git-for-each-ref.txt, Documentation/git-tag.txt

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
Jeff King· Jul 18, 2018, 17:49 UTC · re: Andrei Rybak · lore

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

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.
Show 13 quoted lines
> 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
brian m. carlson· Jul 20, 2018, 22:36 UTC · re: Jeff King · lore

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

On Wed, Jul 18, 2018 at 01:49:44PM -0400, Jeff King wrote:
Show 23 quoted lines
> 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
Junio C Hamano· Jul 20, 2018, 23:37 UTC · re: brian m. carlson · lore

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

"brian m. carlson" <sandals@crustytoothpaste.net> writes:
Show 6 quoted lines
> 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.
Junio C Hamano· Jul 18, 2018, 18:24 UTC · re: Andrei Rybak · lore

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

Andrei Rybak <rybak.a.v@gmail.com> writes:
Show 15 quoted lines
> 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.

← back to recent threads