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

[Jeff King <peff@peff.net>]

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

> 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