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

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

[Jacob Helwig]

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(-)

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

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

[Thomas Rast]

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

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

[Jacob Helwig]

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

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

[Jacob Helwig]

On 04:33 Mon 15 Feb     , Jacob Helwig wrote:
> 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

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

[Junio C Hamano]

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

> 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.