Re: [PATCH 2/2] docs/diffcore: unquote "Complete Rewrites" in headers

From: Jeff King <peff@peff.net>
Date: Feb 28, 2017, 12:37 UTC
Message-ID: <20170228123753.6k646m7jnyc5uoav@sigill.intra.peff.net>
In-Reply-To: <576fa5be072ebd503aa553ef24290c77ed34eeb1.1488272203.git.patrick.steinhardt@elego.de>

On Tue, Feb 28, 2017 at 09:59:05AM +0100, Patrick Steinhardt wrote:

Show 23 quoted lines

> The gitdiffcore documentation quotes the term "Complete Rewrites" in
> headers for no real gain. This would make sense if the term could be
> easily confused if not properly grouped together. But actually, the term
> is quite obvious and thus does not really need any quoting, especially
> regarding that it is not used anywhere else.
> 
> But more importanly, this brings up a bug when rendering man pages: when
> trying to render quotes inside of a section header, we end up with
> quotes which have been misaligned to the end of line. E.g.
> 
>     diffcore-break: For Splitting Up Complete Rewrites
>     --------------------------------------------------
> 
> renders as
> 
>     DIFFCORE-BREAK: FOR SPLITTING UP  COMPLETE REWRITES""
> 
> , which is obviously wrong. While this is fixable for the man pages by
> using double-quotes (e.g. ""COMPLETE REWRITES""), this again breaks it
> for our generated HTML pages.
> 
> So fix the issue by simply dropping quotes inside of section headers,
> which is currently only done for the term "Complete Rewrites".

Thanks for a nice explanation of the issue. I was curious whether asciidoctor gets this right. It does, though I suppose that's because we only look at the HTML output. It sounds like the issue is in the docbook->roff path.

At any rate, I agree with your analysis. It's not worth futzing with the formatting when it reads just as well without the quotes.

-Peff