diff mbox

[ndctl,v2,2/3] Documentation: Add the support for asciidoctor

Message ID 20180419151120.11041-3-tiwai@suse.de
State New, archived
Headers show

Commit Message

Takashi Iwai April 19, 2018, 3:11 p.m. UTC
This patch adds the support for asciidoctor to be used for generating
documents instead of asciidoc.  It's enabled via --enable-asciidoctor
configure option while asciidoc is used still as default.

In addition to the configure option, a few other changes were needed:
* some asciidoc.conf python stuff has to be replaced with asciidoctor
  ruby extension; copied mostly from git
* asciidoctor requires slightly different options
* the man pages are generated directly via asciidoctor without xmlto
  processing; less package dependency

Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
 Documentation/asciidoctor-extensions.rb.in | 28 ++++++++++++++++++++++++++++
 Documentation/daxctl/Makefile.am           | 28 ++++++++++++++++++++++++++--
 Documentation/ndctl/Makefile.am            | 28 ++++++++++++++++++++++++++--
 configure.ac                               | 17 +++++++++++++++--
 4 files changed, 95 insertions(+), 6 deletions(-)
 create mode 100644 Documentation/asciidoctor-extensions.rb.in

Comments

Verma, Vishal L April 23, 2018, 9:46 p.m. UTC | #1
On Thu, 2018-04-19 at 17:11 +0200, Takashi Iwai wrote:
> This patch adds the support for asciidoctor to be used for generating
> documents instead of asciidoc.  It's enabled via --enable-asciidoctor
> configure option while asciidoc is used still as default.
> 
> In addition to the configure option, a few other changes were needed:
> * some asciidoc.conf python stuff has to be replaced with asciidoctor
>   ruby extension; copied mostly from git
> * asciidoctor requires slightly different options
> * the man pages are generated directly via asciidoctor without xmlto
>   processing; less package dependency
> 
> Signed-off-by: Takashi Iwai <tiwai@suse.de>
> ---
>  Documentation/asciidoctor-extensions.rb.in | 28
> ++++++++++++++++++++++++++++
>  Documentation/daxctl/Makefile.am           | 28
> ++++++++++++++++++++++++++--
>  Documentation/ndctl/Makefile.am            | 28
> ++++++++++++++++++++++++++--
>  configure.ac                               | 17 +++++++++++++++--
>  4 files changed, 95 insertions(+), 6 deletions(-)
>  create mode 100644 Documentation/asciidoctor-extensions.rb.in
> 
> diff --git a/Documentation/asciidoctor-extensions.rb.in
> b/Documentation/asciidoctor-extensions.rb.in
> new file mode 100644
> index 000000000000..ebdd665f1fb9
> --- /dev/null
> +++ b/Documentation/asciidoctor-extensions.rb.in
> @@ -0,0 +1,28 @@
> +require 'asciidoctor'
> +require 'asciidoctor/extensions'
> +
> +module @Utility@
> +  module Documentation
> +    class Link@Utility@Processor <
> Asciidoctor::Extensions::InlineMacroProcessor
> +      use_dsl
> +
> +      named :chrome
> +
> +      def process(parent, target, attrs)
> +        if parent.document.basebackend? 'html'
> +          prefix = parent.document.attr('@utility@-relative-html-
> prefix')
> +          %(<a
> href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
> +        elsif parent.document.basebackend? 'docbook'
> +          "<citerefentry>\n" \
> +            "<refentrytitle>#{target}</refentrytitle>" \
> +            "<manvolnum>#{attrs[1]}</manvolnum>\n" \
> +          "</citerefentry>\n"
> +        end
> +      end
> +    end
> +  end
> +end
> +
> +Asciidoctor::Extensions.register do
> +  inline_macro @Utility@::Documentation::Link@Utility@Processor, :link@u
> tility@
> +end

Hi Takashi,

It looks like this extension should be doing the right thing for the
'linkndctl' macros, but for some reason it doesn't seem to be working for
me. In the generated man pages:

SEE ALSO
       linkndctl:ndctl-zero-labels[1], linkndctl:ndctl-init-labels[1]... etc.

Thanks,
	-Vishal
Takashi Iwai April 24, 2018, 10:13 a.m. UTC | #2
On Mon, 23 Apr 2018 23:46:28 +0200,
Verma, Vishal L wrote:
> 
> On Thu, 2018-04-19 at 17:11 +0200, Takashi Iwai wrote:
> > This patch adds the support for asciidoctor to be used for generating
> > documents instead of asciidoc.  It's enabled via --enable-asciidoctor
> > configure option while asciidoc is used still as default.
> > 
> > In addition to the configure option, a few other changes were needed:
> > * some asciidoc.conf python stuff has to be replaced with asciidoctor
> >   ruby extension; copied mostly from git
> > * asciidoctor requires slightly different options
> > * the man pages are generated directly via asciidoctor without xmlto
> >   processing; less package dependency
> > 
> > Signed-off-by: Takashi Iwai <tiwai@suse.de>
> > ---
> >  Documentation/asciidoctor-extensions.rb.in | 28
> > ++++++++++++++++++++++++++++
> >  Documentation/daxctl/Makefile.am           | 28
> > ++++++++++++++++++++++++++--
> >  Documentation/ndctl/Makefile.am            | 28
> > ++++++++++++++++++++++++++--
> >  configure.ac                               | 17 +++++++++++++++--
> >  4 files changed, 95 insertions(+), 6 deletions(-)
> >  create mode 100644 Documentation/asciidoctor-extensions.rb.in
> > 
> > diff --git a/Documentation/asciidoctor-extensions.rb.in
> > b/Documentation/asciidoctor-extensions.rb.in
> > new file mode 100644
> > index 000000000000..ebdd665f1fb9
> > --- /dev/null
> > +++ b/Documentation/asciidoctor-extensions.rb.in
> > @@ -0,0 +1,28 @@
> > +require 'asciidoctor'
> > +require 'asciidoctor/extensions'
> > +
> > +module @Utility@
> > +  module Documentation
> > +    class Link@Utility@Processor <
> > Asciidoctor::Extensions::InlineMacroProcessor
> > +      use_dsl
> > +
> > +      named :chrome
> > +
> > +      def process(parent, target, attrs)
> > +        if parent.document.basebackend? 'html'
> > +          prefix = parent.document.attr('@utility@-relative-html-
> > prefix')
> > +          %(<a
> > href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
> > +        elsif parent.document.basebackend? 'docbook'
> > +          "<citerefentry>\n" \
> > +            "<refentrytitle>#{target}</refentrytitle>" \
> > +            "<manvolnum>#{attrs[1]}</manvolnum>\n" \
> > +          "</citerefentry>\n"
> > +        end
> > +      end
> > +    end
> > +  end
> > +end
> > +
> > +Asciidoctor::Extensions.register do
> > +  inline_macro @Utility@::Documentation::Link@Utility@Processor, :link@u
> > tility@
> > +end
> 
> Hi Takashi,
> 
> It looks like this extension should be doing the right thing for the
> 'linkndctl' macros, but for some reason it doesn't seem to be working for
> me. In the generated man pages:
> 
> SEE ALSO
>        linkndctl:ndctl-zero-labels[1], linkndctl:ndctl-init-labels[1]... etc.

Mea culpa, I messed up the macro while rewriting.
Will send a fixed v3 series.


thanks,

Takashi
diff mbox

Patch

diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in
new file mode 100644
index 000000000000..ebdd665f1fb9
--- /dev/null
+++ b/Documentation/asciidoctor-extensions.rb.in
@@ -0,0 +1,28 @@ 
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+module @Utility@
+  module Documentation
+    class Link@Utility@Processor < Asciidoctor::Extensions::InlineMacroProcessor
+      use_dsl
+
+      named :chrome
+
+      def process(parent, target, attrs)
+        if parent.document.basebackend? 'html'
+          prefix = parent.document.attr('@utility@-relative-html-prefix')
+          %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>\n)
+        elsif parent.document.basebackend? 'docbook'
+          "<citerefentry>\n" \
+            "<refentrytitle>#{target}</refentrytitle>" \
+            "<manvolnum>#{attrs[1]}</manvolnum>\n" \
+          "</citerefentry>\n"
+        end
+      end
+    end
+  end
+end
+
+Asciidoctor::Extensions.register do
+  inline_macro @Utility@::Documentation::Link@Utility@Processor, :link@utility@
+end
diff --git a/Documentation/daxctl/Makefile.am b/Documentation/daxctl/Makefile.am
index 259dafd18e5e..7b753095d7a7 100644
--- a/Documentation/daxctl/Makefile.am
+++ b/Documentation/daxctl/Makefile.am
@@ -9,11 +9,22 @@ 
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 # General Public License for more details.
 
-do_subst = sed -e 's,UTILITY,daxctl,g'
+if USE_ASCIIDOCTOR
+
+do_subst = sed -e 's,@Utility@,Daxctl,g' -e's,@utility@,daxctl,g'
+CONFFILE = asciidoctor-extensions.rb
+asciidoctor-extensions.rb: ../asciidoctor-extensions.rb.in
+	$(AM_V_GEN) $(do_subst) < $< > $@
 
+else
+
+do_subst = sed -e 's,UTILITY,daxctl,g'
+CONFFILE = asciidoc.conf
 asciidoc.conf: ../asciidoc.conf.in
 	$(AM_V_GEN) $(do_subst) < $< > $@
 
+endif
+
 man1_MANS = \
 	daxctl.1 \
 	daxctl-list.1
@@ -24,10 +35,21 @@  XML_DEPS = \
 	../../version.m4 \
 	../copyright.txt \
 	Makefile \
-	asciidoc.conf
+	$(CONFFILE)
 
 RM ?= rm -f
 
+if USE_ASCIIDOCTOR
+
+%.1: %.txt $(XML_DEPS)
+	$(AM_V_GEN)$(RM) $@+ $@ && \
+		$(ASCIIDOC) -b manpage -d manpage -acompat-mode \
+		-amansource=daxctl -amanmanual="daxctl Manual" \
+		-andctl_version=$(VERSION) -o $@+ $< && \
+		mv $@+ $@
+
+else
+
 %.xml: %.txt $(XML_DEPS)
 	$(AM_V_GEN)$(RM) $@+ $@ && \
 		$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
@@ -37,3 +59,5 @@  RM ?= rm -f
 %.1: %.xml $(XML_DEPS)
 	$(AM_V_GEN)$(RM) $@ && \
 		$(XMLTO) -o . -m ../manpage-normal.xsl man $<
+
+endif
diff --git a/Documentation/ndctl/Makefile.am b/Documentation/ndctl/Makefile.am
index 4f04087598b5..70ec4597bd06 100644
--- a/Documentation/ndctl/Makefile.am
+++ b/Documentation/ndctl/Makefile.am
@@ -9,11 +9,22 @@ 
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 # General Public License for more details.
 
-do_subst = sed -e 's,UTILITY,ndctl,g'
+if USE_ASCIIDOCTOR
+
+do_subst = sed -e 's,@Utility@,Ndctl,g' -e's,@utility@,ndctl,g'
+CONFFILE = asciidoctor-extensions.rb
+asciidoctor-extensions.rb: ../asciidoctor-extensions.rb.in
+	$(AM_V_GEN) $(do_subst) < $< > $@
 
+else
+
+do_subst = sed -e 's,UTILITY,ndctl,g'
+CONFFILE = asciidoc.conf
 asciidoc.conf: ../asciidoc.conf.in
 	$(AM_V_GEN) $(do_subst) < $< > $@
 
+endif
+
 man1_MANS = \
 	ndctl.1 \
 	ndctl-wait-scrub.1 \
@@ -41,7 +52,7 @@  CLEANFILES = $(man1_MANS)
 XML_DEPS = \
 	../../version.m4 \
 	Makefile \
-	asciidoc.conf \
+	$(CONFFILE) \
 	../copyright.txt \
 	region-description.txt \
 	xable-region-options.txt \
@@ -54,6 +65,17 @@  XML_DEPS = \
 
 RM ?= rm -f
 
+if USE_ASCIIDOCTOR
+
+%.1: %.txt $(XML_DEPS)
+	$(AM_V_GEN)$(RM) $@+ $@ && \
+		$(ASCIIDOC) -b manpage -d manpage -acompat-mode \
+		-amansource=ndctl -amanmanual="ndctl Manual" \
+		-andctl_version=$(VERSION) -o $@+ $< && \
+		mv $@+ $@
+
+else
+
 %.xml: %.txt $(XML_DEPS)
 	$(AM_V_GEN)$(RM) $@+ $@ && \
 		$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
@@ -63,3 +85,5 @@  RM ?= rm -f
 %.1: %.xml $(XML_DEPS)
 	$(AM_V_GEN)$(RM) $@ && \
 		$(XMLTO) -o . -m ../manpage-normal.xsl man $<
+
+endif
diff --git a/configure.ac b/configure.ac
index 3eaac32feb80..cddad16925f8 100644
--- a/configure.ac
+++ b/configure.ac
@@ -42,16 +42,29 @@  AS_IF([test "x$enable_docs" = "xyes"], [
 ])
 AM_CONDITIONAL([ENABLE_DOCS], [test "x$enable_docs" = "xyes"])
 
-AC_CHECK_PROG(ASCIIDOC, [asciidoc], [$(which asciidoc)], [missing])
+AC_ARG_ENABLE([asciidoctor],
+	AS_HELP_STRING([--enable-asciidoctor],
+	[use asciidoctor for documentation build]),
+	[], enable_asciidoctor=no)
+AM_CONDITIONAL([USE_ASCIIDOCTOR], [test "x$enable_asciidoctor" = "xyes"])
+if test "x$enable_asciidoctor" = "xyes"; then
+	asciidoc="asciidoctor"
+else
+	asciidoc="asciidoc"
+fi
+AC_CHECK_PROG(ASCIIDOC, [$asciidoc], [$(which $asciidoc)], [missing])
 if test "x$ASCIIDOC" = xmissing -a "x$enable_docs" = "xyes"; then
-       AC_MSG_ERROR([asciidoc needed to build documentation])
+	AC_MSG_ERROR([$asciidoc needed to build documentation])
 fi
 AC_SUBST([ASCIIDOC])
+
+if test x"$asciidoc" = x"asciidoc"; then
 AC_CHECK_PROG(XMLTO, [xmlto], [$(which xmlto)], [missing])
 if test "x$XMLTO" = xmissing -a "x$enable_docs" = "xyes"; then
        AC_MSG_ERROR([xmlto needed to build documentation])
 fi
 AC_SUBST([XMLTO])
+fi
 
 AC_C_TYPEOF
 AC_DEFINE([HAVE_STATEMENT_EXPR], 1, [Define to 1 if you have statement expressions.])