[PATCH 0/6] various fixes for docs

[PATCH 0/6] various fixes for docs

[Andreas Heiduk]

A small batch of fixes for the docs. All but the very first fixes
formatting and similar stuff. The first one makes parsing 
'git worktree list' more future-proof.

Andreas Heiduk (6):
  doc: clarify boundaries of 'git worktree list --porcelain'
  doc: fix ASCII art tab spacing
  doc: fix inappropriate monospace formatting
  doc: fix descripion for 'git tag --format'
  doc: fix indentation of listing blocks in gitweb.conf.txt
  doc: fix formatting in git-update-ref

 Documentation/git-bisect-lk2009.txt | 30 ++++++++++++++---------------
 Documentation/git-checkout.txt      | 14 +++++++-------
 Documentation/git-merge-base.txt    |  6 +++---
 Documentation/git-tag.txt           | 12 ++++++------
 Documentation/git-update-ref.txt    |  8 ++++----
 Documentation/git-upload-pack.txt   |  1 +
 Documentation/git-worktree.txt      |  4 ++--
 Documentation/git.txt               | 10 +++++-----
 Documentation/gitattributes.txt     | 30 ++++++++++++++---------------
 Documentation/gitmodules.txt        | 17 +++++++++-------
 Documentation/gitsubmodules.txt     | 14 +++++++++-----
 Documentation/gitweb.conf.txt       | 25 ++++++++++++++----------
 12 files changed, 92 insertions(+), 79 deletions(-)

-- 
2.19.1

[PATCH 1/6] doc: clarify boundaries of 'git worktree list --porcelain'

[Andreas Heiduk]

Defined delimiters for 'git worktree list --porcelain' make the format
easier to parse in scripts. For example

	sed -n '/^worktree ID$/,/^$/p'

extracts only the information for the worktree 'ID'.

The format did not changed since [1], only the guaranty is added.

[1] bb9c03b82a (worktree: add 'list' command, 2015-10-08)

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-worktree.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index e2ee9fc21b..73520434f6 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -270,8 +270,8 @@ Porcelain Format
 The porcelain format has a line per attribute.  Attributes are listed with a
 label and value separated by a single space.  Boolean attributes (like 'bare'
 and 'detached') are listed as a label only, and are only present if and only
-if the value is true.  An empty line indicates the end of a worktree.  For
-example:
+if the value is true.  The first attribute of a worktree is always `worktree`,
+an empty line indicates the end of the record.  For example:
 
 ------------
 $ git worktree list --porcelain
-- 
2.19.1

Re: [PATCH 1/6] doc: clarify boundaries of 'git worktree list --porcelain'

[Eric Sunshine]

On Mon, Oct 22, 2018 at 4:46 PM Andreas Heiduk <asheiduk@gmail.com> wrote:
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> @@ -270,8 +270,8 @@ Porcelain Format
>  The porcelain format has a line per attribute.  Attributes are listed with a
>  label and value separated by a single space.  Boolean attributes (like 'bare'
>  and 'detached') are listed as a label only, and are only present if and only
> -if the value is true.  An empty line indicates the end of a worktree.  For
> -example:
> +if the value is true.  The first attribute of a worktree is always `worktree`,
> +an empty line indicates the end of the record.  For example:

When I suggested the --porcelain option for "git worktree list" and
provided an example of its proposed output, the idea all along was
that the "worktree" line itself would indicate start-of-stanza. A
blank line between records is superfluous and unnecessary.
Unfortunately, by the time the implementation was posted with blank
line as stanza separator, I was not around to contest it, and it ended
up in a release, after which point it was too late to change it.

So, the tl;dr is that this documentation update agrees with the
original intention as I envisioned it (although I wouldn't be sad to
see the mention of "blank line" dropped altogether, but that's perhaps
a separate battle).

[PATCH 2/6] doc: fix ASCII art tab spacing

[Andreas Heiduk]

Followup to 5dd05ebf ("doc: fix merge-base ASCII art tab spacing", 2016-10-21)

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-bisect-lk2009.txt | 30 ++++++++++++++---------------
 Documentation/git-checkout.txt      | 14 +++++++-------
 Documentation/git-merge-base.txt    |  6 +++---
 3 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt
index 0f9ef2f25e..e99925184d 100644
--- a/Documentation/git-bisect-lk2009.txt
+++ b/Documentation/git-bisect-lk2009.txt
@@ -633,11 +633,11 @@ and so at step 3) we compute f(X).
 Let's take the following graph as an example:
 
 -------------
-	    G-H-I-J
-	   /       \
+            G-H-I-J
+           /       \
 A-B-C-D-E-F         O
-	   \       /
-	    K-L-M-N
+           \       /
+            K-L-M-N
 -------------
 
 If we compute the following non optimal function on it:
@@ -649,25 +649,25 @@ g(X) = min(number_of_ancestors(X), number_of_descendants(X))
 we get:
 
 -------------
-	    4 3 2 1
-	    G-H-I-J
+            4 3 2 1
+            G-H-I-J
 1 2 3 4 5 6/       \0
 A-B-C-D-E-F         O
-	   \       /
-	    K-L-M-N
-	    4 3 2 1
+           \       /
+            K-L-M-N
+            4 3 2 1
 -------------
 
 but with the algorithm used by git bisect we get:
 
 -------------
-	    7 7 6 5
-	    G-H-I-J
+            7 7 6 5
+            G-H-I-J
 1 2 3 4 5 6/       \0
 A-B-C-D-E-F         O
-	   \       /
-	    K-L-M-N
-	    7 7 6 5
+           \       /
+            K-L-M-N
+            7 7 6 5
 -------------
 
 So we chose G, H, K or L as the best bisection point, which is better
@@ -773,7 +773,7 @@ forked of the main branch at a commit named "D" like this:
 -------------
 A-B-C-D-E-F-G  <--main
        \
-	H-I-J  <--dev
+        H-I-J  <--dev
 -------------
 
 The commit "D" is called a "merge base" for branch "main" and "dev"
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9db02928c4..801de2f764 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -311,9 +311,9 @@ branch refers to a specific commit. Let's look at a repo with three
 commits, one of them tagged, and with branch 'master' checked out:
 
 ------------
-	   HEAD (refers to branch 'master')
-	    |
-	    v
+           HEAD (refers to branch 'master')
+            |
+            v
 a---b---c  branch 'master' (refers to commit 'c')
     ^
     |
@@ -329,9 +329,9 @@ to commit 'd':
 ------------
 $ edit; git add; git commit
 
-	       HEAD (refers to branch 'master')
-		|
-		v
+               HEAD (refers to branch 'master')
+                |
+                v
 a---b---c---d  branch 'master' (refers to commit 'd')
     ^
     |
@@ -398,7 +398,7 @@ at what happens when we then checkout master:
 ------------
 $ git checkout master
 
-	       HEAD (refers to branch 'master')
+               HEAD (refers to branch 'master')
       e---f     |
      /          v
 a---b---c---d  branch 'master' (refers to commit 'd')
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index 502e00ec35..9f07f4f6ed 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -154,13 +154,13 @@ topic origin/master`, the history of remote-tracking branch
 `origin/master` may have been rewound and rebuilt, leading to a
 history of this shape:
 
-			 o---B2
+	                 o---B2
 	                /
 	---o---o---B1--o---o---o---B (origin/master)
 	        \
-		 B0
+	         B0
 	          \
-		   D0---D1---D (topic)
+	           D0---D1---D (topic)
 
 where `origin/master` used to point at commits B0, B1, B2 and now it
 points at B, and your `topic` branch was started on top of it back
-- 
2.19.1

[PATCH 3/6] doc: fix inappropriate monospace formatting

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-upload-pack.txt |  1 +
 Documentation/git.txt             | 10 +++++-----
 Documentation/gitattributes.txt   | 30 +++++++++++++++---------------
 Documentation/gitmodules.txt      | 17 ++++++++++-------
 Documentation/gitsubmodules.txt   | 14 +++++++++-----
 5 files changed, 40 insertions(+), 32 deletions(-)

diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
index 822ad593af..998f52d3df 100644
--- a/Documentation/git-upload-pack.txt
+++ b/Documentation/git-upload-pack.txt
@@ -11,6 +11,7 @@ SYNOPSIS
 [verse]
 'git-upload-pack' [--[no-]strict] [--timeout=<n>] [--stateless-rpc]
 		  [--advertise-refs] <directory>
+
 DESCRIPTION
 -----------
 Invoked by 'git fetch-pack', learns what
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 2ac9b1c7fe..00156d64aa 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -402,11 +402,11 @@ Git so take care if using a foreign front-end.
 	of Git object directories which can be used to search for Git
 	objects. New objects will not be written to these directories.
 +
-	Entries that begin with `"` (double-quote) will be interpreted
-	as C-style quoted paths, removing leading and trailing
-	double-quotes and respecting backslash escapes. E.g., the value
-	`"path-with-\"-and-:-in-it":vanilla-path` has two paths:
-	`path-with-"-and-:-in-it` and `vanilla-path`.
+Entries that begin with `"` (double-quote) will be interpreted
+as C-style quoted paths, removing leading and trailing
+double-quotes and respecting backslash escapes. E.g., the value
+`"path-with-\"-and-:-in-it":vanilla-path` has two paths:
+`path-with-"-and-:-in-it` and `vanilla-path`.
 
 `GIT_DIR`::
 	If the `GIT_DIR` environment variable is set then it
diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 92010b062e..b8392fc330 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -303,21 +303,21 @@ number of pitfalls:
   attribute. If you decide to use the `working-tree-encoding` attribute
   in your repository, then it is strongly recommended to ensure that all
   clients working with the repository support it.
-
-  For example, Microsoft Visual Studio resources files (`*.rc`) or
-  PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
-  If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
-  a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
-  stored as UTF-8 internally. A client without `working-tree-encoding`
-  support will checkout `foo.ps1` as UTF-8 encoded file. This will
-  typically cause trouble for the users of this file.
-
-  If a Git client, that does not support the `working-tree-encoding`
-  attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
-  stored "as-is" internally (in this example probably as UTF-16).
-  A client with `working-tree-encoding` support will interpret the
-  internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
-  That operation will fail and cause an error.
++
+For example, Microsoft Visual Studio resources files (`*.rc`) or
+PowerShell script files (`*.ps1`) are sometimes encoded in UTF-16.
+If you declare `*.ps1` as files as UTF-16 and you add `foo.ps1` with
+a `working-tree-encoding` enabled Git client, then `foo.ps1` will be
+stored as UTF-8 internally. A client without `working-tree-encoding`
+support will checkout `foo.ps1` as UTF-8 encoded file. This will
+typically cause trouble for the users of this file.
++
+If a Git client, that does not support the `working-tree-encoding`
+attribute, adds a new file `bar.ps1`, then `bar.ps1` will be
+stored "as-is" internally (in this example probably as UTF-16).
+A client with `working-tree-encoding` support will interpret the
+internal contents as UTF-8 and try to convert it to UTF-16 on checkout.
+That operation will fail and cause an error.
 
 - Reencoding content to non-UTF encodings can cause errors as the
   conversion might not be UTF-8 round trip safe. If you suspect your
diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt
index 4d63def206..312b6f9259 100644
--- a/Documentation/gitmodules.txt
+++ b/Documentation/gitmodules.txt
@@ -67,7 +67,8 @@ submodule.<name>.fetchRecurseSubmodules::
 submodule.<name>.ignore::
 	Defines under what circumstances "git status" and the diff family show
 	a submodule as modified. The following values are supported:
-
++
+--
 	all;; The submodule will never be considered modified (but will
 	    nonetheless show up in the output of status and commit when it has
 	    been staged).
@@ -84,12 +85,14 @@ submodule.<name>.ignore::
 	    differences, and modifications to tracked and untracked files are
 	    shown. This is the default option.
 
-	If this option is also present in the submodules entry in .git/config
-	of the superproject, the setting there will override the one found in
-	.gitmodules.
-	Both settings can be overridden on the command line by using the
-	"--ignore-submodule" option. The 'git submodule' commands are not
-	affected by this setting.
+If this option is also present in the submodules entry in .git/config
+of the superproject, the setting there will override the one found in
+.gitmodules.
+
+Both settings can be overridden on the command line by using the
+"--ignore-submodule" option. The 'git submodule' commands are not
+affected by this setting.
+--
 
 submodule.<name>.shallow::
 	When set to true, a clone of this submodule will be performed as a
diff --git a/Documentation/gitsubmodules.txt b/Documentation/gitsubmodules.txt
index 504c5f1a88..57999e9f36 100644
--- a/Documentation/gitsubmodules.txt
+++ b/Documentation/gitsubmodules.txt
@@ -169,11 +169,15 @@ ACTIVE SUBMODULES
 
 A submodule is considered active,
 
-  (a) if `submodule.<name>.active` is set to `true`
-     or
-  (b) if the submodule's path matches the pathspec in `submodule.active`
-     or
-  (c) if `submodule.<name>.url` is set.
+  a. if `submodule.<name>.active` is set to `true`
++
+or
+
+  b. if the submodule's path matches the pathspec in `submodule.active`
++
+or
+
+  c. if `submodule.<name>.url` is set.
 
 and these are evaluated in this order.
 
-- 
2.19.1

[PATCH 4/6] doc: fix descripion for 'git tag --format'

[Andreas Heiduk]

The '--format=<format>' is now listed in the 'OPTIONS' section, not only
the '<format>' string itself. The description moved up a few paragraphs
because '<format>' is not a standalone paramater but a parameter for the
option '--format'.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-tag.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 92f9c12b87..f2d644e3af 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -187,6 +187,12 @@ This option is only applicable when listing tags without annotation lines.
 	`--create-reflog`, but currently does not negate the setting of
 	`core.logAllRefUpdates`.
 
+--format=<format>::
+	A string that interpolates `%(fieldname)` from a tag ref being shown
+	and the object it points at.  The format is the same as
+	that of linkgit:git-for-each-ref[1].  When unspecified,
+	defaults to `%(refname:strip=2)`.
+
 <tagname>::
 	The name of the tag to create, delete, or describe.
 	The new tag name must pass all checks defined by
@@ -198,12 +204,6 @@ This option is only applicable when listing tags without annotation lines.
 	The object that the new tag will refer to, usually a commit.
 	Defaults to HEAD.
 
-<format>::
-	A string that interpolates `%(fieldname)` from a tag ref being shown
-	and the object it points at.  The format is the same as
-	that of linkgit:git-for-each-ref[1].  When unspecified,
-	defaults to `%(refname:strip=2)`.
-
 CONFIGURATION
 -------------
 By default, 'git tag' in sign-with-default mode (-s) will use your
-- 
2.19.1

[PATCH 5/6] doc: fix indentation of listing blocks in gitweb.conf.txt

[Andreas Heiduk]

'gitweb.conf.txt' uses inconsistent indentation in listing blocks and a mix
of listing blocks and literal paragraphs. Both didn't look pretty in the
rendered HTML page.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/gitweb.conf.txt | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt
index 9c8982ec98..c0a326e388 100644
--- a/Documentation/gitweb.conf.txt
+++ b/Documentation/gitweb.conf.txt
@@ -19,10 +19,12 @@ end of a line is ignored.  See *perlsyn*(1) for details.
 
 An example:
 
-    # gitweb configuration file for http://git.example.org
-    #
-    our $projectroot = "/srv/git"; # FHS recommendation
-    our $site_name = 'Example.org >> Repos';
+------------------------------------------------
+# gitweb configuration file for http://git.example.org
+#
+our $projectroot = "/srv/git"; # FHS recommendation
+our $site_name = 'Example.org >> Repos';
+------------------------------------------------
 
 
 The configuration file is used to override the default settings that
@@ -357,6 +359,7 @@ $home_link_str::
 +
 For example, the following setting produces a breadcrumb trail like
 "home / dev / projects / ..." where "projects" is the home link.
++
 ----------------------------------------------------------------------------
     our @extra_breadcrumbs = (
       [ 'home' => 'https://www.example.org/' ],
@@ -901,14 +904,16 @@ To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and
 "zip" snapshots), while allowing individual projects to turn them off, put
 the following in your GITWEB_CONFIG file:
 
-	$feature{'blame'}{'default'} = [1];
-	$feature{'blame'}{'override'} = 1;
+--------------------------------------------------------------------------------
+$feature{'blame'}{'default'} = [1];
+$feature{'blame'}{'override'} = 1;
 
-	$feature{'pickaxe'}{'default'} = [1];
-	$feature{'pickaxe'}{'override'} = 1;
+$feature{'pickaxe'}{'default'} = [1];
+$feature{'pickaxe'}{'override'} = 1;
 
-	$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
-	$feature{'snapshot'}{'override'} = 1;
+$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
+$feature{'snapshot'}{'override'} = 1;
+--------------------------------------------------------------------------------
 
 If you allow overriding for the snapshot feature, you can specify which
 snapshot formats are globally disabled. You can also add any command-line
-- 
2.19.1

[PATCH 6/6] doc: fix formatting in git-update-ref

[Andreas Heiduk]

Remove the parapgraph numbers from lines explaining the reflog format
and typeset these lines in monospace.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-update-ref.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index fda8516677..9671423117 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -129,8 +129,8 @@ a line to the log file "$GIT_DIR/logs/<ref>" (dereferencing all
 symbolic refs before creating the log name) describing the change
 in ref value.  Log lines are formatted as:
 
-    . oldsha1 SP newsha1 SP committer LF
-+
+    oldsha1 SP newsha1 SP committer LF
+
 Where "oldsha1" is the 40 character hexadecimal value previously
 stored in <ref>, "newsha1" is the 40 character hexadecimal value of
 <newvalue> and "committer" is the committer's name, email address
@@ -138,8 +138,8 @@ and date in the standard Git committer ident format.
 
 Optionally with -m:
 
-    . oldsha1 SP newsha1 SP committer TAB message LF
-+
+    oldsha1 SP newsha1 SP committer TAB message LF
+
 Where all fields are as described above and "message" is the
 value supplied to the -m option.
 
-- 
2.19.1