[PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Martin Ågren]

These patches reduce

  ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD

from ~1200 to ~1000 lines. It's the usual mix of things where one or the
other of the tools renders something less well, or where we're doing
something odd in the source and we just happen to notice it in the diff.

My ulterior motive here is to have a smaller doc-diff when I post a
patch to switch the default to Asciidoctor (with xmlto), so that it gets
a bit easier to reason about. But if everybody gets prettier docs,
that's also good.

Some of these rephrase wording such as "other peoples' commits" to avoid
that apostrophe at the end of a word. I'm hoping those rephrasings don't
regress the quality of the text -- if they do, I'll be happy to try
something else.

Martin Ågren (6):
  git-http-push.txt,git-send-pack.txt: avoid single quote
  git-range-diff.txt: avoid single quotes
  git-check-ref-format.txt: avoid single quote
  diff-options.txt: move monospace markup out of attribute
  git-svn.txt: change verse to listing block
  Doc: use two backticks for monospace, not backtick+apostrophe

 Documentation/config/diff.txt          |  2 +-
 Documentation/diff-options.txt         |  2 +-
 Documentation/git-check-ignore.txt     |  2 +-
 Documentation/git-check-ref-format.txt |  6 +--
 Documentation/git-describe.txt         |  2 +-
 Documentation/git-http-push.txt        |  2 +-
 Documentation/git-log.txt              |  2 +-
 Documentation/git-range-diff.txt       |  6 +--
 Documentation/git-send-pack.txt        |  2 +-
 Documentation/git-show.txt             |  2 +-
 Documentation/git-svn.txt              | 51 +++++++++++++++++---------
 11 files changed, 47 insertions(+), 32 deletions(-)

-- 
2.31.1.751.gd2f1c929bd

[PATCH 1/6] git-http-push.txt,git-send-pack.txt: avoid single quote

[Martin Ågren]

