fixing a few Asciidoc/tor differences
cover fixing a few Asciidoc/tor differences
I've got a W-I-P series to teach our doc-diff tool to diff between AsciiDoc and Asciidoctor. It looks promising, and here are a few fixes that fell out from my first round of testing things.
The W-I-P doc-diff is able to find three types of problems, as shown by these patches. One is where Asciidoctor trips on something, but Asciidoc doesn't. There's the other way around. And sometimes they both stumble, but differently.
Based on maint.
Martin Ågren (5):
config/diff.txt: drop spurious backtick config/fsck.txt: avoid starting line with dash git.txt: remove empty line before list continuation git-svn.txt: drop escaping '\' that ends up being rendered
Documentation: turn middle-of-line tabs into spaces
Documentation/config/diff.txt | 4 ++-- Documentation/config/fsck.txt | 6 +++--- Documentation/config/gc.txt | 2 +- Documentation/config/gpg.txt | 2 +- Documentation/git-config.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-http-backend.txt | 2 +- Documentation/git-ls-remote.txt | 2 +- Documentation/git-notes.txt | 2 +- Documentation/git-svn.txt | 10 +++++----- Documentation/git.txt | 1 - Documentation/gitattributes.txt | 2 +- Documentation/gitremote-helpers.txt | 2 +- Documentation/gitweb.conf.txt | 2 +- Documentation/rev-list-options.txt | 2 +- 15 files changed, 21 insertions(+), 22 deletions(-)
Signature · 1 line
2.21.0
PATCH 3/5 git.txt: remove empty line before list continuation
This patch is a no-op for Asciidoctor, but makes AsciiDoc render this as intended.
--- Documentation/git.txt | 1 - 1 file changed, 1 deletion(-)
Documentation/git.txt +0 -1
@@ -536,7 +536,6 @@ other The command-line parameters passed to the configured command are determined by the ssh variant. See `ssh.variant` option in linkgit:git-config[1] for details. - + `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted by the shell, which allows additional arguments to be included.
Signature · 1 line
2.21.0
PATCH 5/5 Documentation: turn middle-of-line tabs into spaces
In reply to Martin ÅgrenThese tabs happen to appear in columns where they don't stand out too much, so the diff here is non-obvious. Some of these are rendered differently by AsciiDoc and Asciidoctor (although the difference might be invisible!), which is how I found a few of them. The remainder were found using git grep "[a-zA-Z.,)]$TAB[a-zA-Z]".
--- Documentation/config/diff.txt | 2 +- Documentation/config/gc.txt | 2 +- Documentation/config/gpg.txt | 2 +- Documentation/git-config.txt | 2 +- Documentation/git-grep.txt | 2 +- Documentation/git-http-backend.txt | 2 +- Documentation/git-ls-remote.txt | 2 +- Documentation/git-notes.txt | 2 +- Documentation/gitattributes.txt | 2 +- Documentation/gitremote-helpers.txt | 2 +- Documentation/gitweb.conf.txt | 2 +- Documentation/rev-list-options.txt | 2 +- 12 files changed, 12 insertions(+), 12 deletions(-)
Documentation/config/diff.txt +1 -1
@@ -73,7 +73,7 @@ diff.external:: 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 - your files, you might want to use linkgit:gitattributes[5] instead. + your files, you might want to use linkgit:gitattributes[5] instead. diff.ignoreSubmodules:: Sets the default value of --ignore-submodules. Note that this
Documentation/config/gc.txt +1 -1
@@ -19,7 +19,7 @@ gc.autoPackLimit:: When there are more than this many packs that are not marked with `*.keep` file in the repository, `git gc --auto` consolidates them into one larger pack. The - default value is 50. Setting this to 0 disables it. + default value is 50. Setting this to 0 disables it. gc.autoDetach:: Make `git gc --auto` return immediately and run in background
Documentation/config/gpg.txt +1 -1
@@ -16,5 +16,5 @@ gpg.format:: gpg.<format>.program:: Use this to customize the program used for the signing format you chose. (see `gpg.program` and `gpg.format`) `gpg.program` can still - be used as a legacy synonym for `gpg.openpgp.program`. The default + be used as a legacy synonym for `gpg.openpgp.program`. The default value for `gpg.x509.program` is "gpgsm".
Documentation/git-config.txt +1 -1
@@ -126,7 +126,7 @@ See also <<FILES>>. --local:: For writing options: write to the repository `.git/config` file. - This is the default behavior. + This is the default behavior. + For reading options: read only from the repository `.git/config` rather than from all available files.
Documentation/git-grep.txt +1 -1
@@ -88,7 +88,7 @@ OPTIONS mechanism. Only useful with `--untracked`. --exclude-standard:: - Do not pay attention to ignored files specified via the `.gitignore` + Do not pay attention to ignored files specified via the `.gitignore` mechanism. Only useful when searching files in the current directory with `--no-index`.
Documentation/git-http-backend.txt +1 -1
@@ -162,7 +162,7 @@ ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage. Accelerated static Apache 2.x:: Similar to the above, but Apache can be used to return static - files that are stored on disk. On many systems this may + files that are stored on disk. On many systems this may be more efficient as Apache can ask the kernel to copy the file contents from the file system directly to the network: +
Documentation/git-ls-remote.txt +1 -1
@@ -31,7 +31,7 @@ OPTIONS displayed. --refs:: - Do not show peeled tags or pseudorefs like HEAD in the output. + Do not show peeled tags or pseudorefs like `HEAD` in the output. -q:: --quiet::
Documentation/git-notes.txt +1 -1
@@ -146,7 +146,7 @@ OPTIONS -C <object>:: --reuse-message=<object>:: - Take the given blob object (for example, another note) as the + Take the given blob object (for example, another note) as the note message. (Use `git notes copy <object>` instead to copy notes between objects.)
Documentation/gitattributes.txt +1 -1
@@ -18,7 +18,7 @@ A `gitattributes` file is a simple text file that gives Each line in `gitattributes` file is of form: - pattern attr1 attr2 ... + pattern attr1 attr2 ... That is, a pattern followed by an attributes list, separated by whitespaces. Leading and trailing whitespaces are
Documentation/gitremote-helpers.txt +1 -1
@@ -468,7 +468,7 @@ set by Git if the remote helper has the 'option' capability. 'option dry-run' {'true'|'false'}: If true, pretend the operation completed successfully, - but don't actually change any repository data. For most + but don't actually change any repository data. For most helpers this only applies to the 'push', if supported. 'option servpath <c-style-quoted-path>'::
Documentation/gitweb.conf.txt +1 -1
@@ -536,7 +536,7 @@ $omit_owner:: $per_request_config:: If this is set to code reference, it will be run once for each request. - You can set parts of configuration that change per session this way. + You can set parts of configuration that change per session this way. For example, one might use the following code in a gitweb configuration file +
Documentation/rev-list-options.txt +1 -1
@@ -742,7 +742,7 @@ is supported, which omits all blobs and trees. --filter-print-omitted:: Only useful with `--filter=`; prints a list of the objects omitted - by the filter. Object IDs are prefixed with a ``~'' character. + by the filter. Object IDs are prefixed with a ``~'' character. --missing=<missing-action>:: A debug option to help with future "partial clone" development.
Signature · 1 line
2.21.0
PATCH 4/5 git-svn.txt: drop escaping '\' that ends up being rendered
In reply to Martin ÅgrenEscaping two *'s as "\*\*" apparently makes Asciidoctor render the second backslash literally, so we end up with "*\*". So let's not escape that second asterisk. The result is now "**" as intended, both in AsciiDoc and Asciidoctor.
--- Documentation/git-svn.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
Documentation/git-svn.txt +5 -5
@@ -126,7 +126,7 @@ your Perl's Getopt::Long is < v2.37). command-line argument. + This automatically updates the rev_map if needed (see -'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). +'$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). --localtime;; Store Git commit times in the local time zone instead of UTC. This
@@ -239,7 +239,7 @@ Like 'git rebase'; this requires that the working tree be clean and have no uncommitted changes. + This automatically updates the rev_map if needed (see -'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). +'$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). -l;; --local;;
@@ -524,7 +524,7 @@ This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file way to repair the repo is to use 'reset'. + Only the rev_map and refs/remotes/git-svn are changed (see -'$GIT_DIR/svn/\*\*/.rev_map.*' in the FILES section below for details). +'$GIT_DIR/svn/\**/.rev_map.*' in the FILES section below for details). Follow 'reset' with a 'fetch' and then 'git reset' or 'git rebase' to move local branches onto the new tree.
@@ -760,7 +760,7 @@ svn-remote.<name>.noMetadata:: + This option can only be used for one-shot imports as 'git svn' will not be able to fetch again without metadata. Additionally, -if you lose your '$GIT_DIR/svn/\*\*/.rev_map.*' files, 'git svn' will not +if you lose your '$GIT_DIR/svn/\**/.rev_map.*' files, 'git svn' will not be able to rebuild them. + The 'git svn log' command will not work on repositories using
@@ -1154,7 +1154,7 @@ fetching, then $GIT_DIR/svn/.metadata must be manually edited to remove FILES ----- -$GIT_DIR/svn/\*\*/.rev_map.*:: +$GIT_DIR/svn/\**/.rev_map.*:: Mapping between Subversion revision numbers and Git commit names. In a repository where the noMetadata option is not set, this can be rebuilt from the git-svn-id: lines that are at the
Signature · 1 line
2.21.0
PATCH 2/5 config/fsck.txt: avoid starting line with dash
In reply to Martin ÅgrenThis dash at the start of the line causes Asciidoctor to trip on the list continuations that follow and to render the pluses literally. Rewrap a little to put the dash elsewhere.
--- Documentation/config/fsck.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/config/fsck.txt +3 -3
@@ -23,9 +23,9 @@ When `fsck.<msg-id>` is set, errors can be switched to warnings and vice versa by configuring the `fsck.<msg-id>` setting where the `<msg-id>` is the fsck message ID and the value is one of `error`, `warn` or `ignore`. For convenience, fsck prefixes the error/warning -with the message ID, e.g. "missingEmail: invalid author/committer line -- missing email" means that setting `fsck.missingEmail = ignore` will -hide that issue. +with the message ID, e.g. "missingEmail: invalid author/committer +line - missing email" means that setting `fsck.missingEmail = ignore` +will hide that issue. + In general, it is better to enumerate existing objects with problems with `fsck.skipList`, instead of listing the kind of breakages these
Signature · 1 line
2.21.0
PATCH 1/5 config/diff.txt: drop spurious backtick
In reply to Martin Ågren--- Documentation/config/diff.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/config/diff.txt +1 -1
@@ -10,7 +10,7 @@ diff.autoRefreshIndex:: diff.dirstat:: A comma separated list of `--dirstat` parameters specifying the - default behavior of the `--dirstat` option to linkgit:git-diff[1]` + default behavior of the `--dirstat` option to linkgit:git-diff[1] and friends. The defaults can be overridden on the command line (using `--dirstat=<param1,param2,...>`). The fallback defaults (when not changed by `diff.dirstat`) are `changes,noncumulative,3`.
Signature · 1 line
2.21.0
Re: [PATCH 5/5] Documentation: turn middle-of-line tabs into spaces
In reply to Martin ÅgrenQuoted 5 lines · Martin Ågren
These tabs happen to appear in columns where they don't stand out too much, so the diff here is non-obvious. Some of these are rendered differently by AsciiDoc and Asciidoctor (although the difference might be invisible!), which is how I found a few of them. The remainder were found using
git grep "[a-zA-Z.,)]$TAB[a-zA-Z]".
Thanks. This was a fun-to-read patch.
Documentation/git-ls-remote.txt OPTIONS · line 34
Quoted 10 lines
Documentation/git-ls-remote.txt +1
-1@@ -31,7 +31,7 @@ OPTIONS displayed. --refs:: - Do not show peeled tags or pseudorefs like HEAD in the output. + Do not show peeled tags or pseudorefs like `HEAD` in the output.
The quoting fix here is also good.