doc: add a blank line around block delimiters

The documentation is using the historical mode for titles, which is a
setext-style (i.e., two-line) section title.

The issue with this mode is that starting block delimiters (e.g., `----`) can be
confused with a section title when they are exactly the same length as the
preceding line. In the original documentation, this is taken care of for English
by the writer, but it is not the case for translations where these delimiters
are hidden. A translator can generate a line that is exactly the same length as
the following block delimiter, which leads to this line being considered as a
title.

To safeguard against this issue, add a blank line before and after block
delimiters where block is at root level, else add a "+" line before block
delimiters to link it to the preceding paragraph.

Signed-off-by: Jean-Noël Avila <[email protected]>

Author: jnavila

Documentation/MyFirstContribution.adoc

@@ -367,6 +367,7 @@ But as we drill down, we can find that `status_init_config()` wraps a call
 to `git_config()`. Let's modify the code we wrote in the previous commit.
 
 Be sure to include the header to allow you to use `struct wt_status`:
+
 ----
 #include "wt-status.h"
 ----

Documentation/MyFirstObjectWalk.adoc

@@ -287,6 +287,7 @@ static void final_rev_info_setup(struct rev_info *rev)
 ====
 Instead of using the shorthand `add_head_to_pending()`, you could do
 something like this:
+
 ----
 	struct setup_revision_opt opt;
 
@@ -295,6 +296,7 @@ something like this:
 	opt.revarg_opt = REVARG_COMMITTISH;
 	setup_revisions(argc, argv, rev, &opt);
 ----
+
 Using a `setup_revision_opt` gives you finer control over your walk's starting
 point.
 ====

Documentation/ToolsForGit.adoc

@@ -34,6 +34,7 @@ This is adapted from Linux's suggestion in its CodingStyle document:
 
 - To follow the rules in CodingGuidelines, it's useful to put the following in
 GIT_CHECKOUT/.dir-locals.el, assuming you use cperl-mode:
