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