[PATCH] doc: fix unmatched code fences

[PATCH] doc: fix unmatched code fences

[Jean-Noel Avila]

This mismatch upsets the renderer on git-scm.com.

Signed-off-by: Jean-Noel Avila <jn.avila@free.fr>
---
 Documentation/gitcore-tutorial.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index 8475c07..36e9ab3 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -259,7 +259,7 @@ index 557db03..263414f 100644
 @@ -1 +1,2 @@
  Hello World
 +It's a new day for git
-----
+------------
 
 i.e. the diff of the change we caused by adding another line to `hello`.
 
-- 
2.4.0.rc2

Re: [PATCH] doc: fix unmatched code fences

[Junio C Hamano]

Jean-Noel Avila <jn.avila@free.fr> writes:

> This mismatch upsets the renderer on git-scm.com.

Thanks.

I do not think this is the first time AsciiDoc(or) rendering glitch
was reported.  GitHub folks, can you guys think of an automated way
to spot these?  Relying on site visitors to eyeball and hoping them
to report is not an ideal approach.

>
> Signed-off-by: Jean-Noel Avila <jn.avila@free.fr>
> ---
>  Documentation/gitcore-tutorial.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
> index 8475c07..36e9ab3 100644
> --- a/Documentation/gitcore-tutorial.txt
> +++ b/Documentation/gitcore-tutorial.txt
> @@ -259,7 +259,7 @@ index 557db03..263414f 100644
>  @@ -1 +1,2 @@
>   Hello World
>  +It's a new day for git
> -----
> +------------
>  
>  i.e. the diff of the change we caused by adding another line to `hello`.

Re: [PATCH] doc: fix unmatched code fences

[Jeff King]

On Tue, May 12, 2015 at 11:45:56AM -0700, Junio C Hamano wrote:

> Jean-Noel Avila <jn.avila@free.fr> writes:
> 
> > This mismatch upsets the renderer on git-scm.com.
> 
> Thanks.
> 
> I do not think this is the first time AsciiDoc(or) rendering glitch
> was reported.  GitHub folks, can you guys think of an automated way
> to spot these?  Relying on site visitors to eyeball and hoping them
> to report is not an ideal approach.

Here's a patch to fix the remaining cases of this particular problem, at
least.

You can build with asciidoctor on the command-line. I don't know if it
would be feasible to diff the asciidoc and asciidoctor output to look
for gratuitous differences (or if the output is so different due to
trivial stuff that the diff is unreadable).

-- >8 --
Subject: doc: fix unmatched code fences in git-stripspace

The asciidoctor renderer is more picky than classic asciidoc,
and insists that the start and end of a code fence be the
same size.

Found with this hacky perl script:

    foreach my $fn (@ARGV) {
      open(my $fh, '<', $fn);
      my ($fence, $fence_lineno, $prev);
      while (<$fh>) {
        chomp;
        if (/^----+$/) {
          if ($fence_lineno) {
            if ($_ ne $fence) {
              print "$fn:$fence_lineno:mismatched fence: ",
                    length($fence), " != ", length($_), "\n";
            }
            $fence_lineno = undef;
          }
	  # hacky check to avoid title-underlining
          elsif ($prev eq '' || $prev eq '+') {
            $fence = $_;
            $fence_lineno = $.;
          }
        }
        $prev = $_;
      }
    }

Signed-off-by: Jeff King <peff@peff.net>
---
With this patch and the one from Jean-Noel, the script above finds only
one hit, which is a false positive. It's at git-commit.txt:233, and it
looks like:

    It is a rough equivalent for:
    ------
            $ git reset --soft HEAD^
            $ ... do something else to come up with the right tree ...
            $ git commit -c ORIG_HEAD

    ------

I have no idea how asciidoc knows that this is a code block and not a
title called "It is a rough...".  So probably in addition to this false
positive, we may be missing some other cases. Doing it right would
probably involve just reusing asciidoc's parser.

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

diff --git a/Documentation/git-stripspace.txt b/Documentation/git-stripspace.txt
index 6c6e989..60328d5 100644
--- a/Documentation/git-stripspace.txt
+++ b/Documentation/git-stripspace.txt
@@ -49,7 +49,7 @@ EXAMPLES
 
 Given the following noisy input with '$' indicating the end of a line:
 
---------
+---------
 |A brief introduction   $
 |   $
 |$
@@ -65,7 +65,7 @@ Given the following noisy input with '$' indicating the end of a line:
 
 Use 'git stripspace' with no arguments to obtain:
 
---------
+---------
 |A brief introduction$
 |$
 |A new paragraph$
@@ -79,7 +79,7 @@ Use 'git stripspace' with no arguments to obtain:
 
 Use 'git stripspace --strip-comments' to obtain:
 
---------
+---------
 |A brief introduction$
 |$
 |A new paragraph$
-- 
2.4.0.192.g5f8138b

Re: [PATCH] doc: fix unmatched code fences

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> With this patch and the one from Jean-Noel, the script above finds only
> one hit, which is a false positive. It's at git-commit.txt:233, and it
> looks like:
>
>     It is a rough equivalent for:
>     ------
>             $ git reset --soft HEAD^
>             $ ... do something else to come up with the right tree ...
>             $ git commit -c ORIG_HEAD
>
>     ------
>
> I have no idea how asciidoc knows that this is a code block and not a
> title called "It is a rough...".

It obviously is not a title underline as the lengths are vastly
different.  It would be an interesing exercise to make both of them
longer, but I suspect giving an extra blank line there may not hurt.

Thanks, will queue.

Re: [PATCH] doc: fix unmatched code fences

[Jeff King]

On Tue, May 12, 2015 at 08:43:52PM -0700, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > With this patch and the one from Jean-Noel, the script above finds only
> > one hit, which is a false positive. It's at git-commit.txt:233, and it
> > looks like:
> >
> >     It is a rough equivalent for:
> >     ------
> >             $ git reset --soft HEAD^
> >             $ ... do something else to come up with the right tree ...
> >             $ git commit -c ORIG_HEAD
> >
> >     ------
> >
> > I have no idea how asciidoc knows that this is a code block and not a
> > title called "It is a rough...".
> 
> It obviously is not a title underline as the lengths are vastly
> different.

Yes, but Python Asciidoc allows the lengths to differ. So clearly it
uses some kind of heuristic, or this is some context in the parser that
disambiguates the case.

-Peff

Re: [PATCH] doc: fix unmatched code fences

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>> It obviously is not a title underline as the lengths are vastly
>> different.
>
> Yes, but Python Asciidoc allows the lengths to differ.

Hmmm, I thought the title underline was a bit more strict. I do
recall having to fix manual pages for many commands, but we do not
add new commands these days anymore, so perhaps things have changed
since then.

> So clearly it
> uses some kind of heuristic, or this is some context in the parser that
> disambiguates the case.

Perhaps.

Thanks.

Re: [PATCH] doc: fix unmatched code fences

[Jeff King]

On Tue, May 12, 2015 at 09:32:45PM -0700, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> >> It obviously is not a title underline as the lengths are vastly
> >> different.
> >
> > Yes, but Python Asciidoc allows the lengths to differ.
> 
> Hmmm, I thought the title underline was a bit more strict. I do
> recall having to fix manual pages for many commands, but we do not
> add new commands these days anymore, so perhaps things have changed
> since then.

I think it is loose in AsciiDoc and strict in AsciiDoctor, so we have
been slowly making sure they are all consistent. And we missed one,
which will be in the series I'll send in a moment. :)

I suspect the potential ambiguity is one of the reasons that AsciiDoctor
went with the stricter rule.

-Peff

[PATCH 0/8] asciidoc fixups

[Jeff King]

On Tue, May 12, 2015 at 10:15:56PM -0400, Jeff King wrote:

> You can build with asciidoctor on the command-line. I don't know if it
> would be feasible to diff the asciidoc and asciidoctor output to look
> for gratuitous differences (or if the output is so different due to
> trivial stuff that the diff is unreadable).

So...it kind of works. I had to do unspeakable things with sed, and even
then ended up with an 18,000-line "--color-words" diff.

Below are some fixes. The early ones are actual bugs in our sources. The
latter ones are changes we could do to make asciidoctor happier. Each
patch is independent, so we can take or leave whatever we want.

After this series, the remaining problems are:

  - asciidoctor does not render {litdd}, which is our invention; locally
    this may be because I did not have the right incantation, but it is
    also broken on git-scm.com. I think the right fix is to define that
    attribute for the site renderer (so not a bug in our sources, and
    not an asciidoctor bug)

  - in the '[verse]' section of the SYNOPSIS of each man page, AsciiDoc
    renders 'git add' in the usual way (with emphasis). Whereas
    AsciiDoctor renders it normally, with the literal quotes included.

    In the same [verse] section, AsciiDoctor does not convert literal
    "..." into a fancy ellipsis. So perhaps it treats [verse] as a
    section in which markup is not expanded? This may be related to the
    [verseblock] stuff we have in our config file.

  - We use "{attr? foo}" to display "foo" only when "attr" is set.
    AsciiDoctor does not seem to understand this and renders the whole
    string.

  - Lots of places where we backslash-escape some syntax for AsciiDoc
    ends up rendered by AsciiDoctor with the backslashes included. In
    some cases the quoting is unnecessary and we can drop it (see
    patches 6 and 7 below). But in others it really is necessary, and
    AsciiDoc generates bad output without the backslashes. The major
    ones are "--" surrounded by spaces (which becomes an emdash), and
    things like @\{HEAD}, which needs quoted to tell AsciiDoc that HEAD
    isn't an attribute.

    I'm not sure of the solution (is AsciiDoctor just broken, or
    is there some other syntax we could use that would work in both
    places, or what?).

Here are the patches. They do not include the code-fence fixes from
Jean-Noel and myself that were already posted, but could easily go on
top.

  [1/8]: doc: fix misrendering due to `single quote'
  [2/8]: doc: fix unquoted use of "{type}"
  [3/8]: doc: fix hanging "+"-continuation
  [4/8]: doc: fix length of underlined section-title
  [5/8]: doc/add: reformat `--edit` option
  [6/8]: doc: convert \--option to --option
  [7/8]: doc: drop backslash quoting of some curly braces
  [8/8]: doc: put example URLs inside literal backticks

-Peff

[PATCH 1/8] doc: fix misrendering due to `single quote'

[Jeff King]

AsciiDoc misparses some text that contains a `literal`
word followed by a fancy `single quote' word, and treats
everything from the start of the literal to the end of the
quote as a single-quoted phrase.

We can work around this by switching the latter to be a
literal, as well. In the first case, this is perhaps what
was intended anyway, as it makes us consistent with the the
earlier literals in the same paragraph. In the second, the
output is arguably better, as we will format our commit
references as <code> blocks.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/diff-generate-patch.txt | 2 +-
 Documentation/git-rebase.txt          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index 843a20b..bcf54da 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -77,7 +77,7 @@ combined diff format
 Any diff-generating command can take the `-c` or `--cc` option to
 produce a 'combined diff' when showing a merge. This is the default
 format when showing merges with linkgit:git-diff[1] or
-linkgit:git-show[1]. Note also that you can give the `-m' option to any
+linkgit:git-show[1]. Note also that you can give the `-m` option to any
 of these commands to force generation of diffs with individual parents
 of a merge.
 
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index 47984e8..1d01baa 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -80,7 +80,7 @@ remain the checked-out branch.
 If the upstream branch already contains a change you have made (e.g.,
 because you mailed a patch which was applied upstream), then that commit
 will be skipped. For example, running `git rebase master` on the
-following history (in which A' and A introduce the same set of changes,
+following history (in which `A'` and `A` introduce the same set of changes,
 but have different committer information):
 
 ------------
-- 
2.4.0.192.g5f8138b

[PATCH 2/8] doc: fix unquoted use of "{type}"

[Jeff King]

Curly braces open an "attribute" in AsciiDoc; if there's no
such attribute, strange things may happen. In this case, the
unquoted "{type}" causes AsciiDoc to omit an entire line of
text from the output. We can fix it by putting the whole
phrase inside literal backticks (which also lets us get rid
of ugly backslash escaping).

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-rev-parse.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 97fc703..52e6826 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -102,7 +102,7 @@ eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")"
 +
 If you want to make sure that the output actually names an object in
 your object database and/or can be used as a specific type of object
-you require, you can add "\^{type}" peeling operator to the parameter.
+you require, you can add the `^{type}` peeling operator to the parameter.
 For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
 names an existing object that is a commit-ish (i.e. a commit, or an
 annotated tag that points at a commit).  To make sure that `$VAR`
-- 
2.4.0.192.g5f8138b

[PATCH 3/8] doc: fix hanging "+"-continuation

[Jeff King]

In list content that wants to continue to a second
paragraph, the "+" continuation and subsequent paragraph
need to be left-aligned. Otherwise AsciiDoc seems to insert
only a linebreak.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-svn.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 39e9a18..1377008 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -279,9 +279,9 @@ first have already been pushed into SVN.
 	Ask the user to confirm that a patch set should actually be sent to SVN.
 	For each patch, one may answer "yes" (accept this patch), "no" (discard this
 	patch), "all" (accept all patches), or "quit".
-	+
-	'git svn dcommit' returns immediately if answer is "no" or "quit", without
-	committing anything to SVN.
++
+'git svn dcommit' returns immediately if answer is "no" or "quit", without
+committing anything to SVN.
 
 'branch'::
 	Create a branch in the SVN repository.
-- 
2.4.0.192.g5f8138b

[PATCH 4/8] doc: fix length of underlined section-title

[Jeff King]

In AsciiDoc, it is OK to say:

   this is my title
   -------------------------

but AsciiDoctor is more strict. Let's match the underline to
the title (which also makes the source prettier to read).
The output from AsciiDoc is the same either way.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-fast-import.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 690fed3..bf7fbd4 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -600,7 +600,7 @@ be removed from the branch.
 See `filemodify` above for a detailed description of `<path>`.
 
 `filecopy`
-^^^^^^^^^^^^
+^^^^^^^^^^
 Recursively copies an existing file or subdirectory to a different
 location within the branch.  The existing file or directory must
 exist.  If the destination exists it will be completely replaced
-- 
2.4.0.192.g5f8138b

[PATCH 5/8] doc/add: reformat `--edit` option

[Jeff King]

All of the other options in the list put short and long as
two separate headings.

We can also drop the backslashing of `--`. It isn't used
elsewhere and is unnecessary for modern asciidoc (plus it
confuses asciidoctor).

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-add.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index f2eb907..fe5282f 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -93,7 +93,8 @@ This effectively runs `add --interactive`, but bypasses the
 initial command menu and directly jumps to the `patch` subcommand.
 See ``Interactive mode'' for details.
 
--e, \--edit::
+-e::
+--edit::
 	Open the diff vs. the index in an editor and let the user
 	edit it.  After the editor was closed, adjust the hunk headers
 	and apply the patch to the index.
-- 
2.4.0.192.g5f8138b

[PATCH 6/8] doc: convert \--option to --option

[Jeff King]

Older versions of AsciiDoc would convert the "--" in
"--option" into an emdash. According to 565e135
(Documentation: quote double-dash for AsciiDoc, 2011-06-29),
this is fixed in AsciiDoc 8.3.0. According to bf17126, we
don't support anything older than 8.4.1 anyway, so we no
longer need to worry about quoting.

Even though this does not change the output at all, there
are a few good reasons to drop the quoting:

  1. It makes the source prettier to read.

  2. We don't quote consistently, which may be confusing when
     reading the source.

  3. Asciidoctor does not like the quoting, and renders a
     literal backslash.

Signed-off-by: Jeff King <peff@peff.net>
---
So this is the first of the more questionable patches, simply because we
are appeasing Asciidoctor, but not fixing the root problem (i.e., there
are still lots of places where the backslash quoting is messed up, like
HEAD@\{yesterday}). So I suspect we need to figure that problem out, and
then the asciidoctor issues will just go away. However, I think this may
be worth doing just to prettify the source.

 Documentation/config.txt           | 10 ++--
 Documentation/git-fast-export.txt  |  6 +--
 Documentation/git-fast-import.txt  | 28 +++++------
 Documentation/git-fetch-pack.txt   |  2 +-
 Documentation/git-pack-objects.txt |  2 +-
 Documentation/git-push.txt         |  4 +-
 Documentation/git-rev-list.txt     | 96 +++++++++++++++++++-------------------
 Documentation/git-rev-parse.txt    |  2 +-
 Documentation/git-send-pack.txt    |  2 +-
 Documentation/git-show.txt         |  2 +-
 Documentation/gitdiffcore.txt      |  6 +--
 11 files changed, 80 insertions(+), 80 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 948b8b0..e5d2ace 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2279,18 +2279,18 @@ remote.<name>.skipFetchAll::
 
 remote.<name>.receivepack::
 	The default program to execute on the remote side when pushing.  See
-	option \--receive-pack of linkgit:git-push[1].
+	option --receive-pack of linkgit:git-push[1].
 
 remote.<name>.uploadpack::
 	The default program to execute on the remote side when fetching.  See
-	option \--upload-pack of linkgit:git-fetch-pack[1].
+	option --upload-pack of linkgit:git-fetch-pack[1].
 
 remote.<name>.tagOpt::
-	Setting this value to \--no-tags disables automatic tag following when
-	fetching from remote <name>. Setting it to \--tags will fetch every
+	Setting this value to --no-tags disables automatic tag following when
+	fetching from remote <name>. Setting it to --tags will fetch every
 	tag from remote <name>, even if they are not reachable from remote
 	branch heads. Passing these flags directly to linkgit:git-fetch[1] can
-	override this setting. See options \--tags and \--no-tags of
+	override this setting. See options --tags and --no-tags of
 	linkgit:git-fetch[1].
 
 remote.<name>.vcs::
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 929e496..ed57c68 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -67,17 +67,17 @@ produced incorrect results if you gave these options.
 	have been completed, or to save the marks table across
 	incremental runs.  As <file> is only opened and truncated
 	at completion, the same path can also be safely given to
-	\--import-marks.
+	--import-marks.
 	The file will not be written if no new object has been
 	marked/exported.
 
 --import-marks=<file>::
 	Before processing any input, load the marks specified in
 	<file>.  The input file must exist, must be readable, and
-	must use the same format as produced by \--export-marks.
+	must use the same format as produced by --export-marks.
 +
 Any commits that have already been marked will not be exported again.
-If the backend uses a similar \--import-marks file, this allows for
+If the backend uses a similar --import-marks file, this allows for
 incremental bidirectional exporting of the repository by keeping the
 marks the same across runs.
 
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index bf7fbd4..fd32895 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -42,13 +42,13 @@ OPTIONS
 --quiet::
 	Disable all non-fatal output, making fast-import silent when it
 	is successful.  This option disables the output shown by
-	\--stats.
+	--stats.
 
 --stats::
 	Display some basic statistics about the objects fast-import has
 	created, the packfiles they were stored into, and the
 	memory used by fast-import during this run.  Showing this output
-	is currently the default, but can be disabled with \--quiet.
+	is currently the default, but can be disabled with --quiet.
 
 Options for Frontends
 ~~~~~~~~~~~~~~~~~~~~~
@@ -81,12 +81,12 @@ Locations of Marks Files
 	have been completed, or to save the marks table across
 	incremental runs.  As <file> is only opened and truncated
 	at checkpoint (or completion) the same path can also be
-	safely given to \--import-marks.
+	safely given to --import-marks.
 
 --import-marks=<file>::
 	Before processing any input, load the marks specified in
 	<file>.  The input file must exist, must be readable, and
-	must use the same format as produced by \--export-marks.
+	must use the same format as produced by --export-marks.
 	Multiple options may be supplied to import more than one
 	set of marks.  If a mark is defined to different values,
 	the last file wins.
@@ -179,8 +179,8 @@ fast-forward update, fast-import will skip updating that ref and instead
 prints a warning message.  fast-import will always attempt to update all
 branch refs, and does not stop on the first failure.
 
-Branch updates can be forced with \--force, but it's recommended that
-this only be used on an otherwise quiet repository.  Using \--force
+Branch updates can be forced with --force, but it's recommended that
+this only be used on an otherwise quiet repository.  Using --force
 is not necessary for an initial import into an empty repository.
 
 
@@ -231,11 +231,11 @@ Date Formats
 ~~~~~~~~~~~~
 The following date formats are supported.  A frontend should select
 the format it will use for this import by passing the format name
-in the \--date-format=<fmt> command-line option.
+in the --date-format=<fmt> command-line option.
 
 `raw`::
 	This is the Git native format and is `<time> SP <offutc>`.
-	It is also fast-import's default format, if \--date-format was
+	It is also fast-import's default format, if --date-format was
 	not specified.
 +
 The time of the event is specified by `<time>` as the number of
@@ -437,7 +437,7 @@ the email address from the other fields in the line.  Note that
 of bytes, except `LT`, `GT` and `LF`.  `<name>` is typically UTF-8 encoded.
 
 The time of the change is specified by `<when>` using the date format
-that was selected by the \--date-format=<fmt> command-line option.
+that was selected by the --date-format=<fmt> command-line option.
 See ``Date Formats'' above for the set of supported formats, and
 their syntax.
 
@@ -888,7 +888,7 @@ save out all current branch refs, tags and marks.
 ....
 
 Note that fast-import automatically switches packfiles when the current
-packfile reaches \--max-pack-size, or 4 GiB, whichever limit is
+packfile reaches --max-pack-size, or 4 GiB, whichever limit is
 smaller.  During an automatic packfile switch fast-import does not update
 the branch refs, tags or marks.
 
@@ -1226,7 +1226,7 @@ users of fast-import, and are offered here as suggestions.
 Use One Mark Per Commit
 ~~~~~~~~~~~~~~~~~~~~~~~
 When doing a repository conversion, use a unique mark per commit
-(`mark :<n>`) and supply the \--export-marks option on the command
+(`mark :<n>`) and supply the --export-marks option on the command
 line.  fast-import will dump a file which lists every mark and the Git
 object SHA-1 that corresponds to it.  If the frontend can tie
 the marks back to the source repository, it is easy to verify the
@@ -1291,7 +1291,7 @@ even for considerably large projects (100,000+ commits).
 
 However repacking the repository is necessary to improve data
 locality and access performance.  It can also take hours on extremely
-large projects (especially if -f and a large \--window parameter is
+large projects (especially if -f and a large --window parameter is
 used).  Since repacking is safe to run alongside readers and writers,
 run the repack in the background and let it finish when it finishes.
 There is no reason to wait to explore your new Git project!
@@ -1305,7 +1305,7 @@ Repacking Historical Data
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 If you are repacking very old imported data (e.g. older than the
 last year), consider expending some extra CPU time and supplying
-\--window=50 (or higher) when you run 'git repack'.
+--window=50 (or higher) when you run 'git repack'.
 This will take longer, but will also produce a smaller packfile.
 You only need to expend the effort once, and everyone using your
 project will benefit from the smaller repository.
@@ -1407,7 +1407,7 @@ branch, their in-memory storage size can grow to a considerable size
 fast-import automatically moves active branches to inactive status based on
 a simple least-recently-used algorithm.  The LRU chain is updated on
 each `commit` command.  The maximum number of active branches can be
-increased or decreased on the command line with \--active-branches=.
+increased or decreased on the command line with --active-branches=.
 
 per active tree
 ~~~~~~~~~~~~~~~
diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
index 93b5067..8680f45 100644
--- a/Documentation/git-fetch-pack.txt
+++ b/Documentation/git-fetch-pack.txt
@@ -80,7 +80,7 @@ be in a separate packet, and the list must end with a flush packet.
 	the things up in .bash_profile).
 
 --exec=<git-upload-pack>::
-	Same as \--upload-pack=<git-upload-pack>.
+	Same as --upload-pack=<git-upload-pack>.
 
 --depth=<n>::
 	Limit fetching to ancestor-chains not longer than n.
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index c2f76fb..bbea529 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -192,7 +192,7 @@ self-contained. Use `git index-pack --fix-thin`
 
 --shallow::
 	Optimize a pack that will be provided to a client with a shallow
-	repository.  This option, combined with \--thin, can result in a
+	repository.  This option, combined with --thin, can result in a
 	smaller pack at the cost of speed.
 
 --delta-base-offset::
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 863c30c..135d810 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -265,8 +265,8 @@ origin +master` to force a push to the `master` branch). See the
 
 --[no-]verify::
 	Toggle the pre-push hook (see linkgit:githooks[5]).  The
-	default is \--verify, giving the hook a chance to prevent the
-	push.  With \--no-verify, the hook is bypassed completely.
+	default is --verify, giving the hook a chance to prevent the
+	push.  With --no-verify, the hook is bypassed completely.
 
 
 include::urls-remotes.txt[]
diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
index 5b11922..b10ea60 100644
--- a/Documentation/git-rev-list.txt
+++ b/Documentation/git-rev-list.txt
@@ -9,54 +9,54 @@ git-rev-list - Lists commit objects in reverse chronological order
 SYNOPSIS
 --------
 [verse]
-'git rev-list' [ \--max-count=<number> ]
-	     [ \--skip=<number> ]
-	     [ \--max-age=<timestamp> ]
-	     [ \--min-age=<timestamp> ]
-	     [ \--sparse ]
-	     [ \--merges ]
-	     [ \--no-merges ]
-	     [ \--min-parents=<number> ]
-	     [ \--no-min-parents ]
-	     [ \--max-parents=<number> ]
-	     [ \--no-max-parents ]
-	     [ \--first-parent ]
-	     [ \--remove-empty ]
-	     [ \--full-history ]
-	     [ \--not ]
-	     [ \--all ]
-	     [ \--branches[=<pattern>] ]
-	     [ \--tags[=<pattern>] ]
-	     [ \--remotes[=<pattern>] ]
-	     [ \--glob=<glob-pattern> ]
-	     [ \--ignore-missing ]
-	     [ \--stdin ]
-	     [ \--quiet ]
-	     [ \--topo-order ]
-	     [ \--parents ]
-	     [ \--timestamp ]
-	     [ \--left-right ]
-	     [ \--left-only ]
-	     [ \--right-only ]
-	     [ \--cherry-mark ]
-	     [ \--cherry-pick ]
-	     [ \--encoding=<encoding> ]
-	     [ \--(author|committer|grep)=<pattern> ]
-	     [ \--regexp-ignore-case | -i ]
-	     [ \--extended-regexp | -E ]
-	     [ \--fixed-strings | -F ]
-	     [ \--date=(local|relative|default|iso|iso-strict|rfc|short) ]
-	     [ [ \--objects | \--objects-edge | \--objects-edge-aggressive ]
-	       [ \--unpacked ] ]
-	     [ \--pretty | \--header ]
-	     [ \--bisect ]
-	     [ \--bisect-vars ]
-	     [ \--bisect-all ]
-	     [ \--merge ]
-	     [ \--reverse ]
-	     [ \--walk-reflogs ]
-	     [ \--no-walk ] [ \--do-walk ]
-	     [ \--use-bitmap-index ]
+'git rev-list' [ --max-count=<number> ]
+	     [ --skip=<number> ]
+	     [ --max-age=<timestamp> ]
+	     [ --min-age=<timestamp> ]
+	     [ --sparse ]
+	     [ --merges ]
+	     [ --no-merges ]
+	     [ --min-parents=<number> ]
+	     [ --no-min-parents ]
+	     [ --max-parents=<number> ]
+	     [ --no-max-parents ]
+	     [ --first-parent ]
+	     [ --remove-empty ]
+	     [ --full-history ]
+	     [ --not ]
+	     [ --all ]
+	     [ --branches[=<pattern>] ]
+	     [ --tags[=<pattern>] ]
+	     [ --remotes[=<pattern>] ]
+	     [ --glob=<glob-pattern> ]
+	     [ --ignore-missing ]
+	     [ --stdin ]
+	     [ --quiet ]
+	     [ --topo-order ]
+	     [ --parents ]
+	     [ --timestamp ]
+	     [ --left-right ]
+	     [ --left-only ]
+	     [ --right-only ]
+	     [ --cherry-mark ]
+	     [ --cherry-pick ]
+	     [ --encoding=<encoding> ]
+	     [ --(author|committer|grep)=<pattern> ]
+	     [ --regexp-ignore-case | -i ]
+	     [ --extended-regexp | -E ]
+	     [ --fixed-strings | -F ]
+	     [ --date=(local|relative|default|iso|iso-strict|rfc|short) ]
+	     [ [ --objects | --objects-edge | --objects-edge-aggressive ]
+	       [ --unpacked ] ]
+	     [ --pretty | --header ]
+	     [ --bisect ]
+	     [ --bisect-vars ]
+	     [ --bisect-all ]
+	     [ --merge ]
+	     [ --reverse ]
+	     [ --walk-reflogs ]
+	     [ --no-walk ] [ --do-walk ]
+	     [ --use-bitmap-index ]
 	     <commit>... [ \-- <paths>... ]
 
 DESCRIPTION
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 52e6826..c483100 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -147,7 +147,7 @@ can be used.
 	form as close to the original input as possible.
 
 --symbolic-full-name::
-	This is similar to \--symbolic, but it omits input that
+	This is similar to --symbolic, but it omits input that
 	are not refs (i.e. branch or tag names; or more
 	explicitly disambiguating "heads/master" form, when you
 	want to name the "master" branch when there is an
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 45c7725..b5d09f7 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -29,7 +29,7 @@ OPTIONS
 	a directory on the default $PATH.
 
 --exec=<git-receive-pack>::
-	Same as \--receive-pack=<git-receive-pack>.
+	Same as --receive-pack=<git-receive-pack>.
 
 --all::
 	Instead of explicitly specifying which refs to update,
diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index 4e617e6..82a4125 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt
@@ -22,7 +22,7 @@ presents the merge commit in a special format as produced by
 For tags, it shows the tag message and the referenced objects.
 
 For trees, it shows the names (equivalent to 'git ls-tree'
-with \--name-only).
+with --name-only).
 
 For plain blobs, it shows the plain contents.
 
diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
index c8b3e51..c579593 100644
--- a/Documentation/gitdiffcore.txt
+++ b/Documentation/gitdiffcore.txt
@@ -28,8 +28,8 @@ The 'git diff-{asterisk}' family works by first comparing two sets of
 files:
 
  - 'git diff-index' compares contents of a "tree" object and the
-   working directory (when '\--cached' flag is not used) or a
-   "tree" object and the index file (when '\--cached' flag is
+   working directory (when '--cached' flag is not used) or a
+   "tree" object and the index file (when '--cached' flag is
    used);
 
  - 'git diff-files' compares contents of the index file and the
@@ -142,7 +142,7 @@ merges these filepairs and creates:
 
 When the "-C" option is used, the original contents of modified files,
 and deleted files (and also unmodified files, if the
-"\--find-copies-harder" option is used) are considered as candidates
+"--find-copies-harder" option is used) are considered as candidates
 of the source files in rename/copy operation.  If the input were like
 these filepairs, that talk about a modified file fileY and a newly
 created file file0:
-- 
2.4.0.192.g5f8138b

[PATCH 7/8] doc: drop backslash quoting of some curly braces

[Jeff King]

Text like "{foo}" triggers an AsciiDoc attribute; we have to
write "\{foo}" to suppress this. But when the "foo" is not a
syntactically valid attribute, we can skip the quoting. This
makes the source nicer to read, and looks better under
Asciidoctor. With AsciiDoc itself, this patch produces no
changes.

Signed-off-by: Jeff King <peff@peff.net>
---
Same arguments apply as the last commit. I split this out because unlike
the "--foo" thing, I don't actually know what version of AsciiDoc
changed this rule (if it was ever in fact necessary). So this one is
slightly riskier.

 Documentation/gitremote-helpers.txt | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt
index 8edf72c..82e2d15 100644
--- a/Documentation/gitremote-helpers.txt
+++ b/Documentation/gitremote-helpers.txt
@@ -408,14 +408,14 @@ set by Git if the remote helper has the 'option' capability.
 	of <n> correspond to the number of -v flags passed on the
 	command line.
 
-'option progress' \{'true'|'false'\}::
+'option progress' {'true'|'false'}::
 	Enables (or disables) progress messages displayed by the
 	transport helper during a command.
 
 'option depth' <depth>::
 	Deepens the history of a shallow repository.
 
-'option followtags' \{'true'|'false'\}::
+'option followtags' {'true'|'false'}::
 	If enabled the helper should automatically fetch annotated
 	tag objects if the object the tag points at was transferred
 	during the fetch command.  If the tag is not fetched by
@@ -423,7 +423,7 @@ set by Git if the remote helper has the 'option' capability.
 	ask for the tag specifically.  Some helpers may be able to
 	use this option to avoid a second network connection.
 
-'option dry-run' \{'true'|'false'\}:
+'option dry-run' {'true'|'false'}:
 	If true, pretend the operation completed successfully,
 	but don't actually change any repository data.	For most
 	helpers this only applies to the 'push', if supported.
@@ -434,18 +434,18 @@ set by Git if the remote helper has the 'option' capability.
 	must not rely on this option being set before
 	connect request occurs.
 
-'option check-connectivity' \{'true'|'false'\}::
+'option check-connectivity' {'true'|'false'}::
 	Request the helper to check connectivity of a clone.
 
-'option force' \{'true'|'false'\}::
+'option force' {'true'|'false'}::
 	Request the helper to perform a force update.  Defaults to
 	'false'.
 
-'option cloning \{'true'|'false'\}::
+'option cloning {'true'|'false'}::
 	Notify the helper this is a clone request (i.e. the current
 	repository is guaranteed empty).
 
-'option update-shallow \{'true'|'false'\}::
+'option update-shallow {'true'|'false'}::
 	Allow to extend .git/shallow if the new refs require it.
 
 SEE ALSO
-- 
2.4.0.192.g5f8138b

[PATCH 8/8] doc: put example URLs and emails inside literal backticks

[Jeff King]

This makes sure that AsciiDoc does not turn them into links.
Regular AsciiDoc does not catch these cases, but AsciiDoctor
does treat them as links.

Signed-off-by: Jeff King <peff@peff.net>
---
Note that this _does_ change the output in AsciiDoc, because we convert
other forms of quotes into backticks. For HTML, that gets us a
typewriter font, and if you have MAN_BOLD_LITERAL, it gets you bold in
the manpages. If we really prefer the emphasis, I think we'd have to
manually escape it.  This seems to work with "\http://" in AsciiDoc, but
that doesn't work for AsciiDoctor.

So we may want to just drop this until we better figure out AsciiDoctor
escaping.

 Documentation/git-http-backend.txt | 4 ++--
 Documentation/git-svn.txt          | 4 ++--
 Documentation/git-tag.txt          | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt
index d422ba4..3ca18c4 100644
--- a/Documentation/git-http-backend.txt
+++ b/Documentation/git-http-backend.txt
@@ -65,8 +65,8 @@ automatically by the web server.
 
 EXAMPLES
 --------
-All of the following examples map 'http://$hostname/git/foo/bar.git'
-to '/var/www/git/foo/bar.git'.
+All of the following examples map `http://$hostname/git/foo/bar.git`
+to `/var/www/git/foo/bar.git`.
 
 Apache 2.x::
 	Ensure mod_cgi, mod_alias, and mod_env are enabled, set
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 1377008..11d1e2f 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -70,8 +70,8 @@ COMMANDS
 --username=<user>;;
 	For transports that SVN handles authentication for (http,
 	https, and plain svn), specify the username.  For other
-	transports (e.g. svn+ssh://), you must include the username in
-	the URL, e.g. svn+ssh://foo@svn.bar.com/project
+	transports (e.g. `svn+ssh://`), you must include the username in
+	the URL, e.g. `svn+ssh://foo@svn.bar.com/project`
 --prefix=<prefix>;;
 	This allows one to specify a prefix which is prepended
 	to the names of remotes if trunk/branches/tags are
diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index f5b267e..034d10d 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -158,7 +158,7 @@ This option is only applicable when listing tags without annotation lines.
 CONFIGURATION
 -------------
 By default, 'git tag' in sign-with-default mode (-s) will use your
-committer identity (of the form "Your Name <\your@email.address>") to
+committer identity (of the form `Your Name <your@email.address>`) to
 find a key.  If you want to use a different default key, you can specify
 it in the repository configuration as follows:
 
-- 
2.4.0.192.g5f8138b

Re: [PATCH 0/8] asciidoc fixups

[Jeff King]

On Wed, May 13, 2015 at 12:56:50AM -0400, Jeff King wrote:

>   - Lots of places where we backslash-escape some syntax for AsciiDoc
>     ends up rendered by AsciiDoctor with the backslashes included. In
>     some cases the quoting is unnecessary and we can drop it (see
>     patches 6 and 7 below). But in others it really is necessary, and
>     AsciiDoc generates bad output without the backslashes. The major
>     ones are "--" surrounded by spaces (which becomes an emdash), and
>     things like @\{HEAD}, which needs quoted to tell AsciiDoc that HEAD
>     isn't an attribute.

That example should be HEAD@\{yesterday}, of course, but I think you get
the point.

>   [1/8]: doc: fix misrendering due to `single quote'
>   [2/8]: doc: fix unquoted use of "{type}"
>   [3/8]: doc: fix hanging "+"-continuation
>   [4/8]: doc: fix length of underlined section-title
>   [5/8]: doc/add: reformat `--edit` option
>   [6/8]: doc: convert \--option to --option
>   [7/8]: doc: drop backslash quoting of some curly braces
>   [8/8]: doc: put example URLs inside literal backticks

While reviewing the changes to the output, I found this script, which
shows the diff of the rendered HTML against the parent, very valuable:

    #!/bin/sh
    
    me=$(git rev-parse HEAD^{tree})
    parent=$(git rev-parse HEAD^^{tree})
    
    build() {
    	test -d build/$1 && return 0
    	mkdir -p build/tmp &&
    	make -j16 html &&
    	cp *.html build/tmp &&
    	mv build/tmp build/$1
    }
    
    check() {
    	test -d build/$1 && return 0
    	echo >&2 "doc for $1 not built"
    	return 1
    }
    
    build $me &&
    check $parent &&
    diff -Nru -I'^ 2015-05' build/$parent build/$me

I basically stopped at each commit in an interactive rebase and checked
the output (to confirm that it was sane, and especially to confirm the
cases where I claimed there should be no changes to the output).

-Peff

Re: [PATCH 0/8] asciidoc fixups

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Here are the patches. They do not include the code-fence fixes from
> Jean-Noel and myself that were already posted, but could easily go on
> top.

Thanks. Will queue.

Why are you guys using AsciiDoctor again?  Speed over accuracy is an
acceptable answer, as I know how slow my documentation codechain is.

Re: [PATCH 0/8] asciidoc fixups

[Jeff King]

On Tue, May 12, 2015 at 10:23:47PM -0700, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > Here are the patches. They do not include the code-fence fixes from
> > Jean-Noel and myself that were already posted, but could easily go on
> > top.
> 
> Thanks. Will queue.
> 
> Why are you guys using AsciiDoctor again?  Speed over accuracy is an
> acceptable answer, as I know how slow my documentation codechain is.

I'm not sure who "you guys" is. I do not use AsciiDoctor locally, though
I would be happy to see it mature to a point where that is feasible
(because it's way faster, and also because it seems like a much more
active project at this point; it may have more bugs, but the rate of
fixing means it should overtake python AsciiDoc at some point).

If it is "why does git-scm.com use it", I think it is that python
AsciiDoc was hard to embed in a web app. AsciiDoctor started as
git-scm.com's home-grown "just enough asciidoc to render the git
manpages" library, and grew from there. I don't know why they didn't
make a decision to just pre-render outside the app for each version. I
didn't pay much attention at the time.

-Peff

Re: [PATCH 0/8] asciidoc fixups

[Johannes Schindelin]

Hi,

On 2015-05-13 07:37, Jeff King wrote:
> On Tue, May 12, 2015 at 10:23:47PM -0700, Junio C Hamano wrote:
> 
>> Jeff King <peff@peff.net> writes:
>>
>> > Here are the patches. They do not include the code-fence fixes from
>> > Jean-Noel and myself that were already posted, but could easily go on
>> > top.
>>
>> Thanks. Will queue.
>>
>> Why are you guys using AsciiDoctor again?  Speed over accuracy is an
>> acceptable answer, as I know how slow my documentation codechain is.
> 
> I'm not sure who "you guys" is.

I would like to believe that I am included in said group, because we recently switched to use AsciiDoctor in Git for Windows 2.x. In msysGit times, we could not even run AsciiDoc (and neither AsciiDoctor), instead we relied on Junio publishing the artifacts in the git-htmldocs repository.

The difference of speed is noticable, although it has to be pointed out that compiling the documentation still takes roughly 5x (!!!) as long as compiling Git's source code itself.

By the way, we have two patches in our fork that are needed here to use Asciidoctor successfully: https://github.com/git-for-windows/git/compare/893292c41%5E...893292c41%5E2

I would like to put them on top of this patch series. Objections?

Ciao,
Dscho

Re: [PATCH 6/8] doc: convert \--option to --option

[John Keeping]

On Wed, May 13, 2015 at 01:01:38AM -0400, Jeff King wrote:
> Older versions of AsciiDoc would convert the "--" in
> "--option" into an emdash. According to 565e135
> (Documentation: quote double-dash for AsciiDoc, 2011-06-29),
> this is fixed in AsciiDoc 8.3.0. According to bf17126, we
> don't support anything older than 8.4.1 anyway, so we no
> longer need to worry about quoting.
> 
> Even though this does not change the output at all, there
> are a few good reasons to drop the quoting:
> 
>   1. It makes the source prettier to read.
> 
>   2. We don't quote consistently, which may be confusing when
>      reading the source.
> 
>   3. Asciidoctor does not like the quoting, and renders a
>      literal backslash.
> 
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> So this is the first of the more questionable patches, simply because we
> are appeasing Asciidoctor, but not fixing the root problem (i.e., there
> are still lots of places where the backslash quoting is messed up, like
> HEAD@\{yesterday}). So I suspect we need to figure that problem out, and
> then the asciidoctor issues will just go away. However, I think this may
> be worth doing just to prettify the source.

If we're changing all of these files anyway, it would be nice to wrap
literal options in backticks as suggested in
Documentation/CodingGuidelines.

>  Documentation/config.txt           | 10 ++--
>  Documentation/git-fast-export.txt  |  6 +--
>  Documentation/git-fast-import.txt  | 28 +++++------
>  Documentation/git-fetch-pack.txt   |  2 +-
>  Documentation/git-pack-objects.txt |  2 +-
>  Documentation/git-push.txt         |  4 +-
>  Documentation/git-rev-list.txt     | 96 +++++++++++++++++++-------------------
>  Documentation/git-rev-parse.txt    |  2 +-
>  Documentation/git-send-pack.txt    |  2 +-
>  Documentation/git-show.txt         |  2 +-
>  Documentation/gitdiffcore.txt      |  6 +--
>  11 files changed, 80 insertions(+), 80 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 948b8b0..e5d2ace 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -2279,18 +2279,18 @@ remote.<name>.skipFetchAll::
>  
>  remote.<name>.receivepack::
>  	The default program to execute on the remote side when pushing.  See
> -	option \--receive-pack of linkgit:git-push[1].
> +	option --receive-pack of linkgit:git-push[1].
>  
>  remote.<name>.uploadpack::
>  	The default program to execute on the remote side when fetching.  See
> -	option \--upload-pack of linkgit:git-fetch-pack[1].
> +	option --upload-pack of linkgit:git-fetch-pack[1].
>  
>  remote.<name>.tagOpt::
> -	Setting this value to \--no-tags disables automatic tag following when
> -	fetching from remote <name>. Setting it to \--tags will fetch every
> +	Setting this value to --no-tags disables automatic tag following when
> +	fetching from remote <name>. Setting it to --tags will fetch every
>  	tag from remote <name>, even if they are not reachable from remote
>  	branch heads. Passing these flags directly to linkgit:git-fetch[1] can
> -	override this setting. See options \--tags and \--no-tags of
> +	override this setting. See options --tags and --no-tags of
>  	linkgit:git-fetch[1].
>  
>  remote.<name>.vcs::
> diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
> index 929e496..ed57c68 100644
> --- a/Documentation/git-fast-export.txt
> +++ b/Documentation/git-fast-export.txt
> @@ -67,17 +67,17 @@ produced incorrect results if you gave these options.
>  	have been completed, or to save the marks table across
>  	incremental runs.  As <file> is only opened and truncated
>  	at completion, the same path can also be safely given to
> -	\--import-marks.
> +	--import-marks.
>  	The file will not be written if no new object has been
>  	marked/exported.
>  
>  --import-marks=<file>::
>  	Before processing any input, load the marks specified in
>  	<file>.  The input file must exist, must be readable, and
> -	must use the same format as produced by \--export-marks.
> +	must use the same format as produced by --export-marks.
>  +
>  Any commits that have already been marked will not be exported again.
> -If the backend uses a similar \--import-marks file, this allows for
> +If the backend uses a similar --import-marks file, this allows for
>  incremental bidirectional exporting of the repository by keeping the
>  marks the same across runs.
>  
> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
> index bf7fbd4..fd32895 100644
> --- a/Documentation/git-fast-import.txt
> +++ b/Documentation/git-fast-import.txt
> @@ -42,13 +42,13 @@ OPTIONS
>  --quiet::
>  	Disable all non-fatal output, making fast-import silent when it
>  	is successful.  This option disables the output shown by
> -	\--stats.
> +	--stats.
>  
>  --stats::
>  	Display some basic statistics about the objects fast-import has
>  	created, the packfiles they were stored into, and the
>  	memory used by fast-import during this run.  Showing this output
> -	is currently the default, but can be disabled with \--quiet.
> +	is currently the default, but can be disabled with --quiet.
>  
>  Options for Frontends
>  ~~~~~~~~~~~~~~~~~~~~~
> @@ -81,12 +81,12 @@ Locations of Marks Files
>  	have been completed, or to save the marks table across
>  	incremental runs.  As <file> is only opened and truncated
>  	at checkpoint (or completion) the same path can also be
> -	safely given to \--import-marks.
> +	safely given to --import-marks.
>  
>  --import-marks=<file>::
>  	Before processing any input, load the marks specified in
>  	<file>.  The input file must exist, must be readable, and
> -	must use the same format as produced by \--export-marks.
> +	must use the same format as produced by --export-marks.
>  	Multiple options may be supplied to import more than one
>  	set of marks.  If a mark is defined to different values,
>  	the last file wins.
> @@ -179,8 +179,8 @@ fast-forward update, fast-import will skip updating that ref and instead
>  prints a warning message.  fast-import will always attempt to update all
>  branch refs, and does not stop on the first failure.
>  
> -Branch updates can be forced with \--force, but it's recommended that
> -this only be used on an otherwise quiet repository.  Using \--force
> +Branch updates can be forced with --force, but it's recommended that
> +this only be used on an otherwise quiet repository.  Using --force
>  is not necessary for an initial import into an empty repository.
>  
>  
> @@ -231,11 +231,11 @@ Date Formats
>  ~~~~~~~~~~~~
>  The following date formats are supported.  A frontend should select
>  the format it will use for this import by passing the format name
> -in the \--date-format=<fmt> command-line option.
> +in the --date-format=<fmt> command-line option.
>  
>  `raw`::
>  	This is the Git native format and is `<time> SP <offutc>`.
> -	It is also fast-import's default format, if \--date-format was
> +	It is also fast-import's default format, if --date-format was
>  	not specified.
>  +
>  The time of the event is specified by `<time>` as the number of
> @@ -437,7 +437,7 @@ the email address from the other fields in the line.  Note that
>  of bytes, except `LT`, `GT` and `LF`.  `<name>` is typically UTF-8 encoded.
>  
>  The time of the change is specified by `<when>` using the date format
> -that was selected by the \--date-format=<fmt> command-line option.
> +that was selected by the --date-format=<fmt> command-line option.
>  See ``Date Formats'' above for the set of supported formats, and
>  their syntax.
>  
> @@ -888,7 +888,7 @@ save out all current branch refs, tags and marks.
>  ....
>  
>  Note that fast-import automatically switches packfiles when the current
> -packfile reaches \--max-pack-size, or 4 GiB, whichever limit is
> +packfile reaches --max-pack-size, or 4 GiB, whichever limit is
>  smaller.  During an automatic packfile switch fast-import does not update
>  the branch refs, tags or marks.
>  
> @@ -1226,7 +1226,7 @@ users of fast-import, and are offered here as suggestions.
>  Use One Mark Per Commit
>  ~~~~~~~~~~~~~~~~~~~~~~~
>  When doing a repository conversion, use a unique mark per commit
> -(`mark :<n>`) and supply the \--export-marks option on the command
> +(`mark :<n>`) and supply the --export-marks option on the command
>  line.  fast-import will dump a file which lists every mark and the Git
>  object SHA-1 that corresponds to it.  If the frontend can tie
>  the marks back to the source repository, it is easy to verify the
> @@ -1291,7 +1291,7 @@ even for considerably large projects (100,000+ commits).
>  
>  However repacking the repository is necessary to improve data
>  locality and access performance.  It can also take hours on extremely
> -large projects (especially if -f and a large \--window parameter is
> +large projects (especially if -f and a large --window parameter is
>  used).  Since repacking is safe to run alongside readers and writers,
>  run the repack in the background and let it finish when it finishes.
>  There is no reason to wait to explore your new Git project!
> @@ -1305,7 +1305,7 @@ Repacking Historical Data
>  ~~~~~~~~~~~~~~~~~~~~~~~~~
>  If you are repacking very old imported data (e.g. older than the
>  last year), consider expending some extra CPU time and supplying
> -\--window=50 (or higher) when you run 'git repack'.
> +--window=50 (or higher) when you run 'git repack'.
>  This will take longer, but will also produce a smaller packfile.
>  You only need to expend the effort once, and everyone using your
>  project will benefit from the smaller repository.
> @@ -1407,7 +1407,7 @@ branch, their in-memory storage size can grow to a considerable size
>  fast-import automatically moves active branches to inactive status based on
>  a simple least-recently-used algorithm.  The LRU chain is updated on
>  each `commit` command.  The maximum number of active branches can be
> -increased or decreased on the command line with \--active-branches=.
> +increased or decreased on the command line with --active-branches=.
>  
>  per active tree
>  ~~~~~~~~~~~~~~~
> diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt
> index 93b5067..8680f45 100644
> --- a/Documentation/git-fetch-pack.txt
> +++ b/Documentation/git-fetch-pack.txt
> @@ -80,7 +80,7 @@ be in a separate packet, and the list must end with a flush packet.
>  	the things up in .bash_profile).
>  
>  --exec=<git-upload-pack>::
> -	Same as \--upload-pack=<git-upload-pack>.
> +	Same as --upload-pack=<git-upload-pack>.
>  
>  --depth=<n>::
>  	Limit fetching to ancestor-chains not longer than n.
> diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
> index c2f76fb..bbea529 100644
> --- a/Documentation/git-pack-objects.txt
> +++ b/Documentation/git-pack-objects.txt
> @@ -192,7 +192,7 @@ self-contained. Use `git index-pack --fix-thin`
>  
>  --shallow::
>  	Optimize a pack that will be provided to a client with a shallow
> -	repository.  This option, combined with \--thin, can result in a
> +	repository.  This option, combined with --thin, can result in a
>  	smaller pack at the cost of speed.
>  
>  --delta-base-offset::
> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 863c30c..135d810 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -265,8 +265,8 @@ origin +master` to force a push to the `master` branch). See the
>  
>  --[no-]verify::
>  	Toggle the pre-push hook (see linkgit:githooks[5]).  The
> -	default is \--verify, giving the hook a chance to prevent the
> -	push.  With \--no-verify, the hook is bypassed completely.
> +	default is --verify, giving the hook a chance to prevent the
> +	push.  With --no-verify, the hook is bypassed completely.
>  
>  
>  include::urls-remotes.txt[]
> diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
> index 5b11922..b10ea60 100644
> --- a/Documentation/git-rev-list.txt
> +++ b/Documentation/git-rev-list.txt
> @@ -9,54 +9,54 @@ git-rev-list - Lists commit objects in reverse chronological order
>  SYNOPSIS
>  --------
>  [verse]
> -'git rev-list' [ \--max-count=<number> ]
> -	     [ \--skip=<number> ]
> -	     [ \--max-age=<timestamp> ]
> -	     [ \--min-age=<timestamp> ]
> -	     [ \--sparse ]
> -	     [ \--merges ]
> -	     [ \--no-merges ]
> -	     [ \--min-parents=<number> ]
> -	     [ \--no-min-parents ]
> -	     [ \--max-parents=<number> ]
> -	     [ \--no-max-parents ]
> -	     [ \--first-parent ]
> -	     [ \--remove-empty ]
> -	     [ \--full-history ]
> -	     [ \--not ]
> -	     [ \--all ]
> -	     [ \--branches[=<pattern>] ]
> -	     [ \--tags[=<pattern>] ]
> -	     [ \--remotes[=<pattern>] ]
> -	     [ \--glob=<glob-pattern> ]
> -	     [ \--ignore-missing ]
> -	     [ \--stdin ]
> -	     [ \--quiet ]
> -	     [ \--topo-order ]
> -	     [ \--parents ]
> -	     [ \--timestamp ]
> -	     [ \--left-right ]
> -	     [ \--left-only ]
> -	     [ \--right-only ]
> -	     [ \--cherry-mark ]
> -	     [ \--cherry-pick ]
> -	     [ \--encoding=<encoding> ]
> -	     [ \--(author|committer|grep)=<pattern> ]
> -	     [ \--regexp-ignore-case | -i ]
> -	     [ \--extended-regexp | -E ]
> -	     [ \--fixed-strings | -F ]
> -	     [ \--date=(local|relative|default|iso|iso-strict|rfc|short) ]
> -	     [ [ \--objects | \--objects-edge | \--objects-edge-aggressive ]
> -	       [ \--unpacked ] ]
> -	     [ \--pretty | \--header ]
> -	     [ \--bisect ]
> -	     [ \--bisect-vars ]
> -	     [ \--bisect-all ]
> -	     [ \--merge ]
> -	     [ \--reverse ]
> -	     [ \--walk-reflogs ]
> -	     [ \--no-walk ] [ \--do-walk ]
> -	     [ \--use-bitmap-index ]
> +'git rev-list' [ --max-count=<number> ]
> +	     [ --skip=<number> ]
> +	     [ --max-age=<timestamp> ]
> +	     [ --min-age=<timestamp> ]
> +	     [ --sparse ]
> +	     [ --merges ]
> +	     [ --no-merges ]
> +	     [ --min-parents=<number> ]
> +	     [ --no-min-parents ]
> +	     [ --max-parents=<number> ]
> +	     [ --no-max-parents ]
> +	     [ --first-parent ]
> +	     [ --remove-empty ]
> +	     [ --full-history ]
> +	     [ --not ]
> +	     [ --all ]
> +	     [ --branches[=<pattern>] ]
> +	     [ --tags[=<pattern>] ]
> +	     [ --remotes[=<pattern>] ]
> +	     [ --glob=<glob-pattern> ]
> +	     [ --ignore-missing ]
> +	     [ --stdin ]
> +	     [ --quiet ]
> +	     [ --topo-order ]
> +	     [ --parents ]
> +	     [ --timestamp ]
> +	     [ --left-right ]
> +	     [ --left-only ]
> +	     [ --right-only ]
> +	     [ --cherry-mark ]
> +	     [ --cherry-pick ]
> +	     [ --encoding=<encoding> ]
> +	     [ --(author|committer|grep)=<pattern> ]
> +	     [ --regexp-ignore-case | -i ]
> +	     [ --extended-regexp | -E ]
> +	     [ --fixed-strings | -F ]
> +	     [ --date=(local|relative|default|iso|iso-strict|rfc|short) ]
> +	     [ [ --objects | --objects-edge | --objects-edge-aggressive ]
> +	       [ --unpacked ] ]
> +	     [ --pretty | --header ]
> +	     [ --bisect ]
> +	     [ --bisect-vars ]
> +	     [ --bisect-all ]
> +	     [ --merge ]
> +	     [ --reverse ]
> +	     [ --walk-reflogs ]
> +	     [ --no-walk ] [ --do-walk ]
> +	     [ --use-bitmap-index ]
>  	     <commit>... [ \-- <paths>... ]
>  
>  DESCRIPTION
> diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
> index 52e6826..c483100 100644
> --- a/Documentation/git-rev-parse.txt
> +++ b/Documentation/git-rev-parse.txt
> @@ -147,7 +147,7 @@ can be used.
>  	form as close to the original input as possible.
>  
>  --symbolic-full-name::
> -	This is similar to \--symbolic, but it omits input that
> +	This is similar to --symbolic, but it omits input that
>  	are not refs (i.e. branch or tag names; or more
>  	explicitly disambiguating "heads/master" form, when you
>  	want to name the "master" branch when there is an
> diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
> index 45c7725..b5d09f7 100644
> --- a/Documentation/git-send-pack.txt
> +++ b/Documentation/git-send-pack.txt
> @@ -29,7 +29,7 @@ OPTIONS
>  	a directory on the default $PATH.
>  
>  --exec=<git-receive-pack>::
> -	Same as \--receive-pack=<git-receive-pack>.
> +	Same as --receive-pack=<git-receive-pack>.
>  
>  --all::
>  	Instead of explicitly specifying which refs to update,
> diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
> index 4e617e6..82a4125 100644
> --- a/Documentation/git-show.txt
> +++ b/Documentation/git-show.txt
> @@ -22,7 +22,7 @@ presents the merge commit in a special format as produced by
>  For tags, it shows the tag message and the referenced objects.
>  
>  For trees, it shows the names (equivalent to 'git ls-tree'
> -with \--name-only).
> +with --name-only).
>  
>  For plain blobs, it shows the plain contents.
>  
> diff --git a/Documentation/gitdiffcore.txt b/Documentation/gitdiffcore.txt
> index c8b3e51..c579593 100644
> --- a/Documentation/gitdiffcore.txt
> +++ b/Documentation/gitdiffcore.txt
> @@ -28,8 +28,8 @@ The 'git diff-{asterisk}' family works by first comparing two sets of
>  files:
>  
>   - 'git diff-index' compares contents of a "tree" object and the
> -   working directory (when '\--cached' flag is not used) or a
> -   "tree" object and the index file (when '\--cached' flag is
> +   working directory (when '--cached' flag is not used) or a
> +   "tree" object and the index file (when '--cached' flag is
>     used);
>  
>   - 'git diff-files' compares contents of the index file and the
> @@ -142,7 +142,7 @@ merges these filepairs and creates:
>  
>  When the "-C" option is used, the original contents of modified files,
>  and deleted files (and also unmodified files, if the
> -"\--find-copies-harder" option is used) are considered as candidates
> +"--find-copies-harder" option is used) are considered as candidates
>  of the source files in rename/copy operation.  If the input were like
>  these filepairs, that talk about a modified file fileY and a newly
>  created file file0:

Re: [PATCH] doc: fix unmatched code fences

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1195 bytes --]

On Wed, May 13, 2015 at 12:36:09AM -0400, Jeff King wrote:
> On Tue, May 12, 2015 at 09:32:45PM -0700, Junio C Hamano wrote:
> 
> > Jeff King <peff@peff.net> writes:
> > 
> > >> It obviously is not a title underline as the lengths are vastly
> > >> different.
> > >
> > > Yes, but Python Asciidoc allows the lengths to differ.
> > 
> > Hmmm, I thought the title underline was a bit more strict. I do
> > recall having to fix manual pages for many commands, but we do not
> > add new commands these days anymore, so perhaps things have changed
> > since then.
> 
> I think it is loose in AsciiDoc and strict in AsciiDoctor, so we have
> been slowly making sure they are all consistent. And we missed one,
> which will be in the series I'll send in a moment. :)
> 
> I suspect the potential ambiguity is one of the reasons that AsciiDoctor
> went with the stricter rule.

The Python implementation allows a difference of ±2, while Asciidoctor
only allows ±1.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH 0/8] asciidoc fixups

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 3990 bytes --]

On Wed, May 13, 2015 at 12:56:51AM -0400, Jeff King wrote:
> On Tue, May 12, 2015 at 10:15:56PM -0400, Jeff King wrote:
> 
> > You can build with asciidoctor on the command-line. I don't know if it
> > would be feasible to diff the asciidoc and asciidoctor output to look
> > for gratuitous differences (or if the output is so different due to
> > trivial stuff that the diff is unreadable).
> 
> So...it kind of works. I had to do unspeakable things with sed, and even
> then ended up with an 18,000-line "--color-words" diff.
> 
> Below are some fixes. The early ones are actual bugs in our sources. The
> latter ones are changes we could do to make asciidoctor happier. Each
> patch is independent, so we can take or leave whatever we want.

