diff mbox series

doc: use asciidoctor to build man pages directly

Message ID 20210511222754.417371-1-felipe.contreras@gmail.com (mailing list archive)
State New
Headers show
Series doc: use asciidoctor to build man pages directly | expand

Commit Message

Felipe Contreras May 11, 2021, 10:27 p.m. UTC
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(+)

Comments

brian m. carlson May 11, 2021, 11:26 p.m. UTC | #1
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 and it also
doesn't honor GNU_ROFF, which means that copying and pasting from manual
pages is problematic on systems which use groff.

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.
Felipe Contreras May 12, 2021, 12:58 a.m. UTC | #2
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.
diff mbox series

Patch

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
 
 SHELL_PATH ?= $(SHELL)
@@ -367,9 +368,16 @@  $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS
 manpage-base-url.xsl: manpage-base-url.xsl.in
 	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
 
+ifdef TXT_TO_MAN
+%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
+	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+	$(TXT_TO_MAN) -o $@+ $< && \
+	mv $@+ $@
+else
 %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(RM) $@ && \
 	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
 
 %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \