brian m. carlson wrote: > Asciidoctor contains a converter to generate man pages. In some > environments, where building only the manual pages and not the other > documentation is desired, installing a toolchain for building > DocBook-based manual pages may be burdensome, and using Asciidoctor > directly may be easier, so let's add an option to build manual pages > using Asciidoctor without the DocBook toolchain. > > We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't > contain proper handling of the apostrophe, which is controlled normally > by the GNU_ROFF option. This option for the DocBook toolchain, as well > as newer versions of Asciidoctor, makes groff output an ASCII apostrophe > instead of a Unicode apostrophe in text, so as to make copy and pasting > commands easier. These newer versions of Asciidoctor (1.5.3 and above) > detect groff and do the right thing in all cases, so the GNU_ROFF option > is obsolete in this case. I don't see what that paragraph has to do with the patch below. > We also need to update the code that tells Asciidoctor how to format our > linkgit macros so that it can output proper code for man pages. Yes, but why shove it in this patch? Now this is is doing *two* logically-independent changes. > Be careful to reset the font to the previous after the change. This is a third change, since the current man pages already don't do this: % zcat /usr/share/man/man1/git-add.1.gz | grep '\fB' you must use the \fBadd\fR command > We insert \e before each font-change backslash so Asciidoctor doesn't > convert them into \*(rs, the reverse solidus character, and instead > leaves them as we wanted them. Right. So my patch was correct: it is neecessary. > Additionally, we don't want to use XML-style escapes for the litdd and > plus macros, so let's only use the XML-style escapes in HTML and XML and > use something different for our man pages. That's a fourth change now, and one that complicates the Makefile even more, when I've been trying to simplify it. > Because Asciidoctor versions before 2.0 had a few problems with man page > output, let's default this to off for now, since some common distros are > still on 1.5. Can you point what problems are those? I did a doc-diff with my patches on asciidoctor 1.5.8 and I did not see any major problems. > If users are using a more modern toolchain or don't care > about the rendering issues, they can enable the option. What rendering issues? Also, the many should not suffer because of the few. If a few people doing USE_ASCIIDOCTOR=YesPlease have issues (because of ancient packages in their distribution, and their reluctance to type `gem install`), then *they* can disable USE_ASCIIDOCTOR_MANPAGE (or just disable USE_ASCIIDOCTOR altogether). Most people doing USE_ASCIIDOCTOR=YesPlease should not suffer because of a minority. > Signed-off-by: Felipe Contreras <felipe.contreras@xxxxxxxxx> I most definitely do not sign off this. -- Felipe Contreras