I've been in contact with Dan Allen, the lead on the Asciidoctor
project.  There are a few things that he pointed out.

> After this series, the remaining problems are:
> 
>   - asciidoctor does not render {litdd}, which is our invention; locally
>     this may be because I did not have the right incantation, but it is
>     also broken on git-scm.com. I think the right fix is to define that
>     attribute for the site renderer (so not a bug in our sources, and
>     not an asciidoctor bug)

I passed this as a command-line argument when using asciidoctor to
generate the docs: -a litdd=--.  For the site, I would recommend just
defining it there, as you suggested.

>   - in the '[verse]' section of the SYNOPSIS of each man page, AsciiDoc
>     renders 'git add' in the usual way (with emphasis). Whereas
>     AsciiDoctor renders it normally, with the literal quotes included.
> 
>     In the same [verse] section, AsciiDoctor does not convert literal
>     "..." into a fancy ellipsis. So perhaps it treats [verse] as a
>     section in which markup is not expanded? This may be related to the
>     [verseblock] stuff we have in our config file.

What you want here is [verse,subs=normal].  As of Asciidoctor 1.5.0,
this allows substitutions and markup within verse blocks.  I believe old
versions of AsciiDoc did not render substitutions and markup in verse
blocks, despite claiming to, and Asciidoctor picked up that behavior.

The set of patches I put in for Asciidoctor require at least 1.5.1
anyway in order to build man pages properly.

>   - We use "{attr? foo}" to display "foo" only when "attr" is set.
>     AsciiDoctor does not seem to understand this and renders the whole
>     string.

Yes, currently Asciidoctor doesn't support this.  Outside of
asciidoc.conf, which Asciidoctor doesn't read, it looks like there's
exactly two uses in diff-options.txt.  We could probably rewrite those
using an attribute.

>   - Lots of places where we backslash-escape some syntax for AsciiDoc
>     ends up rendered by AsciiDoctor with the backslashes included. In
>     some cases the quoting is unnecessary and we can drop it (see
>     patches 6 and 7 below). But in others it really is necessary, and
>     AsciiDoc generates bad output without the backslashes. The major
>     ones are "--" surrounded by spaces (which becomes an emdash), and
>     things like @\{HEAD}, which needs quoted to tell AsciiDoc that HEAD
>     isn't an attribute.
> 
>     I'm not sure of the solution (is AsciiDoctor just broken, or
>     is there some other syntax we could use that would work in both
>     places, or what?).

This is an under-defined area.  AsciiDoc and Asciidoctor both use
regexes instead of real parsers, and apparently there's some
disagreement on how these should be interpreted.  (The real solution is
to use a grammar and parser.) I think in some cases it might be
sufficient to use backticks, as those prevent further interpretation.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH 0/8] asciidoc fixups

