marko10_000
/
btrfs-progs
forked from Mirrors/btrfs-progs
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

btrfs-progs: build: add support for asciidoctor doc generator 

We've been using asciidoc that's written in python2, which is going to
be phased out and deprecated next year. There's a replacement,
asciidoctor. Add a configure-time detection which tool is available,
update Documentation/Makefile.in.

The original asciidoc tool is still preferred as it produces slightly
better output. The file asciidoc.conf does not have a direct equivalten
in asciidoct and would need to be replaced by extension written in ruby.

The differences:

- the <literal> are not automatically underlined and are less visible in
  the generated manual page, but it's still acceptable
- the inline CSS for the html output looks subjectively worse, is less
  compact and colourful

Issue: #89
Signed-off-by: David Sterba <dsterba@suse.com>
master
David Sterba 2018-02-02 20:51:25 +01:00
parent 4523dc2776
commit 652544f4c0
2 changed files with 35 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Documentation/Makefile.in
View File

@ -46,8 +46,21 @@ man3dir = $(mandir)/man3
man5dir = $(mandir)/man5
man8dir = $(mandir)/man8
ifeq (@ASCIIDOC_TOOL@,asciidoc)
ASCIIDOC = @ASCIIDOC@
ASCIIDOC_EXTRA =
ASCIIDOC_ARGS = -abtrfs_version=$(BTRFS_VERSION) -f asciidoc.conf
ASCIIDOC_HTML = html
ASCIIDOC_DOCBOOK = docbook
ASCIIDOC_DEPS = asciidoc.conf
endif
ifeq (@ASCIIDOC_TOOL@,asciidoctor)
ASCIIDOC = @ASCIIDOCTOR@
ASCIIDOC_ARGS = -abtrfs_version=$(BTRFS_VERSION)
ASCIIDOC_HTML = xhtml5
ASCIIDOC_DOCBOOK = docbook45
ASCIIDOC_DEPS =
endif
MANPAGE_XSL = manpage-normal.xsl
XMLTO = @XMLTO@
XMLTO_EXTRA =
@ -121,16 +134,12 @@ clean:
$(QUIET_XMLTO)$(RM) -f $@ && \
$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
%.xml : %.asciidoc asciidoc.conf
%.xml : %.asciidoc $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \
$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
$(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \
-o $@+ $< && \
$(ASCIIDOC) $(ASCIIDOC_ARGS) -b $(ASCIIDOC_DOCBOOK) -d manpage -o $@+ $< && \
$(MV) $@+ $@
%.html : %.asciidoc asciidoc.conf
%.html : %.asciidoc $(ASCIIDOC_DEPS)
$(QUIET_ASCIIDOC)$(RM) -f $@+ $@ && \
$(ASCIIDOC) -b html -d article -f asciidoc.conf \
$(ASCIIDOC_EXTRA) -abtrfs_version=$(BTRFS_VERSION) \
-o $@+ $< && \
$(ASCIIDOC) $(ASCIIDOC_ARGS) -b $(ASCIIDOC_HTML) -d article -o $@+ $< && \
$(MV) $@+ $@

18
configure.ac
View File

@ -39,6 +39,7 @@ AC_CHECK_TOOL([AR], [ar])
AC_PATH_PROG([RM], [rm], [rm])
AC_PATH_PROG([RMDIR], [rmdir], [rmdir])
AC_CHECK_FUNCS([openat], [],
[AC_MSG_ERROR([cannot find openat() function])])
@ -88,13 +89,27 @@ AS_IF([test "x$enable_documentation" = xyes], [DISABLE_DOCUMENTATION=0], [DISABL
AC_SUBST([DISABLE_DOCUMENTATION])
dnl detect tools to build documentation
ASCIIDOC_TOOL="none"
if test "x$enable_documentation" = xyes; then
AC_PATH_PROG([ASCIIDOC], [asciidoc], [asciidoc])
AC_PATH_PROG([XMLTO], [xmlto], [xmlto])
AC_PATH_PROG([GZIP], [gzip], [gzip])
AC_PATH_PROG([MV], [mv], [mv])
AC_PROG_SED
AC_PATH_PROG([ASCIIDOC], [asciidoc])
AC_PATH_PROG([ASCIIDOCTOR], [asciidoctor])
dnl asciidoc is preferred
if test -n "$ASCIIDOC"; then
ASCIIDOC_TOOL="asciidoc"
else
if test -n "$ASCIIDOCTOR"; then
ASCIIDOC_TOOL="asciidoctor"
else
AC_MSG_ERROR([cannot find asciidoc or asciidoctor, cannot build documentation])
fi
fi
fi
AC_SUBST([ASCIIDOC_TOOL])
AC_ARG_ENABLE([convert],
AS_HELP_STRING([--disable-convert], [do not build btrfs-convert]),
@ -246,6 +261,7 @@ AC_MSG_RESULT([
ldflags: ${LDFLAGS}
documentation: ${enable_documentation}
doc generator: ${ASCIIDOC_TOOL}
backtrace support: ${enable_backtrace}
btrfs-convert: ${enable_convert} ${convertfs:+($convertfs)}
btrfs-restore zstd: ${enable_zstd}