AsciiDoc matches up the very first backtick with the single quote
towards the end, and renders that first backtick literally:

    `--force, ... other peoples' commits

Rewrite the "other peoples' commits" construction to drop the single
quote mark.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-http-push.txt | 2 +-
 Documentation/git-send-pack.txt | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-http-push.txt b/Documentation/git-http-push.txt
index ea03a4eeb0..cbb7d2de6d 100644
--- a/Documentation/git-http-push.txt
+++ b/Documentation/git-http-push.txt
@@ -85,7 +85,7 @@ Without `--force`, the <src> ref is stored at the remote only if
 <dst> does not exist, or <dst> is a proper subset (i.e. an
 ancestor) of <src>.  This check, known as "fast-forward check",
 is performed in order to avoid accidentally overwriting the
-remote ref and lose other peoples' commits from there.
+remote ref and losing commits of other people from there.
 
 With `--force`, the fast-forward check is disabled for all refs.
 
diff --git a/Documentation/git-send-pack.txt b/Documentation/git-send-pack.txt
index 44fd146b91..d8c8acb96e 100644
--- a/Documentation/git-send-pack.txt
+++ b/Documentation/git-send-pack.txt
@@ -144,7 +144,7 @@ Without `--force`, the <src> ref is stored at the remote only if
 <dst> does not exist, or <dst> is a proper subset (i.e. an
 ancestor) of <src>.  This check, known as "fast-forward check",
 is performed in order to avoid accidentally overwriting the
-remote ref and lose other peoples' commits from there.
+remote ref and losing commits of other people from there.
 
 With `--force`, the fast-forward check is disabled for all refs.
 
-- 
2.31.1.751.gd2f1c929bd

[PATCH 2/6] git-range-diff.txt: avoid single quotes

[Martin Ågren]

Similar to the previous commit, the use of backticks for monospacing and
a single quote as an apostrophe trip up AsciiDoc in two places which
render as follows:

    `git range-diff ... diffs' coloring

    ‘1` is ... commits' patches

Reword slighly to avoid those last single quotes.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-range-diff.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-range-diff.txt b/Documentation/git-range-diff.txt
index fe350d7f40..6e9a0ea6b6 100644
--- a/Documentation/git-range-diff.txt
+++ b/Documentation/git-range-diff.txt
@@ -45,7 +45,7 @@ OPTIONS
 -------
 --no-dual-color::
 	When the commit diffs differ, `git range-diff` recreates the
-	original diffs' coloring, and adds outer -/+ diff markers with
+	coloring of the original diffs, and adds outer -/+ diff markers with
 	the *background* being red/green to make it easier to see e.g.
 	when there was a change in what exact lines were added.
 +
@@ -239,8 +239,8 @@ because of the modification:
 In mathematical terms, what we are looking for is some sort of a minimum
 cost bipartite matching; `1` is matched to `C` at some cost, etc. The
 underlying graph is in fact a complete bipartite graph; the cost we
-associate with every edge is the size of the diff between the two
-commits' patches. To explain also new commits, we introduce dummy nodes
+associate with every edge is the size of the diff between the patches of
+the two commits. To explain also new commits, we introduce dummy nodes
 on both sides:
 
 ------------
-- 
2.31.1.751.gd2f1c929bd

[PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Martin Ågren]

Asciidoctor renders 'git cat-file' with the single quotes. It's somehow
tricked by the single quote in "srcref\'s" earler in the paragraph. If
we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite
things a bit to avoid "srcref's" entirely.

Add backticks for monospacing around these refs and command invocations
while at it.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-check-ref-format.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index ee6a4144fb..71d53ffb60 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -70,10 +70,10 @@ reference name expressions (see linkgit:gitrevisions[7]):
 . A tilde `~` and caret `^` are used to introduce the postfix
   'nth parent' and 'peel onion' operation.
 
-. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
-  value and store it in dstref" in fetch and push operations.
+. A colon `:` is used as in `srcref:dstref` to mean "use the value
+  of `srcref` and store it in `dstref`" in fetch and push operations.
   It may also be used to select a specific object such as with
-  'git cat-file': "git cat-file blob v1.3.3:refs.c".
+  'git cat-file': `git cat-file blob v1.3.3:refs.c`.
 
 . at-open-brace `@{` is used as a notation to access a reflog entry.
 
-- 
2.31.1.751.gd2f1c929bd

[PATCH 4/6] diff-options.txt: move monospace markup out of attribute

[Martin Ågren]

git-log.txt and git-show.txt want to use different defaults for the
`--no-diff-merges` option. They do this by defining a
"diff-merges-default" attribute as, e.g., `off` (with backticks), which
is then referenced in the common diff-options.txt.

AsciiDoc renders the default in monospace, as wanted, but Asciidoctor
renders the backticks literally.

Pull the formatting into diff-options.txt and define
"diff-merges-default" without any quotation or markup. We can't write
`{diff-merges-default)` with backticks since that would render as
"{diff-merges-default}", but we can use +{diff-merges-default}+ -- both
Asciidoc and Asciidoctor do the substitution and the parsing of the
plusses in the order we want.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/diff-options.txt | 2 +-
 Documentation/git-log.txt      | 2 +-
 Documentation/git-show.txt     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 530d115914..6eb8bfff5d 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -37,7 +37,7 @@ ifdef::git-log[]
 --diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc)::
 --no-diff-merges::
 	Specify diff format to be used for merge commits. Default is
-	{diff-merges-default} unless `--first-parent` is in use, in which case
+	+{diff-merges-default}+ unless `--first-parent` is in use, in which case
 	`first-parent` is the default.
 +
 --diff-merges=(off|none):::
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 1bbf865a1b..19560650bf 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -115,7 +115,7 @@ is when `--first-parent` is in use, in which case `first-parent` is
 the default format.
 
 :git-log: 1
-:diff-merges-default: `off`
+:diff-merges-default: off
 include::diff-options.txt[]
 
 include::diff-generate-patch.txt[]
diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index 2b1bc7288d..f8341e51c0 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt
@@ -51,7 +51,7 @@ The options below can be used to change the way `git show` generates
 diff output.
 
 :git-log: 1
-:diff-merges-default: `dense-combined`
+:diff-merges-default: dense-combined
 include::diff-options.txt[]
 
 include::diff-generate-patch.txt[]
-- 
2.31.1.751.gd2f1c929bd

[PATCH 5/6] git-svn.txt: change verse to listing block

[Martin Ågren]

Unlike AsciiDoc, Asciidoctor seems to leave out an empty line after a verse
in a list continuation:

  allow only certain refs.

       config key: svn-remote.<name>.ignore-refs
  If the ignore-refs configuration key is ...

We could probably convince Asciidoctor do this differently, but thinking
about it, there's no real reason for a "verse" here. We might as well
use a listing block.

This is the only place in our documentation that uses this "config key:
foo.bar" construction. We could rework it into prose ("This option
overrides the foo.bar configuration, which defaults to baz."). Right
now, let's just solve the immediate issue of the missing empty line when
we use Asciidoctor to generate the manpage.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/git-svn.txt | 45 ++++++++++++++++++++++++++-------------
 1 file changed, 30 insertions(+), 15 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index d5776ffcfd..4e62dc37e7 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -148,8 +148,9 @@ the same local time zone.
 	`^refs/remotes/origin/(?!tags/wanted-tag|wanted-branch).*$`
 	can be used to allow only certain refs.
 +
-[verse]
+------------
 config key: svn-remote.<name>.ignore-refs
+------------
 +
 If the ignore-refs configuration key is set, and the command-line
 option is also given, both regular expressions will be used.
@@ -161,8 +162,9 @@ option is also given, both regular expressions will be used.
 	(including automatic fetches due to 'clone', 'dcommit',
 	'rebase', etc) on a given repository.
 +
-[verse]
+------------
 config key: svn-remote.<name>.ignore-paths
+------------
 +
 If the ignore-paths configuration key is set, and the command-line
 option is also given, both regular expressions will be used.
@@ -191,8 +193,9 @@ Skip "branches" and "tags" of first level directories;;
 	'rebase', etc) on a given repository. `--ignore-paths` takes
 	precedence over `--include-paths`.
 +
-[verse]
+------------
 config key: svn-remote.<name>.include-paths
+------------
 
 --log-window-size=<n>;;
 	Fetch <n> log entries per request when scanning Subversion history.
@@ -267,9 +270,10 @@ Use of 'dcommit' is preferred to 'set-tree' (below).
 	reused if a user is later given access to an alternate transport
 	method (e.g. `svn+ssh://` or `https://`) for commit.
 +
-[verse]
+------------
 config key: svn-remote.<name>.commiturl
 config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)
+------------
 +
 Note that the SVN URL of the commiturl config key includes the SVN branch.
 If you rather want to set the commit URL for an entire SVN repository use
@@ -286,8 +290,9 @@ discouraged.
 	branches, use a single space character between the branches
 	(`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`)
 +
-[verse]
+------------
 config key: svn.pushmergeinfo
+------------
 +
 This option will cause git-svn to attempt to automatically populate the
 svn:mergeinfo property in the SVN repository when possible. Currently, this can
@@ -548,9 +553,10 @@ Assume you have local changes in "master", but you need to refetch "r2".
 Fix the ignore-paths or SVN permissions problem that caused "r2" to
 be incomplete in the first place.  Then:
 +
-[verse]
+------------
 git svn reset -r2 -p
 git svn fetch
+------------
 +
 ------------
     r1---r2'--r3' remotes/git-svn
@@ -562,8 +568,9 @@ Then fixup "master" with 'git rebase'.
 Do NOT use 'git merge' or your history will not be compatible with a
 future 'dcommit'!
 +
-[verse]
+------------
 git rebase --onto remotes/git-svn A^ master
+------------
 +
 ------------
     r1---r2'--r3' remotes/git-svn
@@ -608,8 +615,9 @@ removed by default if there are no files left in them.  Git
 cannot version empty directories.  Enabling this flag will make
 the commit to SVN act like Git.
 +
-[verse]
+------------
 config key: svn.rmdir
+------------
 
 -e::
 --edit::
@@ -619,8 +627,9 @@ Edit the commit message before committing to SVN.  This is off by
 default for objects that are commits, and forced on when committing
 tree objects.
 +
-[verse]
+------------
 config key: svn.edit
+------------
 
 -l<num>::
 --find-copies-harder::
@@ -629,9 +638,10 @@ config key: svn.edit
 They are both passed directly to 'git diff-tree'; see
 linkgit:git-diff-tree[1] for more information.
 +
-[verse]
+------------
 config key: svn.l
 config key: svn.findcopiesharder
+------------
 
 -A<filename>::
 --authors-file=<filename>::
@@ -648,8 +658,9 @@ will abort operation. The user will then have to add the
 appropriate entry.  Re-running the previous 'git svn' command
 after the authors-file is modified should continue operation.
 +
-[verse]
+------------
 config key: svn.authorsfile
+------------
 
 --authors-prog=<filename>::
 	If this option is specified, for each SVN committer name that
@@ -664,8 +675,9 @@ relative to the current directory for 'init' and 'clone' and relative
 to the root of the working tree for 'fetch'. If 'filename' is
 not found, it is searched like any other command in '$PATH'.
 +
-[verse]
+------------
 config key: svn.authorsProg
+------------
 
 -q::
 --quiet::
@@ -704,8 +716,9 @@ creating the branch or tag.
 	'dcommit' operations), look for the first `From:` line or `Signed-off-by` trailer
 	in the log message and use that as the author string.
 +
