From: Felipe Contreras <felipe.contreras@gmail.com>
To: "brian m. carlson" <sandals@crustytoothpaste.net>, git@vger.kernel.org
Cc: "Felipe Contreras" <felipe.contreras@gmail.com>,
"Martin Ågren" <martin.agren@gmail.com>,
"Bagas Sanjaya" <bagasdotme@gmail.com>,
"Jeff King" <peff@peff.net>
Subject: RE: [PATCH v2 1/2] doc: add an option to have Asciidoctor build man pages directly
Date: Fri, 14 May 2021 14:53:13 -0500 [thread overview]
Message-ID: <609ed529e2306_431272087@natae.notmuch> (raw)
In-Reply-To: <20210514003104.94644-2-sandals@crustytoothpaste.net>
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@gmail.com>
I most definitely do not sign off this.
--
Felipe Contreras
next prev parent reply other threads:[~2021-05-14 19:53 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-11 22:27 [PATCH] doc: use asciidoctor to build man pages directly Felipe Contreras
2021-05-11 23:26 ` brian m. carlson
2021-05-12 0:58 ` Felipe Contreras
2021-05-12 2:11 ` [PATCH 1/2] doc: add an option to have Asciidoctor " brian m. carlson
2021-05-12 2:11 ` [PATCH 2/2] doc: remove GNU_ROFF option brian m. carlson
2021-05-12 2:18 ` Eric Sunshine
2021-05-12 2:28 ` brian m. carlson
2021-05-12 4:45 ` Felipe Contreras
2021-05-14 0:11 ` brian m. carlson
2021-05-15 13:30 ` Felipe Contreras
2021-05-13 13:11 ` Martin Ågren
2021-05-12 2:48 ` [PATCH 1/2] doc: add an option to have Asciidoctor build man pages directly Bagas Sanjaya
2021-05-12 5:03 ` Felipe Contreras
2021-05-13 23:24 ` brian m. carlson
2021-05-14 12:58 ` Felipe Contreras
2021-05-15 13:25 ` Felipe Contreras
2021-05-12 4:41 ` Felipe Contreras
2021-05-13 23:38 ` brian m. carlson
2021-05-14 19:02 ` Felipe Contreras
2021-05-12 4:43 ` Bagas Sanjaya
2021-05-13 23:54 ` brian m. carlson
2021-05-12 6:22 ` Jeff King
2021-05-12 6:30 ` Jeff King
2021-05-12 6:59 ` Jeff King
2021-05-12 19:29 ` Felipe Contreras
2021-05-13 17:30 ` Martin Ågren
2021-05-13 22:37 ` Felipe Contreras
2021-05-12 19:53 ` Eric Sunshine
2021-05-12 22:37 ` Jeff King
2021-05-14 15:34 ` Martin Ågren
2021-05-14 0:31 ` [PATCH v2 0/2] Asciidoctor native manpage builds brian m. carlson
2021-05-14 0:31 ` [PATCH v2 1/2] doc: add an option to have Asciidoctor build man pages directly brian m. carlson
2021-05-14 3:58 ` Junio C Hamano
2021-05-14 5:27 ` Jeff King
2021-05-14 20:00 ` Felipe Contreras
2021-05-14 19:55 ` brian m. carlson
2021-05-14 20:52 ` Felipe Contreras
2021-05-14 19:57 ` Felipe Contreras
2021-05-14 19:53 ` Felipe Contreras [this message]
2021-05-14 20:17 ` brian m. carlson
2021-05-14 23:31 ` Felipe Contreras
2021-05-14 0:31 ` [PATCH v2 2/2] doc: remove GNU_ROFF option brian m. carlson
2021-05-14 19:07 ` [PATCH v2 0/2] Asciidoctor native manpage builds Felipe Contreras
2021-05-14 20:00 ` brian m. carlson
2021-05-14 21:21 ` Felipe Contreras
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=609ed529e2306_431272087@natae.notmuch \
--to=felipe.contreras@gmail.com \
--cc=bagasdotme@gmail.com \
--cc=git@vger.kernel.org \
--cc=martin.agren@gmail.com \
--cc=peff@peff.net \
--cc=sandals@crustytoothpaste.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).