threads / patch / 22658

patchDocumentation: Fix indentation problem in git-commit(1)

Subject: [PATCH] Documentation: Fix indentation problem in git-commit(1)

## tl;dr

5 messages between Feb 15, 2010 and Feb 20, 2010. Diffs are folded; open one to read it.

replies: 4people: 3as markdown or json

Jacob Helwig· Feb 15, 2010, 00:45 UTC · lore

All options listed after "-u[<mode>], --untracked-files[=<mode>]" in the git-commit(1) manpage ended up listed as though they were part of the description for -u/--untracked-files. This was introduced by d6293d1.

Signed-off-by: Jacob Helwig <jacob.helwig@gmail.com>
---

Ever since the "See linkgit:git-config[1]..." paragraph was added to the description for the --untracked-files option (d6293d1), the paragraphs for the following options were indented at the same level as the "See linkgit:git-config[1]" paragraph. This problem looks like it only showed up in the manpages, not in the HTML documentation.

I'm not entirely happy with this patch, since the "See linkgit..." paragraph does not retain its previous indentation level in the manpages, or HTML documentation.

Unfortunately, I'm not very good with ASCIIDOC at all, so this is mainly the result of me throwing things at the problem until I found something that (mostly) works. Hopefully this will be enough to grab the attention of someone that's better with ASCIIDOC than I.

 Documentation/git-commit.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

Show changes to Documentation/git-commit.txt +3 −1

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index e99bb14..64fb458 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -197,13 +197,13 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 	Show untracked files (Default: 'all').
 +
 The mode parameter is optional, and is used to specify
-the handling of untracked files. The possible options are:
+the handling of untracked files.
++
+The possible options are:
 +
---
 	- 'no'     - Show no untracked files
 	- 'normal' - Shows untracked files and directories
 	- 'all'    - Also shows individual files in untracked directories.
---
 +
 See linkgit:git-config[1] for configuration variable
 used to change the default for when the option is not

-- 
1.7.0

Thomas Rast· Feb 15, 2010, 09:08 UTC · re: Jacob Helwig · lore

Re: [PATCH] Documentation: Fix indentation problem in git-commit(1)

On Monday 15 February 2010 01:45:17 Jacob Helwig wrote:

> All options listed after "-u[<mode>], --untracked-files[=<mode>]" in the
> git-commit(1) manpage ended up listed as though they were part of the
> description for -u/--untracked-files.  This was introduced by d6293d1.

Wow. I once spent something that felt like an hour fiddling with different options and eventually just gave up without results.

I think the caveat

> I'm not entirely happy with this patch, since the "See linkgit..."
> paragraph does not retain its previous indentation level in the
> manpages, or HTML documentation.

should go into the commit message in some form, but it's definitely an improvement either way.

So,

Acked-by: Thomas Rast <trast@student.ethz.ch>

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Jacob Helwig· Feb 15, 2010, 12:33 UTC · re: Thomas Rast · lore

[PATCH v2] Documentation: Fix indentation problem in git-commit(1)

Ever since the "See linkgit:git-config[1]..." paragraph was added to the description for --untracked-files (d6293d1), the paragraphs for the following options were indented at the same level as the "See linkgit:git-config[1]" paragraph. This problem showed up in the manpages, but not in the HTML documentation.

While this does fix the alignment of the options following --untracked-files in the manpage, the "See linkgit..." portion of the description does not retain its previous indentation level in the manpages, or HTML documentation.

Signed-off-by: Jacob Helwig <jacob.helwig@gmail.com>
Acked-by: Thomas Rast <trast@student.ethz.ch>
---

When adding the caveat to the commit message, the introductory comment paragraph I had before seemed to fit better; I decided to go with a version of it, instead.

 Documentation/git-commit.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

Show changes to Documentation/git-commit.txt +3 −1

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index e99bb14..64fb458 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -197,13 +197,13 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
 	Show untracked files (Default: 'all').
 +
 The mode parameter is optional, and is used to specify
