git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Felipe Contreras <felipe.contreras@gmail.com>
To: "brian m. carlson" <sandals@crustytoothpaste.net>,
	Felipe Contreras <felipe.contreras@gmail.com>
Cc: git@vger.kernel.org, "Jeff King" <peff@peff.net>,
	"Martin Ågren" <martin.agren@gmail.com>,
	"Bagas Sanjaya" <bagasdotme@gmail.com>
Subject: Re: [PATCH] doc: use asciidoctor to build man pages directly
Date: Tue, 11 May 2021 19:58:16 -0500	[thread overview]
Message-ID: <609b2828309fc_678ff2082@natae.notmuch> (raw)
In-Reply-To: <YJsSuAscwHwRo84R@camp.crustytoothpaste.net>

brian m. carlson wrote:
> On 2021-05-11 at 22:27:54, Felipe Contreras wrote:
> > There's no need to use xmlto to build the man pages when modern
> > asciidoctor can do it by itself.
> > 
> > This new mode will be active only when USE_ASCIIDOCTOR is set.
> > 
> > Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
> > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
> > ---
> >  Documentation/Makefile | 8 ++++++++
> >  1 file changed, 8 insertions(+)
> > 
> > diff --git a/Documentation/Makefile b/Documentation/Makefile
> > index 2aae4c9cbb..0cfa88a92b 100644
> > --- a/Documentation/Makefile
> > +++ b/Documentation/Makefile
> > @@ -196,6 +196,7 @@ ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
> >  DBLATEX_COMMON =
> >  XMLTO_EXTRA += --skip-validation
> >  XMLTO_EXTRA += -x manpage.xsl
> > +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
> >  endif
> 
> As I mentioned elsewhere, this breaks the linkgit functionality since we
> don't have a patch for the asciidoctor-extensions.rb file

That's an easy fix:

--- 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'
+          "\e\\fB%s\e\\fR(%s)" % [target, attrs[1]]
         elsif parent.document.basebackend? 'docbook'
           "<citerefentry>\n" \
             "<refentrytitle>#{target}</refentrytitle>" \

> and it also doesn't honor GNU_ROFF, which means that copying and
> pasting from manual pages is problematic on systems which use groff.

My system uses groff, I don't see any issues copy-pasting from manual
pages.

How exactly can I reproduce this issue?

> I'd prefer if we put this behind an option so that just because someone
> like me who builds with Asciidoctor doesn't have to get this behavior.
> We may by default enable that option if the issues I mentioned above are
> addressed, but it would still be nice to have an option to enable the
> legacy behavior, if only for those people who may be using older
> versions of Asciidoctor.

Sure, that would be nice, but that's not not an itch I personally have
right now.

At the moment I'm finding too many areas of improvement with the
documentation build system. Perhaps, I'll do this after I've addressed
those. Or somebody else could volunteer.

Cheers.

-- 
Felipe Contreras

  reply	other threads:[~2021-05-12  0:58 UTC|newest]

Thread overview: 45+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-11 22:27 Felipe Contreras
2021-05-11 23:26 ` brian m. carlson
2021-05-12  0:58   ` Felipe Contreras [this message]
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
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=609b2828309fc_678ff2082@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 \
    --subject='Re: [PATCH] doc: use asciidoctor to build man pages directly' \
    /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

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox