[2/2] Documentation: Allow to use asciidoctor for formatting man pages

Submitted by Takashi Iwai on Jan. 16, 2019, 9:27 a.m.

Details

Message ID 20190116092747.12235-2-tiwai@suse.de
State New
Series "Series without cover letter"
Headers show

Commit Message

Takashi Iwai Jan. 16, 2019, 9:27 a.m.
Since asciidoc is based on Phyton 2, we want to move to alternative,
and a promising one is asciidoctor.  This patch allows to use
asciidoctor for formatting man pages instead of asiidoc, by passing
a make option, USE_ASCIIDOCTOR=yes.

Although asciidoctor is almost compatible with asciidoc, it can
produce a man page directly from a text file without XML, which is
more efficiently.  So in asciidoctor mode, we don't require xmlto.

Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
 Documentation/Makefile | 13 +++++++++++++
 1 file changed, 13 insertions(+)

Patch hide | download patch | download mbox

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3c93ec8a4083..aa5d3ebbf652 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -2,8 +2,13 @@  __nmk_dir ?= ../scripts/nmk/scripts/
 include $(__nmk_dir)include.mk
 include $(__nmk_dir)macro.mk
 
+ifneq ($(USE_ASCIIDOCTOR),)
+ASCIIDOC	:= asciidoctor
+XMLTO		:=
+else
 ASCIIDOC	:= asciidoc
 XMLTO		:= xmlto
+endif
 
 FOOTER		:= footer.txt
 SRC1		+= crit.txt
@@ -44,13 +49,21 @@  $(FOOTER): ../Makefile.versions
 
 %.1: %.txt $(FOOTER) custom.xsl
 	$(call msg-gen, $@)
+ifneq ($(USE_ASCIIDOCTOR),)
+	$(Q) $(ASCIIDOC) -b manpage -d manpage -o $@ $<
+else
 	$(Q) $(ASCIIDOC) -b docbook -d manpage -o $(patsubst %.1,%.xml,$@) $<
 	$(Q) $(XMLTO) man -m custom.xsl $(patsubst %.1,%.xml,$@) 2>/dev/null
+endif
 
 %.8: %.txt $(FOOTER) custom.xsl
 	$(call msg-gen, $@)
+ifneq ($(USE_ASCIIDOCTOR),)
+	$(Q) $(ASCIIDOC) -b manpage -d manpage -o $@ $<
+else
 	$(Q) $(ASCIIDOC) -b docbook -d manpage -o $(patsubst %.8,%.xml,$@) $<
 	$(Q) $(XMLTO) man -m custom.xsl $(patsubst %.8,%.xml,$@) 2>/dev/null
+endif
 
 %.ps: %.1
 	$(call msg-gen, $@)

Comments

Radostin Stoyanov Jan. 16, 2019, 10:05 a.m.
On 16/01/2019 09:27, Takashi Iwai wrote:
> Since asciidoc is based on Phyton 2, we want to move to alternative,
> and a promising one is asciidoctor.  This patch allows to use
> asciidoctor for formatting man pages instead of asiidoc, by passing
> a make option, USE_ASCIIDOCTOR=yes.
>
> Although asciidoctor is almost compatible with asciidoc, it can
> produce a man page directly from a text file without XML, which is
> more efficiently.  So in asciidoctor mode, we don't require xmlto.
>
> Signed-off-by: Takashi Iwai <tiwai@suse.de>
> ---
>  Documentation/Makefile | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
This is a very good idea!

Could you also update the following files to use/install 'asciidoctor'
instead of 'asciidoc'?

- test/others/bers/Makefile
- scripts/travis/travis-tests
- scripts/nmk/Documentation/Makefile
- scripts/build/Dockerfile.centos
- scripts/build/Dockerfile.alpine
- scripts/build/Dockerfile.fedora.tmpl

Thanks,
Radostin
Takashi Iwai Jan. 16, 2019, 10:35 a.m.
On Wed, 16 Jan 2019 11:05:29 +0100,
Radostin Stoyanov wrote:
> 
> On 16/01/2019 09:27, Takashi Iwai wrote:
> > Since asciidoc is based on Phyton 2, we want to move to alternative,
> > and a promising one is asciidoctor.  This patch allows to use
> > asciidoctor for formatting man pages instead of asiidoc, by passing
> > a make option, USE_ASCIIDOCTOR=yes.
> >
> > Although asciidoctor is almost compatible with asciidoc, it can
> > produce a man page directly from a text file without XML, which is
> > more efficiently.  So in asciidoctor mode, we don't require xmlto.
> >
> > Signed-off-by: Takashi Iwai <tiwai@suse.de>
> > ---
> >  Documentation/Makefile | 13 +++++++++++++
> >  1 file changed, 13 insertions(+)
> This is a very good idea!
> 
> Could you also update the following files to use/install 'asciidoctor'
> instead of 'asciidoc'?
> 
> - test/others/bers/Makefile
> - scripts/travis/travis-tests
> - scripts/nmk/Documentation/Makefile
> - scripts/build/Dockerfile.centos
> - scripts/build/Dockerfile.alpine
> - scripts/build/Dockerfile.fedora.tmpl

OK, I'm going to add the changes to these Makefiles that were
overlooked, but somehow hesitate to change the default behavior, as
I'm not sure how well asciidoctor is supported on each distro at all.

I'll leave travis and docker stuff as is for now, while will resend v2
patches soon later.


thanks,

Takashi