-the handling of untracked files. The possible options are:
+the handling of untracked files.
++
+The possible options are:
 +
---
 	- 'no'     - Show no untracked files
 	- 'normal' - Shows untracked files and directories
 	- 'all'    - Also shows individual files in untracked directories.
---
 +
 See linkgit:git-config[1] for configuration variable
 used to change the default for when the option is not

-- 
1.7.0

Jacob Helwig· Feb 19, 2010, 17:54 UTC · re: Jacob Helwig · lore

Re: [PATCH v2] Documentation: Fix indentation problem in git-commit(1)

On 04:33 Mon 15 Feb     , Jacob Helwig wrote:

Show 46 quoted lines

> Ever since the "See linkgit:git-config[1]..." paragraph was added to the
> description for --untracked-files (d6293d1), the paragraphs for the
> following options were indented at the same level as the "See
> linkgit:git-config[1]" paragraph.  This problem showed up in the
> manpages, but not in the HTML documentation.
> 
> While this does fix the alignment of the options following
> --untracked-files in the manpage, the "See linkgit..." portion of the
> description does not retain its previous indentation level in the
> manpages, or HTML documentation.
> 
> Signed-off-by: Jacob Helwig <jacob.helwig@gmail.com>
> Acked-by: Thomas Rast <trast@student.ethz.ch>
> ---
> 
> When adding the caveat to the commit message, the introductory comment
> paragraph I had before seemed to fit better; I decided to go with a
> version of it, instead.
> 
>  Documentation/git-commit.txt |    6 +++---
>  1 files changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index e99bb14..64fb458 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -197,13 +197,13 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].)
>  	Show untracked files (Default: 'all').
>  +
>  The mode parameter is optional, and is used to specify
> -the handling of untracked files. The possible options are:
> +the handling of untracked files.
> ++
> +The possible options are:
>  +
> ---
>  	- 'no'     - Show no untracked files
>  	- 'normal' - Shows untracked files and directories
>  	- 'all'    - Also shows individual files in untracked directories.
> ---
>  +
>  See linkgit:git-config[1] for configuration variable
>  used to change the default for when the option is not
> -- 
> 1.7.0
>

I haven't seen any further discussion on this after I sent out a v2 with Thomas's suggested change to the commit message, and I didn't want to let the problem that this is trying to address fall through the cracks.

Does anyone have any comments on the v2 of this change?

-- 
Jacob Helwig

Junio C Hamano· Feb 20, 2010, 05:28 UTC · re: Jacob Helwig · lore

Re: [PATCH v2] Documentation: Fix indentation problem in git-commit(1)

Jacob Helwig <jacob.helwig@gmail.com> writes:

Show 5 quoted lines

> Ever since the "See linkgit:git-config[1]..." paragraph was added to the
> description for --untracked-files (d6293d1), the paragraphs for the
> following options were indented at the same level as the "See
> linkgit:git-config[1]" paragraph.  This problem showed up in the
> manpages, but not in the HTML documentation.

I've never noticed it myself, but options after -u do align incorrectly in the manpage rendered on FC11 (asciidoc 8.2.5, xmoto 0.0.22) or on FreeBSD8 (asciidoc 8.4.5, xmlto 0.0.21) without your patch, and your patch seems to fix it on both of them.

Your patch does not make any difference in my primary environment (Debian 5 with asciidoc 8.2.7, xmlto 0.0.20), by the way. The options have the same indentation level, with or without your patch. Your patch does not make things worse, so that is Ok.

The "See git-config(1)" paragraph itself is indented too deeply, to align the last bullet item (all). which does look wrong. This is true on all machines I tried, and your patch does not improve nor worsen this.

When output on Debian 5 (but not FC11 nor FBSD) is rendered to ps/pdf, the bullets alone align with '-u', which is also wrong. Your patch does not improve nor worsen this.