All of lore.kernel.org
 help / color / mirror / Atom feed
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

  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.