doc: fix unmatched code fences
PATCH 1/1 doc: fix unmatched code fences
This mismatch upsets the renderer on git-scm.com.
--- Documentation/gitcore-tutorial.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/gitcore-tutorial.txt +1 -1
@@ -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`.
Signature · 1 line
2.4.0.rc2
Quoted 1 line · Jean-Noel Avila
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.
Quoted 18 lines
Signed-off-by Jean-Noel Avila <[email protected]>--- Documentation/gitcore-tutorial.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/gitcore-tutorial.txt +1
-1@@ -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`.
Quoted 10 lines · Junio C Hamano
Quoted 1 line · Jean-Noel Avila
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 = $_;
}
}---
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(-)
Documentation/git-stripspace.txt +3 -3
@@ -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$
Signature · 1 line
2.4.0.192.g5f8138b
cover asciidoc fixups
Quoted 4 lines · Jeff King
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'
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.
--- Documentation/diff-generate-patch.txt | 2 +- Documentation/git-rebase.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-)
Documentation/diff-generate-patch.txt +1 -1
@@ -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.
Documentation/git-rebase.txt +1 -1
@@ -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): ------------
Signature · 1 line
2.4.0.192.g5f8138b
PATCH 2/8 doc: fix unquoted use of "{type}"
In reply to Jeff KingCurly 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).
--- Documentation/git-rev-parse.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-rev-parse.txt +1 -1
@@ -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`
Signature · 1 line
2.4.0.192.g5f8138b
PATCH 3/8 doc: fix hanging "+"-continuation
In reply to Jeff KingIn 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.
--- Documentation/git-svn.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-svn.txt +3 -3
@@ -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.
Signature · 1 line
2.4.0.192.g5f8138b
PATCH 4/8 doc: fix length of underlined section-title
In reply to Jeff KingIn 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.
--- Documentation/git-fast-import.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-fast-import.txt +1 -1
@@ -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
Signature · 1 line
2.4.0.192.g5f8138b
PATCH 5/8 doc/add: reformat `--edit` option
In reply to Jeff KingAll 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).
--- Documentation/git-add.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/git-add.txt +2 -1
@@ -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.
Signature · 1 line
2.4.0.192.g5f8138b
PATCH 6/8 doc: convert \--option to --option
In reply to Jeff KingOlder 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.
---
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(-)
Documentation/config.txt +5 -5
@@ -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::
Documentation/git-fast-export.txt +3 -3
@@ -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.
Documentation/git-fast-import.txt +14 -14
@@ -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 ~~~~~~~~~~~~~~~
Documentation/git-fetch-pack.txt +1 -1
@@ -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.
Documentation/git-pack-objects.txt +1 -1
@@ -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::
Documentation/git-push.txt +2 -2
@@ -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[]
Documentation/git-rev-list.txt +48 -48
102 lines not on this page · raw message
Documentation/git-rev-parse.txt +1 -1
@@ -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
Documentation/git-send-pack.txt +1 -1
@@ -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,
Documentation/git-show.txt +1 -1
@@ -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.
Documentation/gitdiffcore.txt +3 -3
@@ -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:
Signature · 1 line
2.4.0.192.g5f8138b
Re: [PATCH 6/8] doc: convert \--option to --option
Quoted 18 lines · 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.
Quoted 8 lines
Signed-off-by Jeff King <[email protected]>---
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.
Quoted 391 lines
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(-)Documentation/config.txt +5
-5@@ -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::Documentation/git-fast-export.txt +3
-3@@ -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.Documentation/git-fast-import.txt +14
-14@@ -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 ~~~~~~~~~~~~~~~Documentation/git-fetch-pack.txt +1
-1@@ -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.Documentation/git-pack-objects.txt +1
-1@@ -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::Documentation/git-push.txt +2
-2@@ -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[]Documentation/git-rev-list.txt +48
-48@@ -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>... ] DESCRIPTIONDocumentation/git-rev-parse.txt +1
-1@@ -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 anDocumentation/git-send-pack.txt +1
-1@@ -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,Documentation/git-show.txt +1
-1@@ -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.Documentation/gitdiffcore.txt +3
-3@@ -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 6/8] doc: convert \--option to --option
Quoted 16 lines · John Keeping
Quoted 15 lines · 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.
Quoted 6 lines
Quoted 2 lines
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
Re: [PATCH 6/8] doc: convert \--option to --option
Quoted 11 lines · Jeff King
Quoted 3 lines · John Keeping
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.
Quoted 6 lines
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.
PATCH 7/8 doc: drop backslash quoting of some curly braces
In reply to Jeff KingText 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.
---
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(-)
Documentation/gitremote-helpers.txt +7 -7
@@ -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
Signature · 1 line
2.4.0.192.g5f8138b
PATCH 8/8 doc: put example URLs and emails inside literal backticks
In reply to Jeff KingThis makes sure that AsciiDoc does not turn them into links. Regular AsciiDoc does not catch these cases, but AsciiDoctor does treat them as links.
---
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(-)
Documentation/git-http-backend.txt +2 -2
@@ -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
Documentation/git-svn.txt +2 -2
@@ -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://[email protected]/project + transports (e.g. `svn+ssh://`), you must include the username in + the URL, e.g. `svn+ssh://[email protected]/project` --prefix=<prefix>;; This allows one to specify a prefix which is prepended to the names of remotes if trunk/branches/tags are
Documentation/git-tag.txt +1 -1
@@ -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 <\[email protected]>") to +committer identity (of the form `Your Name <[email protected]>`) to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows:
Signature · 1 line
2.4.0.192.g5f8138b
Re: [PATCH 0/8] asciidoc fixups
In reply to Jeff KingQuoted 8 lines · Jeff King
- 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.
Quoted 8 lines
[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/$meI 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
In reply to Jeff KingQuoted 3 lines · Jeff King
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
Quoted 10 lines · Junio C Hamano
Quoted 3 lines · Jeff King
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
Hi,
Quoted 8 lines · Jeff King
Quoted 6 lines · Junio C Hamano
Quoted 3 lines · Jeff King
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.
Quoted 6 lines
Quoted 4 lines
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 0/8] asciidoc fixups
Quoted 5 lines · Johannes Schindelin
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.
Quoted 5 lines
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%5E2I 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 0/8] asciidoc fixups
In reply to Jeff KingQuoted 7 lines · Jeff King
Quoted 4 lines · Jeff King
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).
Quoted 6 lines
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.
Quoted 7 lines
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.
Quoted 8 lines
- 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.
Quoted 3 lines
- 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.
Quoted 9 lines
- 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.
Quoted 3 lines
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.
Signature · 3 lines
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
Re: [PATCH 0/8] asciidoc fixups
Quoted 2 lines · brian m. carlson
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. :)
Quoted 9 lines
Quoted 5 lines
- 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] <[email protected]> (sorry no link, gmane seems down)
Quoted 8 lines
Quoted 3 lines
- 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">
— 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"?
Quoted 8 lines
Quoted 3 lines
- 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.
Quoted 9 lines
Quoted 2 lines
- 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
[PATCH 9/8] doc: convert AsciiDoc {?foo} to ifdef::foo[]
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).
--- Documentation/diff-options.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-)
Documentation/diff-options.txt +6 -2
@@ -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[]
Signature · 1 line
2.4.0.327.ge28c153
Re: [PATCH 0/8] asciidoc fixups
In reply to Jeff KingHi Brian and Peff,
Quoted 17 lines · Jeff King
Quoted 2 lines · brian m. carlson
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. :)
Quoted 9 lines
Quoted 5 lines
- 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.
Quoted 6 lines
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:
which documents how Git for Windows defines litdd.
Sorry!
Dscho
Re: [PATCH 0/8] asciidoc fixups
Quoted 5 lines · Johannes Schindelin
Quoted 5 lines
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=--'"
Quoted 7 lines
Quoted 1 line
seems to work OK.
Oh darn, I really meant to include this link:
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
Hi Peff,
Quoted 15 lines · Jeff King
Quoted 5 lines · Johannes Schindelin
Quoted 5 lines
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=--'"
Quoted 7 lines
Quoted 1 line
seems to work OK.
Oh darn, I really meant to include this link:
which documents how Git for Windows defines
litdd.
Quoted 7 lines
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
Quoted 5 lines · Johannes Schindelin
Quoted 3 lines
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
gemand 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
Quoted 6 lines · Junio C Hamano
Quoted 4 lines · Johannes Schindelin
Quoted 3 lines
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.
Quoted 8 lines
Quoted 1 line
We installed asciidoctor via
gemand 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
Quoted 9 lines · Jeff King
Quoted 7 lines · Junio C Hamano
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.
Quoted 7 lines
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
Quoted 19 lines · Junio C Hamano
Quoted 9 lines · Jeff King
Quoted 7 lines · Junio C Hamano
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.Quoted 7 lines
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).
Quoted 6 lines
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
In reply to Jeff KingQuoted 9 lines · Jeff King
Quoted 4 lines · brian m. carlson
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:
Quoted 7 lines
<div class="attribution"> — 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.
Quoted 6 lines
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
Signature · 3 lines
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
Re: [PATCH 0/8] asciidoc fixups
Quoted 4 lines · brian m. carlson
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.
Quoted 4 lines
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
Quoted 10 lines · Jeff King
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 -cORIG_HEAD
Quoted 4 lines
------
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.
Quoted 12 lines · Junio C Hamano
Quoted 10 lines · Jeff King
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 -cORIG_HEAD
Quoted 7 lines
Quoted 4 lines
------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
Quoted 4 lines · Jeff King
Quoted 2 lines
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.
Quoted 3 lines
So clearly it
uses some kind of heuristic, or this is some context in the parser that disambiguates the case.
Perhaps.
Thanks.
Quoted 11 lines · Junio C Hamano
Quoted 4 lines · Jeff King
Quoted 2 lines
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
Quoted 14 lines · Jeff King
Quoted 11 lines · Junio C Hamano
Quoted 4 lines · Jeff King
Quoted 2 lines
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.
Quoted 6 lines
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.
Signature · 3 lines
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