login
Search
fixes a failure to build the git-rev-parse manpage,
seen with asciidoc 8.0.0
Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
---
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index b761b4b..671b4e3 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -138,7 +138,7 @@ syntax.
'rev{caret}0' means the commit itself and is used when 'rev' is the
object name of a tag object that refers to a commit object.
-* A suffix '~<n>' to a revision parameter means the commit
+* A suffix '$$~$$<n>' to a revision parameter means the commit
object that is the <n>th generation grand-parent of the named
commit object, following only the first parent. I.e. rev~3 is
equivalent to rev{caret}{caret}{caret} which is equivalent to\
-
But this makes it asciidoc 7.1 barf, so we need an alternative
compatible to both.
This works for me on 7.1; is your 8.0 happy with it?
-- >8 --
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 8196d78..44b1ce4 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -11,6 +11,7 @@ # the command.
caret=^
startsb=&#91;
endsb=&#93;
+tilde=&#126;
ifdef::backend-docbook[]
[gitlink-inlinemacro]
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index b761b4b..2f1306c 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -138,7 +138,7 @@ syntax.
'rev{caret}0' means the commit itself and is used when 'rev' is the
object name of a tag object that refers to a commit object.
-* A suffix '~<n>' to a revision parameter means the commit
+* A suffix '{tilde}<n>' to a revision parameter means the commit
object that is the <n>th generation grand-parent of the named
commit object, following only the first parent. I.e. rev~3 is
equivalent to rev{caret}{caret}{caret} which is equivalent to\
-
Junio C Hamano wrote: ... Yes, this works as intended. Thanks, -- Stefan Richter -=====-=-==- =-=- ---== http://arcgraph.de/sr/ -
Thanks. It's a bit sad that asciidoc's nicer quoting features are not backward compatible. -
Yes, this is awkward. Here comes the next candidate for quoting.
In pull-fetch-param.txt:
----8<----
<refspec>::
The canonical format of a <refspec> parameter is
`+?<src>:<dst>`; that is, an optional plus `+`, followed
by the source ref, followed by a colon `:`, followed by
the destination ref.
+
The remote ref that matches <src>
is fetched, and if <dst> is not empty string, the local
ref that matches it is fast forwarded using <src>.
Again, if the optional plus `+` is used, the local ref
---->8----
"man git-fetch" and "man git-pull" show:
----8<----
<refspec>
The canonical format of a <refspec> parameter is ?<src>:<dst>;
that is, an optional plus, followed by the source ref, followed
by a colon :, followed by the destination ref.
The remote ref that matches <src> is fetched, and if <dst> is
not empty string, the local ref that matches it is fast for-
warded using <src>. Again, if the optional plus + is used, the
---->8----
I.e. the first and second + were swallowed, but not the third one.
This is the fix for asciidoc 8.0.0:
`$$+$$?<src>:<dst>`; that is, an optional plus `+`, followed
Here is another fix that works with asciidoc 8.0.0:
`\+?<src>:<dst>`; that is, an optional plus `+`, followed
Results in
----8<----
<refspec>
The canonical format of a <refspec> parameter is +?<src>:<dst>;
that is, an optional plus +, followed by the source ref, fol-
lowed by a colon :, followed by the destination ref.
The remote ref that matches <src> is fetched, and if <dst> is
not empty string, the local ref that matches it is fast for-
warded using <src>. Again, if the optional plus + is used, the
---->8----
Does the backslash notation work with asciidoc 7?
--
Stefan Richter
-=====-=-==- =-=- ---==
http://arcgraph.de/sr/
-
[Stuart Rackham CC'ed]
At this point I have to say
What the h*ck AsciiDoc people are thinking?
Heck, I thought we were one of the more important customers of
asciidoc project and not breaking us meant at least something to
them; our name is at the top of "Project using AsciiDoc" section
of their website, http:/www.methods.co.nz/asciidoc/. Apparently
I was delusional.
Introducing nicer new features is a good thing, but you do not
break existing documents without a good reason and an escape
hatch.
Put it more mildly, I think we need to find out what their
policy on backward compatibility is, and if it is "screw it --
you should re-mark-up your documents to match the newer rule
every time we have a new release. By the way, you always have
the option to stay at older releases of ours", then we should
seriously consider switching the documentation format to
something else. I honestly hope it does not have to come to
Without looking at asciidoc 8.0 source, my guess is that it
treats _anything_ that has two pluses on the same input line as
quoted by some magical '+'-pair quote. Can you try
and verify that conjecture?
We already had to deal with this with your patch for tilde.
Arguably tilde and caret are rare enough in plain text so we can
live with having to spell it as {caret} and {tilde}, but if my
guess is correct, that means we have to spell plus '+' as {plus}
with an appropriate entry in asciidoc.conf (or "\+" if it works
in both older and newer versions). As more ordinary characters
are taken for special mark-up purposes, we would need to keep
adding them to our list. Where does the madness end?
Fortunately AsciiDoc 8.0 is still young. Maybe they can find a
fix for this in a way that does not break documents written for
(at least recent versions of) AsciiDoc 7; it might have to break
documents written for early betas and the initial release of
8.0, but that is _much_ better than breaking existing documents,
in my extremely biased opinion as a ...From the AsciiDoc User Guide (http://www.methods.co.nz/asciidoc/userguide.html#X53): If you want to disable unconstrained quotes, the new alternative constrained quotes syntax and the new index entry syntax then you can define the attribute asciidoc7compatible (for example by using the -a asciidoc7compatible command-line option). -- Stuart Rackham -
Thank you for a quick reply. Stefan, can you try it with the earlier commit to escape tilde reverted and see if our documentation set behaves well? -
Stuart,
the actual issues were:
1.) Input which works with asciidoc 7 fails to build with asciidoc 8
(after the intermediary XML step). This pair of tildes broke (but other
occurences of tilde did not):
| * A suffix '~<n>' to a revision parameter means the commit
| object that is the <n>th generation grand-parent of the named
| commit object, following only the first parent. I.e. rev~3 is
2.) Asciidoc 8 silently swallows characters from input which works with
asciidoc 7. The two pluses in the following line vanished (but instances
of single pluses per input line did not vanish):
| `+?<src>:<dst>`; that is, an optional plus `+`, followed
I wonder:
- Are tilde and plus new special characters in asciidoc 8, or were they
already special characters in asciidoc 7?
[ A pair of single pluses encloses monospaced text in asciidoc 8.
A pair of single tildes encloses subscripts. ]
- If they were already special characters in asciidoc 7, what is the
canonical way to escape them in asciidoc 7, 8, and hopefully 9?
[ If they weren't special characters in asciidoc 7, then we need
to use the asciidoc7compatible attribute. ]
- Does asciidoc 7 accept the asciidoc7compatible attribute?
Thanks.
PS:
Junio, Stuart, here is another inconsistency between asciidoc 7 and 8.
Please have a look at
http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html .
See the ASCII art above "SPECIFYING RANGES". The input
\ | / \
\ | / |
produced
\ | / \ | / |
I.e. backslash-newline was interpreted by asciidoc 7 (or whatever you
use to generate what is put online) as an escaped thus swallowed
newline. But the output that I got here from asciidoc 8 (manpage as well
as the html file) still has backslash and newline printed out.
--
Stefan Richter
-=====-=-==- =-=- --=--
http://arcgraph.de/sr/
-
Hi Stefan I've conditionally redefined subscript (tilde) and superscripting so they use the old replacements mechanism when asciidoc7compatible is defined rather than the asciidoc 8 default unconstrained quoting (patch Cheers, Stuart
Could git/Documentation/asciidoc.conf just kill all the various meanings of +, ~, ^ and make them into regular characters? In a way that works with all versions of asciidoc? (Frankly, using + as a special character may sound like a neat idea if all one wants to do is to typeset poems.) -- Stefan Richter -=====-=-==- =-=- --=-- http://arcgraph.de/sr/ -
[quotes] ^= ~= += From the AsciiDoc User Guide: "A configuration file [quotes] entry can The rationale for the + is discussed in the AsciiDoc changelog (http://www.methods.co.nz/asciidoc/CHANGELOG.html). It also brings AsciiDoc in line with the Ruby RDoc source code documentation system syntax. -- Stuart Rackham -
This hack does not help. The two `+` are still absent from the manpage (but as before, the `+` in the next paragraph is printed as desired). -- Stefan Richter -=====-=-==- =-=- --=-- http://arcgraph.de/sr/ -
After a few more experiments with different placements of backticks et cetera, I found only the following variants to work with asciidoc 8: (as mentioned, not compatible to asciidoc 7): `$$+$$?<src>:<dst>`; that is, an optional plus `+`, followed (as mentioned, compatible) `\+?<src>:<dst>`; that is, an optional plus `+`, followed (also OK, and this is probably the only really correct syntax) `\+?<src>:<dst>`; that is, an optional plus `\+`, followed (also OK but misses the monospace formatting on the plus or on the plus and questionmark) \+`?<src>:<dst>`; that is, an optional plus `+`, followed \+?`<src>:<dst>`; that is, an optional plus `+`, followed \+?`<src>:<dst>`; that is, an optional plus \+, followed `\+?<src>:<dst>`; that is, an optional plus +, followed Note, `+``?<src>:<dst>`; that is, an optional plus `+`, followed does _not_ work. It stops on invalid syntax in the intermediary xml file. Also +\+?<src>:<dst>+; that is, an optional plus `+`, followed or `+`+?<src>:<dst>+; that is, an optional plus `+`, followed do _not_ work. They don't print what we want to see. -- Stefan Richter -=====-=-==- =-=- --=-- http://arcgraph.de/sr/ -
Hi, this still is a problem, at least on Debian/unstable; with asciidoc
8.2.1, the git-push(1) and git-fetch(1) man pages have this 'broken'
refspec description[0].
Additionally there're problems with callouts, whereever <n> is used to
refer to a callout list, it renders broken man pages[1], e.g.:
$ man git-reset
[...]
EXAMPLES
Undo a commit and redo
$ git commit ...
$ git reset --soft HEAD^ \fB(1)\fR
$ edit \fB(2)\fR
$ git commit -a -c ORIG_HEAD \fB(3)\fR
.sp \fB1. \fRThis is most often done when you remembered what you
just committed is incomplete, or you misspelled your commit
message, or both. Leaves working tree as it was before "reset".
.br \fB2. \fRmake corrections to working tree files.
.br \fB3. \fR"reset" copies the old head to .git/ORIG_HEAD; redo
the commit by starting with its log message. If you do not need to
edit the message further, you can give -C option instead.
See also the --amend option to git-commit(1).
.br
Undo commits permanently
$ git commit ...
$ git reset --hard HEAD~3 \fB(1)\fR
.sp \fB1. \fRThe last three commits (HEAD, HEAD^, and HEAD~2) were
bad and you do not want to ever see them again. Do not do this if
you have already given these commits to somebody else.
.br
Undo a commit, making it a topic branch
[...]
Regards, Gerrit.
[0] http://bugs.debian.org/432560
[1] http://bugs.debian.org/420114
-
No, must have missed that. This solves the first issue with the refspec in git-push(1), git-fetch(1), but not the second one with callout lists. Thanks, Gerrit. -
Sorry, does not reproduce for me, with asciidoc 8.2.1. There
must be something different between our environments.
Here is an excerpt from what I get for git-reset.txt in
git-reset.1:
-- >8 --
.\" Title: git\-reset
.\" Author:
.\" Generator: DocBook XSL Stylesheets v1.71.0 <http://docbook.sf.net/>
.\" Date: 07/13/2007
.\" Manual: Git Manual
.\" Source: Git 1.5.3.rc1.4.gaf83
...
.SH "EXAMPLES"
.PP
Undo a commit and redo
.RS 3n
.sp
.RS 3n
.nf
$ git commit ...
$ git reset \-\-soft HEAD^ \fB(1)\fR
$ edit \fB(2)\fR
$ git commit \-a \-c ORIG_HEAD \fB(3)\fR
.fi
.RE
.sp
\fB1. \fRThis is most often done when you remembered what you just committed is incomplete, or you misspelled your commit message, or both. Leaves working tree as it was before "reset".
.br
\fB2. \fRmake corrections to working tree files.
.br
\fB3. \fR"reset" copies the old head to .git/ORIG_HEAD; redo the commit by starting with its log message. If you do not need to edit the message further, you can give \-C option instead.
See also the \-\-amend option to \fBgit\-commit\fR(1).
.br
.RE
-- 8< --
and "man -l git-reset.1" seems to show the callouts just fine.
-- >8 --
...
EXAMPLES
Undo a commit and redo
$ git commit ...
$ git reset --soft HEAD^ (1)
$ edit (2)
$ git commit -a -c ORIG_HEAD (3)
1. This is most often done when you remembered what you just
committed is incomplete, or you misspelled your commit message,
or both. Leaves working tree as it was before "reset".
2. make corrections to working tree files.
3. "reset" copies the old head to .git/ORIG_HEAD; redo the
commit by starting with its log message. If you do not need to
edit the message further, you can give -C option instead.
See also the --amend option to git-commit(1).
-- 8< --
-
I get the same with docbook-xsl 1.71.0, but with 1.72.0: .\" Title: git-reset .\" Author: .\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/> .\" Date: 07/13/2007 .\" Manual: Git Manual .\" Source: Git 1.5.3.rc0.104.g71f98 [...] .SH "EXAMPLES" .PP Undo a commit and redo .RS 4 .sp .RS 4 .nf $ git commit ... $ git reset \-\-soft HEAD^ \efB(1)\efR $ edit \efB(2)\efR $ git commit \-a \-c ORIG_HEAD \efB(3)\efR .fi .RE \&.sp \efB1. \efRThis is most often done when you remembered what you just committed is incomplete, or you misspelled your commit message, or both. Leaves working tree as it was before "reset". \&.br \efB2. \efRmake corrections to working tree files. \&.br \efB3. \efR"reset" copies the old head to .git/ORIG_HEAD; redo the commit by starting with its log message. If you do not need to edit the message further, you can give \-C option instead. I'll check with the docbook-xsl Debian maintainer. Thanks, Gerrit. -
The change in docbook-xsl was by intention, please see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=420114#22 Regards, Gerrit. -
Hmph. Where does that leave us poor users who would want to support both 1.71 and 1.72, I wonder... Will they have the same revert in 1.73 for that House Sign, too? -
It looks like they do, so perhaps we could just say that you will have issues building the git docs with 1.72 and ignore my last patch? (comparing http://docbook.xml-doc.org/snapshots/xsl/manpages/utility.xsl which has today's date and uses . and \ against http://docbook.sourceforge.net/release/xsl/1.72.0/manpages/utility.xsl which uses U+2302 and U+2593) -- Julian --- Old MacDonald had an agricultural real estate tax abatement. -