-[verse]
+------------
 config key: svn.useLogAuthor
+------------
 
 --add-author-from::
 	When committing to svn from Git (as part of 'set-tree' or 'dcommit'
@@ -714,8 +727,9 @@ config key: svn.useLogAuthor
 	Git commit's author string.  If you use this, then `--use-log-author`
 	will retrieve a valid author string for all commits.
 +
-[verse]
+------------
 config key: svn.addAuthorFrom
+------------
 
 ADVANCED OPTIONS
 ----------------
@@ -749,8 +763,9 @@ ADVANCED OPTIONS
 	process. This feature is enabled by default, use
 	--no-follow-parent to disable it.
 +
-[verse]
+------------
 config key: svn.followparent
+------------
 
 CONFIG FILE-ONLY OPTIONS
 ------------------------
-- 
2.31.1.751.gd2f1c929bd

[PATCH 6/6] Doc: use two backticks for monospace, not backtick+apostrophe

[Martin Ågren]

In a few places, we wrap the name of an --option or an ENV_VARIABLE in
backtick+apostrophe rather than backtick+backtick. Switch to using
two backticks, as per the coding guidelines.

As an added bonus to rendering these as monospace, we will have them
render the same with AsciiDoc and Asciidoctor. The `quoted' way ends up
as ‘quoted’ vs “quoted”.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/config/diff.txt      | 2 +-
 Documentation/git-check-ignore.txt | 2 +-
 Documentation/git-describe.txt     | 2 +-
 Documentation/git-svn.txt          | 6 +++---
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index 2d3331f55c..eda0c452d1 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -69,7 +69,7 @@ diff.interHunkContext::
 diff.external::
 	If this config variable is set, diff generation is not
 	performed using the internal diff machinery, but using the
-	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
+	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF`
 	environment variable.  The command is called with parameters
 	as described under "git Diffs" in linkgit:git[1].  Note: if
 	you want to use an external diff program only on a subset of
diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index 0c3924a63d..ab97ee9d50 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -21,7 +21,7 @@ input files to the exclude mechanism) and output the path if it is
 excluded.
 
 By default, tracked files are not shown at all since they are not
-subject to exclude rules; but see `--no-index'.
+subject to exclude rules; but see `--no-index`.
 
 OPTIONS
 -------
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index a88f6ae2c6..adbbb8907f 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -44,7 +44,7 @@ OPTIONS
 	HEAD".  If the working tree has local modification "-dirty"
 	is appended to it.  If a repository is corrupt and Git
 	cannot determine if there is local modification, Git will
-	error out, unless `--broken' is given, which appends
+	error out, unless `--broken` is given, which appends
 	the suffix "-broken" instead.
 
 --all::
diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 4e62dc37e7..2491ed47a6 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -361,7 +361,7 @@ where <name> is the name of the SVN repository as specified by the -R option to
 	This should make it easy to look up svn log messages when svn
 	users refer to -r/--revision numbers.
 +
-The following features from `svn log' are supported:
+The following features from `svn log` are supported:
 +
 --
 -r <n>[:<n>];;
@@ -397,7 +397,7 @@ Any other arguments are passed directly to 'git log'
 'blame'::
 	Show what revision and author last modified each line of a file. The
 	output of this mode is format-compatible with the output of
-	`svn blame' by default. Like the SVN blame command,
+	`svn blame` by default. Like the SVN blame command,
 	local uncommitted changes in the working tree are ignored;
 	the version of the file in the HEAD revision is annotated. Unknown
 	arguments are passed directly to 'git blame'.
@@ -482,7 +482,7 @@ denotes such an object, or it is requested by invoking an editor (see
 
 'info'::
 	Shows information about a file or directory similar to what
-	`svn info' provides.  Does not currently support a -r/--revision
+	`svn info` provides.  Does not currently support a -r/--revision
 	argument.  Use the --url option to output only the value of the
 	'URL:' field.
 
-- 
2.31.1.751.gd2f1c929bd

Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Eric Sunshine]

On Thu, May 13, 2021 at 2:18 PM Martin Ågren <martin.agren@gmail.com> wrote:
> Asciidoctor renders 'git cat-file' with the single quotes. It's somehow
> tricked by the single quote in "srcref\'s" earler in the paragraph. If

s/earler/earlier/

> we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite
> things a bit to avoid "srcref's" entirely.
>
> Add backticks for monospacing around these refs and command invocations
> while at it.
>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>

Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Martin Ågren]

On Thu, 13 May 2021 at 21:16, Eric Sunshine <sunshine@sunshineco.com> wrote:
>
> On Thu, May 13, 2021 at 2:18 PM Martin Ågren <martin.agren@gmail.com> wrote:
> > Asciidoctor renders 'git cat-file' with the single quotes. It's somehow
> > tricked by the single quote in "srcref\'s" earler in the paragraph. If
>
> s/earler/earlier/

Oops. Thanks!

Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Junio C Hamano]

Martin Ågren <martin.agren@gmail.com> writes:

> These patches reduce
>
>   ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD
>
> from ~1200 to ~1000 lines. It's the usual mix of things where one or the
> other of the tools renders something less well, or where we're doing
> something odd in the source and we just happen to notice it in the diff.
>
> My ulterior motive here is to have a smaller doc-diff when I post a
> patch to switch the default to Asciidoctor (with xmlto), so that it gets
> a bit easier to reason about. But if everybody gets prettier docs,
> that's also good.
>
> Some of these rephrase wording such as "other peoples' commits" to avoid
> that apostrophe at the end of a word. I'm hoping those rephrasings don't
> regress the quality of the text -- if they do, I'll be happy to try
> something else.

It is sad, but we really should try "something else", unfortunately.

I do agree with the "motive" very much---even though condensing it
down to plain text before running comparison already loses too much
information, doc-diff is the only tool we currently have to
effectively review regressions in rendered document, and the
proposed transition cannot be done safely with confidence without
being able to vet the differences.  I am happy to hear about 17%
reduction already, but the requirement to rewrite things like "other
peoples' commits" is a dealbreaker.

I am not so worried about the existing text you rewrote in these
patches.  I however do not want to see asciidoc(tor) dictating use
of a strange dialect of English when we write new documentation or
update existing ones by imposing rules like "you are not allowed to
use apostrophe-es to express possessive, and instead use 'of'"; it
will become a continuing burden for anybody who writes documentation
for us.

A typesettig rule like "instead of double-dashes --, use {litdd}" is
an acceptable way out.  At least that wouldn't constrain what the
final product that gets delivered to the end-users can say.

Thanks.

Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Junio C Hamano]

Martin Ågren <martin.agren@gmail.com> writes:

> Asciidoctor renders 'git cat-file' with the single quotes.

I somehow find this sentence a bit hard to grok.  Do you mean
"instead of typesetting them emphasized, the two-word phrase is
enclosed in a pair of literal single quotes"?

> It's somehow
> tricked by the single quote in "srcref\'s" earler in the paragraph. If
> we drop the backslash, we'll regress with AsciiDoc. Let's just rewrite
> things a bit to avoid "srcref's" entirely.

I also was puzzled by this one and the previous "cat-file" thing,
mostly because I couldn't tell if this is an unrelated problem that
happens to be around the same single-quote letter, or somehow
happens only because the single-quoted 'cat-file' was nearby, until
I checked the patch text (and it seems that this is "here is another
problem around apostrophe").

> Add backticks for monospacing around these refs and command invocations
> while at it.

I have no problem with this particular rephrasing from "srcref's
value" to "value of srcref", but forbidding possessive "'s" from any
future documentation is troubling.

> -. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
> -  value and store it in dstref" in fetch and push operations.
> +. A colon `:` is used as in `srcref:dstref` to mean "use the value
> +  of `srcref` and store it in `dstref`" in fetch and push operations.
>    It may also be used to select a specific object such as with
> -  'git cat-file': "git cat-file blob v1.3.3:refs.c".
> +  'git cat-file': `git cat-file blob v1.3.3:refs.c`.

The proposed log message did not explain why you wanted to avoid
double-quote pair on the "cat-file" line.  Is this meant as a
workaround for the "single quotes are shown around git cat-file"
issue?

Thanks.

RE: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Felipe Contreras]

Martin Ågren wrote:
> These patches reduce
> 
>   ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD
> 
> from ~1200 to ~1000 lines. It's the usual mix of things where one or the
> other of the tools renders something less well, or where we're doing
> something odd in the source and we just happen to notice it in the diff.

These changes are good, but what happens the next time somebody
inadvertedly introduces something that "trips" asciidoctor?

We should be submitting bug reports to the asciidoctor project as well,
so in the future it's less likely we find ourselves in the same
scenario.

Preferably the bug report should be in the commit message.

Cheers.

-- 
Felipe Contreras

Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Jeff King]

On Thu, May 13, 2021 at 08:17:42PM +0200, Martin Ågren wrote:

> -. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
> -  value and store it in dstref" in fetch and push operations.
> +. A colon `:` is used as in `srcref:dstref` to mean "use the value
> +  of `srcref` and store it in `dstref`" in fetch and push operations.
>    It may also be used to select a specific object such as with
> -  'git cat-file': "git cat-file blob v1.3.3:refs.c".
> +  'git cat-file': `git cat-file blob v1.3.3:refs.c`.

I'd perhaps write:

  `srcref`'s value...

but I'm a little afraid to see how it is handled by the various parsers
(I'd write it because it does look OK in most markdown parsers I've
used).

That said, I think in this case "value of `srcref`" is actually an
improvement to the text (but I wouldn't say the same of the earlier
patches, which feel like they are making things clunkier).

-Peff

Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Martin Ågren]

On Thu, 13 May 2021 at 22:35, Junio C Hamano <gitster@pobox.com> wrote:
>
> Martin Ågren <martin.agren@gmail.com> writes:
>
> > Some of these rephrase wording such as "other peoples' commits" to avoid
> > that apostrophe at the end of a word. I'm hoping those rephrasings don't
> > regress the quality of the text -- if they do, I'll be happy to try
> > something else.
>
> It is sad, but we really should try "something else", unfortunately.
>
> I do agree with the "motive" very much---even though condensing it
> down to plain text before running comparison already loses too much
> information, doc-diff is the only tool we currently have to
> effectively review regressions in rendered document, and the
> proposed transition cannot be done safely with confidence without
> being able to vet the differences.  I am happy to hear about 17%
> reduction already, but the requirement to rewrite things like "other
> peoples' commits" is a dealbreaker.

OK, calling it a dealbreaker is fair. Thanks.

> A typesettig rule like "instead of double-dashes --, use {litdd}" is
> an acceptable way out.  At least that wouldn't constrain what the
> final product that gets delivered to the end-users can say.

I've done some experimenting now with a new attribute "apos" which
expands to a lone SQ. It seems to work fine across the different tools.
The rule could be that all ' should be {apos}. That's a quite
aggressive rule in a sense. It could be narrowed down to something like
"... if the paragraph contains other quotation, such as backticks or
single quotes", but that's probably just overly complicating things.

I don't see an immediate need to go s/'/{apos}/ just because we can.
We've identified five problematic spots, four of which are with the tool
we're moving away from.

Martin

Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Martin Ågren]

On Fri, 14 May 2021 at 03:40, Felipe Contreras
<felipe.contreras@gmail.com> wrote:

> We should be submitting bug reports to the asciidoctor project as well,
> so in the future it's less likely we find ourselves in the same
> scenario.
>
> Preferably the bug report should be in the commit message.

I don't have an account with the website they use for their issue
tracking. If you want to submit a bug report and post the link here,
that's fine by me and I'll include it in the reroll.

Martin

Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Martin Ågren]

On Fri, 14 May 2021 at 00:00, Junio C Hamano <gitster@pobox.com> wrote:
>
> Martin Ågren <martin.agren@gmail.com> writes:
>
> > Asciidoctor renders 'git cat-file' with the single quotes.
>
> I somehow find this sentence a bit hard to grok.  Do you mean
> "instead of typesetting them emphasized, the two-word phrase is
> enclosed in a pair of literal single quotes"?

Yes. I will improve the description.

> I have no problem with this particular rephrasing from "srcref's
> value" to "value of srcref", but forbidding possessive "'s" from any
> future documentation is troubling.

I think this is a case of several things going on in one paragraph in a
way that confuses the tool. As Felipe commented, it's probably correct
to call it out as an Asciidoctor bug. If we hit is *once* across all our
documentation, I think it's correct to work around it [and report the
bug, if we can], but not let the experience impose a blanket rule on
ourselves that we mustn't do anything that even resembles this
paragraph.

> > -. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
> > -  value and store it in dstref" in fetch and push operations.
> > +. A colon `:` is used as in `srcref:dstref` to mean "use the value
> > +  of `srcref` and store it in `dstref`" in fetch and push operations.
> >    It may also be used to select a specific object such as with
> > -  'git cat-file': "git cat-file blob v1.3.3:refs.c".
> > +  'git cat-file': `git cat-file blob v1.3.3:refs.c`.
>
> The proposed log message did not explain why you wanted to avoid
> double-quote pair on the "cat-file" line.  Is this meant as a
> workaround for the "single quotes are shown around git cat-file"
> issue?

Hmm, I've somehow tended to think that it's 'git foo' the tool and `git
foo --bar baz` the actual invocation. SQs for the former, backticks for
the latter. Like, `git cat-file` is not a correct invocation of 'git
cat-file'. But I think I'm starting to see the error in my ways --
CodingGuidelines says to use backticks around command names, so it
really should be `git cat-file`. And changing that might just happen to
avoid the issue that triggered this patch.

Thanks for your comments.

Martin

Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Martin Ågren]

On Fri, 14 May 2021 at 07:30, Jeff King <peff@peff.net> wrote:
>
> That said, I think in this case "value of `srcref`" is actually an
> improvement to the text (but I wouldn't say the same of the earlier
> patches, which feel like they are making things clunkier).

Ok, if it's an improvement on its own, that's good. Thanks for calling
out that the others are not.

Martin

Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Felipe Contreras]

Martin Ågren wrote:
> On Thu, 13 May 2021 at 22:35, Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Martin Ågren <martin.agren@gmail.com> writes:
> >
> > > Some of these rephrase wording such as "other peoples' commits" to avoid
> > > that apostrophe at the end of a word. I'm hoping those rephrasings don't
> > > regress the quality of the text -- if they do, I'll be happy to try
> > > something else.
> >
> > It is sad, but we really should try "something else", unfortunately.
> >
> > I do agree with the "motive" very much---even though condensing it
> > down to plain text before running comparison already loses too much
> > information, doc-diff is the only tool we currently have to
> > effectively review regressions in rendered document, and the
> > proposed transition cannot be done safely with confidence without
> > being able to vet the differences.  I am happy to hear about 17%
> > reduction already, but the requirement to rewrite things like "other
> > peoples' commits" is a dealbreaker.
> 
> OK, calling it a dealbreaker is fair. Thanks.

If I understood correctly the deal-breaker is as a long-term solution.

These particular patches may be welcome right now to reduce the
doc-diff, but eventually these issues should be fixed in asciidoctor.

> > A typesettig rule like "instead of double-dashes --, use {litdd}" is
> > an acceptable way out.  At least that wouldn't constrain what the
> > final product that gets delivered to the end-users can say.
> 
> I've done some experimenting now with a new attribute "apos" which
> expands to a lone SQ. It seems to work fine across the different tools.
> The rule could be that all ' should be {apos}. That's a quite
> aggressive rule in a sense. It could be narrowed down to something like
> "... if the paragraph contains other quotation, such as backticks or
> single quotes", but that's probably just overly complicating things.

I would rather fix it in asciidoctor (the ones that are actually
asciidoctor issues)

-- 
Felipe Contreras

Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Felipe Contreras]

Martin Ågren wrote:
> On Fri, 14 May 2021 at 03:40, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
> 
> > We should be submitting bug reports to the asciidoctor project as well,
> > so in the future it's less likely we find ourselves in the same
> > scenario.
> >
> > Preferably the bug report should be in the commit message.
> 
> I don't have an account with the website they use for their issue
> tracking.

GitHub? It probably takes a couple of minutes to set up an account.

> If you want to submit a bug report and post the link here,
> that's fine by me and I'll include it in the reroll.

If you would rather have me act as a proxy, that's fine by me.

Just give me a simple example that produces the issue.

Cheers.

-- 
Felipe Contreras

Re: [PATCH 3/6] git-check-ref-format.txt: avoid single quote

[Felipe Contreras]

Martin Ågren wrote:
> On Fri, 14 May 2021 at 00:00, Junio C Hamano <gitster@pobox.com> wrote:

> > The proposed log message did not explain why you wanted to avoid
> > double-quote pair on the "cat-file" line.  Is this meant as a
> > workaround for the "single quotes are shown around git cat-file"
> > issue?
> 
> Hmm, I've somehow tended to think that it's 'git foo' the tool and `git
> foo --bar baz` the actual invocation. SQs for the former, backticks for
> the latter. Like, `git cat-file` is not a correct invocation of 'git
> cat-file'. But I think I'm starting to see the error in my ways --
> CodingGuidelines says to use backticks around command names, so it
> really should be `git cat-file`. And changing that might just happen to
> avoid the issue that triggered this patch.

Hmmm. `git status`, `git branch`, `git diff`, `git log`.

All these are both "tools" **and** invocations. In fact, you an pretty
much "invoke" any thing: `git checkout` might not do anything... But it
runs.

-- 
Felipe Contreras

Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Martin Ågren]

On Fri, 14 May 2021 at 14:24, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
>
> Martin Ågren wrote:
> > On Fri, 14 May 2021 at 03:40, Felipe Contreras
> > <felipe.contreras@gmail.com> wrote:
> >
> > > We should be submitting bug reports to the asciidoctor project as well,
> > > so in the future it's less likely we find ourselves in the same
> > > scenario.
> > >
> > > Preferably the bug report should be in the commit message.
> >
> > I don't have an account with the website they use for their issue
> > tracking.
>
> GitHub? It probably takes a couple of minutes to set up an account.

Yes, it's GitHub. I'm not interested in having an account there. There's
some trade-off there with me not being able to report bugs, but that
cuts both ways, so I don't feel bad about it.

> > If you want to submit a bug report and post the link here,
> > that's fine by me and I'll include it in the reroll.
>
> If you would rather have me act as a proxy, that's fine by me.

Thanks. If you have better things to do, no worry.

> Just give me a simple example that produces the issue.

Here are three variants where AsciiDoc 8.6.10 renders the same, with
emphasis:

  single quotes that will not render literally: 'git cat-file'.

  single quotes that won't render literally: 'git cat-file'.

  single quotes that\'ll render literally: 'git cat-file'.

With Asciidoctor (2.0.15),

  asciidoctor -b docbook5 -d manpage -o test.xml test.txt

the XML contains

<simpara>single quotes that will not render literally: <emphasis>git
cat-file</emphasis>.</simpara>
<simpara>single quotes that won&#8217;t render literally:
<emphasis>git cat-file</emphasis>.</simpara>
<simpara>single quotes that&#8217;ll render literally: 'git cat-file'.</simpara>

That last paragraph is not as expected. I expect <emphasis>.

I realize that a good answer here is "don't do that then". But the
background is that there's some other stuff going on that means AsciiDoc
needs that backspaced apostrophe. So this is a minimal reproduction for
Asciidoctor where we've lost some of the AsciiDoc-specific background.

A fix that works with both tools is an attribute:

  :apos: '
  single quotes that won{apos}t render literally: 'git cat-file'.

Martin

Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

[Felipe Contreras]

Martin Ågren wrote:
> On Fri, 14 May 2021 at 14:24, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
> >
> > Martin Ågren wrote:
> > > On Fri, 14 May 2021 at 03:40, Felipe Contreras
> > > <felipe.contreras@gmail.com> wrote:
> > >
> > > > We should be submitting bug reports to the asciidoctor project as well,
> > > > so in the future it's less likely we find ourselves in the same
> > > > scenario.
> > > >
> > > > Preferably the bug report should be in the commit message.
> > >
> > > I don't have an account with the website they use for their issue
> > > tracking.
> >
> > GitHub? It probably takes a couple of minutes to set up an account.
> 
> Yes, it's GitHub. I'm not interested in having an account there. There's
> some trade-off there with me not being able to report bugs, but that
> cuts both ways, so I don't feel bad about it.

I don't see what are those both ways, but OK.

> > > If you want to submit a bug report and post the link here,
> > > that's fine by me and I'll include it in the reroll.
> >
> > If you would rather have me act as a proxy, that's fine by me.
> 
> Thanks. If you have better things to do, no worry.

I do, but reporting bugs doesn't that *that* much time.

> > Just give me a simple example that produces the issue.
> 
> Here are three variants where AsciiDoc 8.6.10 renders the same, with
> emphasis:
> 
>   single quotes that will not render literally: 'git cat-file'.
> 
>   single quotes that won't render literally: 'git cat-file'.
> 
>   single quotes that\'ll render literally: 'git cat-file'.
> 
> With Asciidoctor (2.0.15),
> 
>   asciidoctor -b docbook5 -d manpage -o test.xml test.txt
> 
> the XML contains

I'm not talking about the XML, I'm talking about the man pages. I'm not
interested in intermediary code, I'm interested in the final output,
which does seem to work correctly:

  ruby -r asciidoctor <<\EOF
  puts Asciidoctor.convert(<<REOF, backend: :manpage)
  single quotes that will not render literally: 'git cat-file'.
  single quotes that won't render literally: 'git cat-file'.
  single quotes that\'ll render literally: 'git cat-file'.
  REOF
  EOF

  single quotes that will not render literally: \(aqgit cat\-file\(aq.
  single quotes that won\(cqt render literally: \(aqgit cat\-file\(aq.
  single quotes that\(cqll render literally: \(aqgit cat\-file\(aq.

Cheers.

-- 
Felipe Contreras