+
 ----
 ;; note the first part is useful for C editing, too
 ((nil . ((indent-tabs-mode . t)

Documentation/git-bisect.adoc

@@ -495,6 +495,7 @@ $ git bisect old HEAD~10 # the tenth commit from now is marked as old
 ------------
 +
 or:
++
 ------------
 $ git bisect start --term-old broken --term-new fixed
 $ git bisect fixed

Documentation/git-cat-file.adoc

@@ -322,10 +322,10 @@ of `%(objectsize)` bytes), followed by a newline.
 
 For example, `--batch` without a custom format would produce:
 
-------------
+-----------
 <oid> SP <type> SP <size> LF
 <contents> LF
-------------
+-----------
 
 Whereas `--batch-check='%(objectname) %(objecttype)'` would produce:
 

Documentation/git-check-attr.adoc

@@ -76,19 +76,22 @@ EXAMPLES
 --------
 
 In the examples, the following '.gitattributes' file is used:
+
 ---------------
 *.java diff=java -crlf myAttr
 NoMyAttr.java !myAttr
 README caveat=unspecified
 ---------------
 
 * Listing a single attribute:
++
 ---------------
 $ git check-attr diff org/example/MyClass.java
 org/example/MyClass.java: diff: java
 ---------------
 
 * Listing multiple attributes for a file:
++
 ---------------
 $ git check-attr crlf diff myAttr -- org/example/MyClass.java
 org/example/MyClass.java: crlf: unset
@@ -97,20 +100,23 @@ org/example/MyClass.java: myAttr: set
 ---------------
 
 * Listing all attributes for a file:
++
 ---------------
 $ git check-attr --all -- org/example/MyClass.java
 org/example/MyClass.java: diff: java
 org/example/MyClass.java: myAttr: set
 ---------------
 
 * Listing an attribute for multiple files:
++
 ---------------
 $ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java
 org/example/MyClass.java: myAttr: set
 org/example/NoMyAttr.java: myAttr: unspecified
 ---------------
 
 * Not all values are equally unambiguous:
++
 ---------------
 $ git check-attr caveat README
 README: caveat: unspecified

Documentation/git-column.adoc

@@ -50,6 +50,7 @@ EXAMPLES
 --------
 
 Format data by columns:
++
 ------------
 $ seq 1 24 | git column --mode=column --padding=5
 1      4      7      10     13     16     19     22
@@ -58,6 +59,7 @@ $ seq 1 24 | git column --mode=column --padding=5
 ------------
 
 Format data by rows:
++
 ------------
 $ seq 1 21 | git column --mode=row --padding=5
 1      2      3      4      5      6      7
@@ -66,6 +68,7 @@ $ seq 1 21 | git column --mode=row --padding=5
 ------------
 
 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

Documentation/git-cvsserver.adoc

@@ -125,9 +125,11 @@ creation in your platform (e.g. mkpasswd in Linux, encrypt in OpenBSD or
 pwhash in NetBSD) and paste it in the right location.
 
 Then provide your password via the pserver method, for example:
+
 ------
    cvs -d:pserver:someuser:somepassword@server:/path/repo.git co <HEAD_name>
 ------
+
 No special setup is needed for SSH access, other than having Git tools
 in the PATH. If you have clients that do not accept the CVS_SERVER
 environment variable, you can rename 'git-cvsserver' to `cvs`.
@@ -138,6 +140,7 @@ CVS_SERVER directly in CVSROOT like
 ------
    cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name>
 ------
+
 This has the advantage that it will be saved in your 'CVS/Root' files and
 you don't need to worry about always setting the correct environment
 variable.  SSH users restricted to 'git-shell' don't need to override the default
@@ -168,6 +171,7 @@ All configuration variables can also be overridden for a specific method of
 access. Valid method names are "ext" (for SSH access) and "pserver". The
 following example configuration would disable pserver access while still
 allowing access over SSH.
+
 ------
    [gitcvs]
         enabled=0

Documentation/git-for-each-ref.adoc

@@ -441,6 +441,7 @@ Ref: %(*refname)
 
 A simple example showing the use of shell eval on the output,
 demonstrating the use of --shell.  List the prefixes of all heads:
+
 ------------
 #!/bin/sh
 
@@ -455,6 +456,7 @@ done
 
 A bit more elaborate report on tags, demonstrating that the format
 may be an entire script:
+
 ------------
 #!/bin/sh
 

Documentation/git-p4.adoc

@@ -80,6 +80,7 @@ This:
 
 To reproduce the entire p4 history in Git, use the '@all' modifier on
 the depot path:
+
 ------------
 $ git p4 clone //depot/path/project@all
 ------------
@@ -89,19 +90,23 @@ Sync
 ~~~~
 As development continues in the p4 repository, those changes can
 be included in the Git repository using:
+
 ------------
 $ git p4 sync
 ------------
+
 This command finds new changes in p4 and imports them as Git commits.
 
 P4 repositories can be added to an existing Git repository using
 'git p4 sync' too:
+
 ------------
 $ mkdir repo-git
 $ cd repo-git
 $ git init
 $ git p4 sync //path/in/your/perforce/depot
 ------------
+
 This imports the specified depot into
 'refs/remotes/p4/master' in an existing Git repository.  The
 `--branch` option can be used to specify a different branch to
@@ -125,6 +130,7 @@ and merge them with local uncommitted changes.  Often, the p4 repository
 is the ultimate location for all code, thus a rebase workflow makes
 sense.  This command does 'git p4 sync' followed by 'git rebase' to move
 local commits on top of updated p4 changes.
+
 ------------
 $ git p4 rebase
 ------------
@@ -140,16 +146,19 @@ will be created and populated if it does not already exist.
 
 To submit all changes that are in the current Git branch but not in
 the 'p4/master' branch, use:
+
 ------------
 $ git p4 submit
 ------------
 
 To specify a branch other than the current one, use:
+
 ------------
 $ git p4 submit topicbranch
 ------------
 
 To specify a single commit or a range of commits, use:
+
 ------------
 $ git p4 submit --commit <sha1>
 $ git p4 submit --commit <sha1..sha1>
@@ -510,20 +519,24 @@ when cloning or syncing to have 'git p4' automatically find
 subdirectories in p4, and to generate these as branches in Git.
 
 For example, if the P4 repository structure is:
+
 ----
 //depot/main/...
 //depot/branch1/...
 ----
 
 And "p4 branch -o branch1" shows a View line that looks like:
+
 ----
 //depot/main/... //depot/branch1/...
 ----
 
 Then this 'git p4 clone' command:
+
 ----
 git p4 clone --detect-branches //depot@all
 ----
+
 produces a separate branch in 'refs/remotes/p4/' for //depot/main,
 called 'master', and one for //depot/branch1 called 'depot/branch1'.
 
@@ -536,6 +549,7 @@ simple p4 branch specification, where the "source" and "destination" are
 the path elements in the p4 repository.  The example above relied on the
 presence of the p4 branch.  Without p4 branches, the same result will
 occur with:
+
 ----
 git init depot
 cd depot