Re: [PATCH 0/8] asciidoc fixups

From: Jeff King <peff@peff.net>
Date: May 13, 2015, 05:09 UTC
Message-ID: <20150513050951.GA7122@peff.net>
In-Reply-To: <20150513045650.GA6070@peff.net>

On Wed, May 13, 2015 at 12:56:50AM -0400, Jeff King wrote:

Show 8 quoted 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.

That example should be HEAD@\{yesterday}, of course, but I think you get the point.

Show 8 quoted 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/$me

I 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