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 1/2] doc: add an option to have Asciidoctor build man pages directly
Date: Tue, 11 May 2021 23:41:41 -0500 [thread overview]
Message-ID: <609b5c85b7c61_678ff20848@natae.notmuch> (raw)
In-Reply-To: <20210512021138.63598-1-sandals@crustytoothpaste.net>
brian m. carlson wrote:
> From: Felipe Contreras <felipe.contreras@gmail.com>
>
> 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 detect groff and
> do the right thing in all cases, so the GNU_ROFF option is obsolete in
> this case.
>
> 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. Be
> careful to reset the font to the previous after the change. In order to
> do so, we must reset to the previous after each font change so the
> previous state at the end is the state before our inserted text, since
> troff only remembers one previous font.
>
> 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.
Are "some common distros" namely Debian stable *exclusively*?
If so, I would consider flipping the default the other way around,
espececially since it's only te default shipped by the Debian stable
packages (easily fixed by `gem install asciidoctor`).
> If users are using a more modern toolchain or don't care
> about the rendering issues, they can enable the option.
The other way around: if users are using an ancient distribution they
can disable the option.
> Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Commit-message-by: brian m. carlson <sandals@crustytoothpaste.net>
I certainly would not want to pretend to have written the text above.
> ---
> I've preserved Felipe's authorship on this patch because much of it is
> his work. However, I have made some substantial changes here with which
> I suspect he will disagree, in addition to expanding on the commit
> message, so if he would prefer, I can reroll with the authorship
> changed. I have no preference myself.
Hard to tell in this frankenstein commit. I'd be fine with a
Commit-message-by line.
> Documentation/Makefile | 10 ++++++++++
> Documentation/asciidoctor-extensions.rb | 2 ++
> Makefile | 3 +++
> 3 files changed, 15 insertions(+)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 2aae4c9cbb..536d9a5f3d 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -196,6 +196,9 @@ ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
> DBLATEX_COMMON =
> XMLTO_EXTRA += --skip-validation
> XMLTO_EXTRA += -x manpage.xsl
> +ifdef USE_ASCIIDOCTOR_MANPAGE
I'd do:
ifndef USE_ASCIIDOCTOR_XMLTO
(the other way around)
> +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
> +endif
> endif
>
> SHELL_PATH ?= $(SHELL)
> diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
> index d906a00803..40fa87b121 100644
> --- a/Documentation/asciidoctor-extensions.rb
> +++ b/Documentation/asciidoctor-extensions.rb
> @@ -15,6 +15,8 @@ module Git
> "#{target}(#{attrs[1]})</ulink>"
> elsif parent.document.basebackend? 'html'
> %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
> + elsif parent.document.basebackend? 'manpage'
> + %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP)
I still prefer my original version, especially since:
1. I suspect most git developers are familiar with printf directives:
%s.
2. Where is that \\fP coming from? I don't see that with xmlto, nor the
publicly genrated man pages[1].
3. Doesn't work on my machine without my original \e; I see
"\fBgittutorial\fR(7)".
I don't see any way this is an improvement.
Cheers.
[1] https://git.kernel.org/pub/scm/git/git-manpages.git/tree/man1/git.1
--
Felipe Contreras
next prev parent reply other threads:[~2021-05-12 4:41 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 [this message]
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
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=609b5c85b7c61_678ff20848@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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.