Re: [PATCH 2/3] git-column.1: clarify initial description, provide examples

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 19, 2018, 22:59 UTC
Message-ID: <xmqqo9ct2ivl.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20180919201231.609-3-frederik@ofb.net>

Frederick Eaton <frederik@ofb.net> writes:

Show 8 quoted lines

> When I read this man page I couldn't figure out what kind of input it
> was referring to, or how input was being put into columns, or where I
> should look for the syntax of the --mode option.
>
> Signed-off-by: Frederick Eaton <frederik@ofb.net>
> ---
>  Documentation/git-column.txt | 35 +++++++++++++++++++++++++++++++++--
>  1 file changed, 33 insertions(+), 2 deletions(-)

I'll defer this to its primary author.

Show 61 quoted lines

>
> diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt
> index 03d18465d..5bbb51068 100644
> --- a/Documentation/git-column.txt
> +++ b/Documentation/git-column.txt
> @@ -13,7 +13,10 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -This command formats its input into multiple columns.
> +This command formats the lines of its standard input into a table with
> +multiple columns. Each input line occupies one cell of the table. It
> +is used internally by other git commands to format output into
> +columns.
>  
>  OPTIONS
>  -------
> @@ -23,7 +26,7 @@ OPTIONS
>  
>  --mode=<mode>::
>  	Specify layout mode. See configuration variable column.ui for option
> -	syntax.
> +	syntax (in git-config(1)).
>  
>  --raw-mode=<n>::
>  	Same as --mode but take mode encoded as a number. This is mainly used
> @@ -43,6 +46,34 @@ OPTIONS
>  --padding=<N>::
>  	The number of spaces between columns. One space by default.
>  
> +EXAMPLES
> +------
> +
> +Format data by columns:
> +------------
> +$ seq 1 24 | git column --mode=column --padding=5
> +1      4      7      10     13     16     19     22
> +2      5      8      11     14     17     20     23
> +3      6      9      12     15     18     21     24
> +------------
> +
> +Format data by rows:
> +------------
> +$ seq 1 21 | git column --mode=row --padding=5
> +1      2      3      4      5      6      7
> +8      9      10     11     12     13     14
> +15     16     17     18     19     20     21
> +------------
> +
> +List some tags in a table with unequal column widths:
> +------------
> +$ git tag --list 'v2.4.*' --column=row,dense
> +v2.4.0  v2.4.0-rc0  v2.4.0-rc1  v2.4.0-rc2  v2.4.0-rc3
> +v2.4.1  v2.4.10     v2.4.11     v2.4.12     v2.4.2
> +v2.4.3  v2.4.4      v2.4.5      v2.4.6      v2.4.7
> +v2.4.8  v2.4.9
> +------------
> +
>  GIT
>  ---
>  Part of the linkgit:git[1] suite