[Jeff King]

On Wed, May 13, 2015 at 10:41:31PM +0000, brian m. carlson wrote:

> I've been in contact with Dan Allen, the lead on the Asciidoctor
> project.  There are a few things that he pointed out.

Thanks. I was hoping you would get involved. :)

> >   - asciidoctor does not render {litdd}, which is our invention; locally
> >     this may be because I did not have the right incantation, but it is
> >     also broken on git-scm.com. I think the right fix is to define that
> >     attribute for the site renderer (so not a bug in our sources, and
> >     not an asciidoctor bug)
> 
> I passed this as a command-line argument when using asciidoctor to
> generate the docs: -a litdd=--.  For the site, I would recommend just
> defining it there, as you suggested.

Yeah, I tried what you wrote earlier in [1], but it didn't work. But I
just realized it has misplaced quotes. Doing:

  make ... ASCIIDOC_EXTRA="-a 'litdd=--'"

seems to work OK.

[1] <1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net>
    (sorry no link, gmane seems down)

> >   - in the '[verse]' section of the SYNOPSIS of each man page, AsciiDoc
> >     renders 'git add' in the usual way (with emphasis). Whereas
> >     AsciiDoctor renders it normally, with the literal quotes included.
> 
> What you want here is [verse,subs=normal].  As of Asciidoctor 1.5.0,
> this allows substitutions and markup within verse blocks.  I believe old
> versions of AsciiDoc did not render substitutions and markup in verse
> blocks, despite claiming to, and Asciidoctor picked up that behavior.

