From: Thomas Rast <trast@inf.ethz.ch>
To: Jeff King <peff@peff.net>
Cc: "Junio C Hamano" <gitster@pobox.com>,
"Thomas Rast" <trast@student.ethz.ch>,
"Carlos Martín Nieto" <cmn@elego.de>,
"Matthieu Moy" <Matthieu.Moy@imag.fr>,
git@vger.kernel.org
Subject: Re: [PATCH] docs: stop using asciidoc no-inline-literal
Date: Thu, 26 Apr 2012 11:42:41 +0200 [thread overview]
Message-ID: <87d36uomlq.fsf@thomas.inf.ethz.ch> (raw)
In-Reply-To: <20120426085156.GB22819@sigill.intra.peff.net> (Jeff King's message of "Thu, 26 Apr 2012 04:51:57 -0400")
Jeff King <peff@peff.net> writes:
> On Thu, Apr 26, 2012 at 02:19:23AM -0400, Jeff King wrote:
>
>> I'd like to eventually stop building the documentation with
>> no-inline-literal. It was an asciidoc7 compatibility thing, but we can
>> probably drop that now. However, I suspect that would require us to
>> simultaneously convert all of the `{tilde}` uses back into `~`.
>
> I took a look at this. There were about 200 sites that needed to be
> fixed up. It was a pain, but it's now done. The resulting source is much
> nicer, and as a bonus, it revealed (and fixed!) a ton of existing
> formatting bugs.
Great!
> In asciidoc 7, backticks like `foo` produced a typographic
> effect, but did not otherwise affect the syntax. In asciidoc
> 8, backticks introduce an "inline literal" inside which markup
> is not interpreted. To keep compatibility with existing
> documents, asciidoc 8 has a "no-inline-literal" attribute to
> keep the old behavior. We enabled this so that the
> documentation could be built on either version.
The switch was actually at asciidoc 8.4.1, as explained in 71c020c
(Disable asciidoc 8.4.1+ semantics for `{plus}` and friends,
2009-07-25).
> ifndef ASCIIDOC7
> -ASCIIDOC_EXTRA += -a asciidoc7compatible -a no-inline-literal
> +ASCIIDOC_EXTRA += -a asciidoc7compatible
> endif
That of course raises the question what asciidoc7compatible means. I
have no idea, and google hasn't exactly been helpful. The only thing I
could find was
http://www.methods.co.nz/asciidoc/chunked/apa.html
It mostly seems to affect quoting rules. Do we really need it?
As for the actual patch, I only did some "lazy verification" using
git grep '`[^`]*[\\{]' Documentation/
That (unsurprisingly :-) turned up no mistakes on your part. However,
some markup mistakes show up in git-fast-import.txt:
diff --git i/Documentation/git-fast-import.txt w/Documentation/git-fast-import.txt
index 2620d28..3e8fbd1 100644
--- i/Documentation/git-fast-import.txt
+++ w/Documentation/git-fast-import.txt
@@ -422,9 +422,9 @@ The `committer` command indicates who made this commit, and when
they made it.
Here `<name>` is the person's display name (for example
-``Com M Itter'') and `<email>` is the person's email address
-(``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c)
-and greater-than (\x3e) symbols. These are required to delimit
+`Com M Itter`) and `<email>` is the person's email address
+(`cm@example.com`). `LT` and `GT` are the literal less-than (`\x3c`)
+and greater-than (`\x3e`) symbols. These are required to delimit
the email address from the other fields in the line. Note that
`<name>` and `<email>` are free-form and may contain any sequence
of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded.
On my box (asciidoc 8.4.5) the preimage renders as
`Com M Itter''
in fixed-width font. In the process of debugging this, I noticed that
the quoting rules are hilariously screwy. It seems that within a
paragraph, saying
``foo'' means `bar`
^^^^^^^^^^^^^
treats the underlined part as a `-quoted chunk of text, and renders it
appropriately using a fixed-width font. The trailing ` has no effect
unless it is followed by another ` within the same paragraph. But the `
right at the start of the "quoted" text has no effect either! Moreover,
this behaviour is the same regardless of the 'asciidoc7compatible'
setting. I wonder if it has since been fixed, but the above might be a
good idea anyway. (The quoting around \xAB is just for good measure.)
--
Thomas Rast
trast@{inf,student}.ethz.ch
next prev parent reply other threads:[~2012-04-26 9:42 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-04-26 8:51 [PATCH] docs: stop using asciidoc no-inline-literal Jeff King
2012-04-26 9:03 ` Jeff King
2012-04-26 9:09 ` Matthieu Moy
2012-04-26 9:13 ` Jeff King
2012-04-26 9:42 ` Thomas Rast [this message]
2012-04-26 9:50 ` Thomas Rast
2012-04-26 12:50 ` Jeff King
2012-04-26 13:09 ` Thomas Rast
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87d36uomlq.fsf@thomas.inf.ethz.ch \
--to=trast@inf.ethz.ch \
--cc=Matthieu.Moy@imag.fr \
--cc=cmn@elego.de \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=peff@peff.net \
--cc=trast@student.ethz.ch \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.