That does work for AsciiDoctor, but sadly it seems to break rendering
for AsciiDoc, where it puts:

    <div class="attribution">
    &#8212; subs=normal
    </div>

in the middle of the SYNOPSIS. Yuck. Is there a way to make it work
under both? Or a way to configure AsciiDoctor verses to always use
"subs=normal"?

> >   - We use "{attr? foo}" to display "foo" only when "attr" is set.
> >     AsciiDoctor does not seem to understand this and renders the whole
> >     string.
> 
> Yes, currently Asciidoctor doesn't support this.  Outside of
> asciidoc.conf, which Asciidoctor doesn't read, it looks like there's
> exactly two uses in diff-options.txt.  We could probably rewrite those
> using an attribute.

I think they're already attributes, and it's just a magic syntax; I have
a trivial patch I'll send in a moment.

> >   - Lots of places where we backslash-escape some syntax for AsciiDoc
> >     ends up rendered by AsciiDoctor with the backslashes included.
> [...]
> 
> This is an under-defined area.  AsciiDoc and Asciidoctor both use
> regexes instead of real parsers, and apparently there's some
> disagreement on how these should be interpreted.  (The real solution is
> to use a grammar and parser.) I think in some cases it might be
> sufficient to use backticks, as those prevent further interpretation.

I actually prefer backticks in many cases, but they do come with their
own formatting. Surely there is a way in AsciiDoctor to say "do not
interpret this magically, but also do not format it as monospace"?

I guess the nuclear option is using attributes like {litdd} everywhere
to avoid quoting. But it makes the source so ugly and hard to read.

-Peff

Re: [PATCH 0/8] asciidoc fixups

[Jeff King]

On Wed, May 13, 2015 at 09:43:54AM +0200, Johannes Schindelin wrote:

> I would like to believe that I am included in said group, because we
> recently switched to use AsciiDoctor in Git for Windows 2.x. In
> msysGit times, we could not even run AsciiDoc (and neither
> AsciiDoctor), instead we relied on Junio publishing the artifacts in
> the git-htmldocs repository.

Thanks, I didn't know that. I have a vague feeling that AsciiDoctor is
the future of AsciiDoc (certainly the AsciiDoctor folks feel that way),
so the more we can keep compatibility, the better. Knowing that you guys
are actively using it makes me feel even better about spending time on
it.

> By the way, we have two patches in our fork that are needed here to
> use Asciidoctor successfully:
> https://github.com/git-for-windows/git/compare/893292c41%5E...893292c41%5E2
> 
> I would like to put them on top of this patch series. Objections?

The first one looks like straight fixes. The second looks rather nasty,
and makes the AsciiDoc output worse. I don't have a better solution
offhand, though. :(

-Peff

Re: [PATCH 6/8] doc: convert \--option to --option

[Jeff King]

On Wed, May 13, 2015 at 10:48:42AM +0100, John Keeping wrote:

> On Wed, May 13, 2015 at 01:01:38AM -0400, Jeff King wrote:
> > Older versions of AsciiDoc would convert the "--" in
> > "--option" into an emdash. According to 565e135
> > (Documentation: quote double-dash for AsciiDoc, 2011-06-29),
> > this is fixed in AsciiDoc 8.3.0. According to bf17126, we
> > don't support anything older than 8.4.1 anyway, so we no
> > longer need to worry about quoting.
> > 
> > Even though this does not change the output at all, there
> > are a few good reasons to drop the quoting:
> > 
> >   1. It makes the source prettier to read.
> > 
> >   2. We don't quote consistently, which may be confusing when
> >      reading the source.
> > 
> >   3. Asciidoctor does not like the quoting, and renders a
> >      literal backslash.
> 
> If we're changing all of these files anyway, it would be nice to wrap
> literal options in backticks as suggested in
> Documentation/CodingGuidelines.

I considered it, and I do prefer backticks. But I stopped short because
my goal here was to make source changes that didn't have any actual
output changes. So I'm not opposed to the output change, but it doesn't
belong in this patch.

I'm also a little hesitant just because it semes there are quite a lot
of outliers. I'm not sure if I'm helping anything to produce a patch
that changes a small subset of them (i.e., if we do it, we should really
do it thoroughly).

I dunno. If you want to do a patch on top, I'd be happy to look at it.

-Peff

[PATCH 9/8] doc: convert AsciiDoc {?foo} to ifdef::foo[]

[Jeff King]

The former seems to just be syntactic sugar for the latter.
And as it's sugar that AsciiDoctor doesn't understand, it
would be nice to avoid it. Since there are only two spots,
and the resulting source is not significantly harder to
read, it's worth doing.

Note that this does slightly affect the generated HTML (it
has an extra newline), but the rendered result for both HTML
and docbook should be the same (since the newline is not
syntactically significant there).

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/diff-options.txt | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index ccd4998..b7c3afe 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -23,7 +23,9 @@ ifndef::git-format-patch[]
 -u::
 --patch::
 	Generate patch (see section on generating patches).
-	{git-diff? This is the default.}
+ifdef::git-diff[]
+	This is the default.
+endif::git-diff[]
 endif::git-format-patch[]
 
 -s::
@@ -42,7 +44,9 @@ endif::git-format-patch[]
 ifndef::git-format-patch[]
 --raw::
 	Generate the raw format.
-	{git-diff-core? This is the default.}
+ifdef::git-diff-core[]
+	This is the default.
+endif::git-diff-core[]
 endif::git-format-patch[]
 
 ifndef::git-format-patch[]
-- 
2.4.0.327.ge28c153

Re: [PATCH 0/8] asciidoc fixups

[Johannes Schindelin]

Hi Brian and Peff,

On 2015-05-14 06:25, Jeff King wrote:
> On Wed, May 13, 2015 at 10:41:31PM +0000, brian m. carlson wrote:
> 
>> I've been in contact with Dan Allen, the lead on the Asciidoctor
>> project.  There are a few things that he pointed out.
> 
> Thanks. I was hoping you would get involved. :)
> 
>> >   - asciidoctor does not render {litdd}, which is our invention; locally
>> >     this may be because I did not have the right incantation, but it is
>> >     also broken on git-scm.com. I think the right fix is to define that
>> >     attribute for the site renderer (so not a bug in our sources, and
>> >     not an asciidoctor bug)
>>
>> I passed this as a command-line argument when using asciidoctor to
>> generate the docs: -a litdd=--.  For the site, I would recommend just
>> defining it there, as you suggested.
> 
> Yeah, I tried what you wrote earlier in [1], but it didn't work. But I
> just realized it has misplaced quotes. Doing:
> 
>   make ... ASCIIDOC_EXTRA="-a 'litdd=--'"
> 
> seems to work OK.

Oh darn, I really meant to include this link:

https://github.com/git-for-windows/MINGW-packages/blob/af36666c829f64847737e783c34ab20402030648/mingw-w64-git/PKGBUILD#L71

which documents how Git for Windows defines `litdd`.

Sorry!
Dscho

Re: [PATCH 0/8] asciidoc fixups

[Jeff King]

On Thu, May 14, 2015 at 09:43:56AM +0200, Johannes Schindelin wrote:

> > Yeah, I tried what you wrote earlier in [1], but it didn't work. But I
> > just realized it has misplaced quotes. Doing:
> > 
> >   make ... ASCIIDOC_EXTRA="-a 'litdd=--'"
> > 
> > seems to work OK.
> 
> Oh darn, I really meant to include this link:
> 
> https://github.com/git-for-windows/MINGW-packages/blob/af36666c829f64847737e783c34ab20402030648/mingw-w64-git/PKGBUILD#L71
> 
> which documents how Git for Windows defines `litdd`.

Hmm, you use the same "stuck" parameter -alitdd=..., whereas it only
worked for me with a space between the "-a" and the attribute. I wonder
if this is from different asciidoctor versions.

My asciidoctor just comes from the Debian package. Looks like it's over
a year old at this point. I should probably be testing with something
more recent.

-Peff

Re: [PATCH 0/8] asciidoc fixups

[Johannes Schindelin]

Hi Peff,

On 2015-05-14 19:38, Jeff King wrote:
> On Thu, May 14, 2015 at 09:43:56AM +0200, Johannes Schindelin wrote:
> 
>> > Yeah, I tried what you wrote earlier in [1], but it didn't work. But I
>> > just realized it has misplaced quotes. Doing:
>> >
>> >   make ... ASCIIDOC_EXTRA="-a 'litdd=--'"
>> >
>> > seems to work OK.
>>
>> Oh darn, I really meant to include this link:
>>
>> https://github.com/git-for-windows/MINGW-packages/blob/af36666c829f64847737e783c34ab20402030648/mingw-w64-git/PKGBUILD#L71
>>
>> which documents how Git for Windows defines `litdd`.
> 
> Hmm, you use the same "stuck" parameter -alitdd=..., whereas it only
> worked for me with a space between the "-a" and the attribute. I wonder
> if this is from different asciidoctor versions.
> 
> My asciidoctor just comes from the Debian package. Looks like it's over
> a year old at this point. I should probably be testing with something
> more recent.

We installed asciidoctor via `gem` and have version 1.5.2.

Ciao,
Dscho

Re: [PATCH 0/8] asciidoc fixups

[Junio C Hamano]

Johannes Schindelin <johannes.schindelin@gmx.de> writes:

>> My asciidoctor just comes from the Debian package. Looks like it's over
>> a year old at this point. I should probably be testing with something
>> more recent.
>
> We installed asciidoctor via `gem` and have version 1.5.2.

What I'll be pushing out today will have some "interesting" mark-up
in Documentation/git-cat-file.txt (on 'jch' or 'pu') from David's
'--follow-symlinks' topic.  I think AsciiDoc formatting looks OK,
but can you check it with both older (peff) and newer (dscho)
asciidoctor to see how well it shows?  Look for --follow-symlinks
in the output.

Thanks.

Re: [PATCH 0/8] asciidoc fixups

[Jeff King]

On Thu, May 14, 2015 at 02:10:53PM -0700, Junio C Hamano wrote:

> Johannes Schindelin <johannes.schindelin@gmx.de> writes:
> 
> >> My asciidoctor just comes from the Debian package. Looks like it's over
> >> a year old at this point. I should probably be testing with something
> >> more recent.
> >
> > We installed asciidoctor via `gem` and have version 1.5.2.
> 
> What I'll be pushing out today will have some "interesting" mark-up
> in Documentation/git-cat-file.txt (on 'jch' or 'pu') from David's
> '--follow-symlinks' topic.  I think AsciiDoc formatting looks OK,
> but can you check it with both older (peff) and newer (dscho)
> asciidoctor to see how well it shows?  Look for --follow-symlinks
> in the output.

What's in 366bc15e9 (your SQUASH) looks terrible with older asciidoctor.
The "[normal]" bumps us out of the list item, left-aligning all of the
other paragraphs, and then the "+" continuation is treated literally
(probably because we are not inside a block).

I don't see any reason we cannot use normal "+" continuation here (but
the hanging paragraphs need to be left-aligned, then).

-Peff

Re: [PATCH 0/8] asciidoc fixups

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Thu, May 14, 2015 at 02:10:53PM -0700, Junio C Hamano wrote:
>> 
>> What I'll be pushing out today will have some "interesting" mark-up
>> in Documentation/git-cat-file.txt (on 'jch' or 'pu') from David's
>> '--follow-symlinks' topic.  I think AsciiDoc formatting looks OK,
>> but can you check it with both older (peff) and newer (dscho)
>> asciidoctor to see how well it shows?  Look for --follow-symlinks
>> in the output.
>
> What's in 366bc15e9 (your SQUASH) looks terrible with older asciidoctor.
> The "[normal]" bumps us out of the list item, left-aligning all of the
> other paragraphs, and then the "+" continuation is treated literally
> (probably because we are not inside a block).
>
> I don't see any reason we cannot use normal "+" continuation here (but
> the hanging paragraphs need to be left-aligned, then).

The use of [normal] with indented subsequent paragraphs is what
David's patch changed from my earlier suggestion, which used the
ugly bog-standard "+ with unindented paragraphs"; I was afraid that
it may lead to a fallout like this X-<.

Thanks for checking.  David, I think we need a v12 after all.

Re: [PATCH 0/8] asciidoc fixups

[David Turner]

On Thu, 2015-05-14 at 14:40 -0700, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
> > On Thu, May 14, 2015 at 02:10:53PM -0700, Junio C Hamano wrote:
> >> 
> >> What I'll be pushing out today will have some "interesting" mark-up
> >> in Documentation/git-cat-file.txt (on 'jch' or 'pu') from David's
> >> '--follow-symlinks' topic.  I think AsciiDoc formatting looks OK,
> >> but can you check it with both older (peff) and newer (dscho)
> >> asciidoctor to see how well it shows?  Look for --follow-symlinks
> >> in the output.
> >
> > What's in 366bc15e9 (your SQUASH) looks terrible with older asciidoctor.
> > The "[normal]" bumps us out of the list item, left-aligning all of the
> > other paragraphs, and then the "+" continuation is treated literally
> > (probably because we are not inside a block).
> >
> > I don't see any reason we cannot use normal "+" continuation here (but
> > the hanging paragraphs need to be left-aligned, then).
> 
> The use of [normal] with indented subsequent paragraphs is what
> David's patch changed from my earlier suggestion, which used the
> ugly bog-standard "+ with unindented paragraphs"; I was afraid that
> it may lead to a fallout like this X-<.
> 
> Thanks for checking.  David, I think we need a v12 after all.

The reason I used [normal] is because + caused even non-code to be
inside <pre><code> in the HTML (when I run make doc, anyway).  But I see
that fixing the hanging paragraph's left-alignment fixes that problem.
So I will send a v12.

Re: [PATCH 0/8] asciidoc fixups

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1891 bytes --]

On Thu, May 14, 2015 at 12:25:44AM -0400, Jeff King wrote:
> On Wed, May 13, 2015 at 10:41:31PM +0000, brian m. carlson wrote:
> > What you want here is [verse,subs=normal].  As of Asciidoctor 1.5.0,
> > this allows substitutions and markup within verse blocks.  I believe old
> > versions of AsciiDoc did not render substitutions and markup in verse
> > blocks, despite claiming to, and Asciidoctor picked up that behavior.
> 
> That does work for AsciiDoctor, but sadly it seems to break rendering
> for AsciiDoc, where it puts:
> 
>     <div class="attribution">
>     &#8212; subs=normal
>     </div>
> 
> in the middle of the SYNOPSIS. Yuck. Is there a way to make it work
> under both? Or a way to configure AsciiDoctor verses to always use
> "subs=normal"?

Using Asciidoctor 1.5.0, it seems to work properly for me without
subs=normal.  So perhaps we should just update the version used for the
site.  I realize the Debian version is out of date; I've already filed a
bug.

> I actually prefer backticks in many cases, but they do come with their
> own formatting. Surely there is a way in AsciiDoctor to say "do not
> interpret this magically, but also do not format it as monospace"?
> 
> I guess the nuclear option is using attributes like {litdd} everywhere
> to avoid quoting. But it makes the source so ugly and hard to read.

I opened issue 1344[0] for this.  However, it looks like we can write
<refname>@+++{+++<date>+++}+++ instead of <refname>@\{<date>\} and it
will work correctly in both processors.  That looks to be a workaround,
as ugly and verbose as it is.

[0] https://github.com/asciidoctor/asciidoctor/issues/1344
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH 0/8] asciidoc fixups

[Jeff King]

On Fri, May 15, 2015 at 02:52:24AM +0000, brian m. carlson wrote:

> Using Asciidoctor 1.5.0, it seems to work properly for me without
> subs=normal.  So perhaps we should just update the version used for the
> site.  I realize the Debian version is out of date; I've already filed a
> bug.

I checked that it was broken on the site, but I didn't check to see how
ancient the version there was. And it is rather old. I've opened a PR[1]
to bump that.

> I opened issue 1344[0] for this.  However, it looks like we can write
> <refname>@+++{+++<date>+++}+++ instead of <refname>@\{<date>\} and it
> will work correctly in both processors.  That looks to be a workaround,
> as ugly and verbose as it is.

Yeah, I guess that works. But man, is it ugly. I'd love it if we can get
backslash-escaping in asciidoctor. Thanks for opening the issue.

-Peff

[1] https://github.com/git/git-scm.com/pull/545

Re: [PATCH 6/8] doc: convert \--option to --option

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, May 13, 2015 at 10:48:42AM +0100, John Keeping wrote:
>
>> If we're changing all of these files anyway, it would be nice to wrap
>> literal options in backticks as suggested in
>> Documentation/CodingGuidelines.
>
> I considered it, and I do prefer backticks. But I stopped short because
> my goal here was to make source changes that didn't have any actual
> output changes. So I'm not opposed to the output change, but it doesn't
> belong in this patch.
>
> I'm also a little hesitant just because it semes there are quite a lot
> of outliers. I'm not sure if I'm helping anything to produce a patch
> that changes a small subset of them (i.e., if we do it, we should really
> do it thoroughly).
>
> I dunno. If you want to do a patch on top, I'd be happy to look at it.

FWIW I agree 100% with what Peff said. `--options` is a good thing
to do, it does not belong to this patch, and we should aim to do so
for the entirety of the documentation, not just a small part.

The last one makes the execution of such a clean-up somewhat a
tricky affair.  We'd need to avoid conflicting with other topics in
flight (i.e. clean up quiet part of the documentation only), make
sure topics in flight do not add new breakages, and come back to
documentation other topics have changed once they stabilized.