[PATCH ndctl v3 0/3] Documentation: add asciidoctor support

[PATCH ndctl v3 0/3] Documentation: add asciidoctor support

[Takashi Iwai]

Hi,

this is a revised patchset to add the support for asciidoctor to
generate documents.  The reason for adding this feature is that the
future of asciidoc isn't clear as it's written in python2, which is
now hated by all people out of sudden :)

The asciidoctor support is enabled via configure option, the default
is still asciidoc for now.

thanks,

Takashi


v1->v2:
 * more marker fixes to ndctl man pages
 * skip superfluous xmlto processing for asciidoctor
 * add .gitignore entries
 * rebased to v60

v2->v3:
 * fix the link processing regression in v2

===

Takashi Iwai (3):
  Documentation: fix title and section markers
  Documentation: Add the support for asciidoctor
  Documentation: add asciidoctor-extensions.rb to .gitignore

 .gitignore                                  |  2 ++
 Documentation/asciidoctor-extensions.rb.in  | 30 +++++++++++++++++++++++++++++
 Documentation/daxctl/Makefile.am            | 29 ++++++++++++++++++++++++++--
 Documentation/daxctl/daxctl-list.txt        | 13 +++++++------
 Documentation/ndctl/Makefile.am             | 29 ++++++++++++++++++++++++++--
 Documentation/ndctl/ndctl-disable-dimm.txt  |  2 +-
 Documentation/ndctl/ndctl-enable-region.txt |  2 +-
 Documentation/ndctl/ndctl-init-labels.txt   | 15 ++++++++++-----
 Documentation/ndctl/ndctl-list.txt          | 13 ++++++++-----
 Documentation/ndctl/ndctl-start-scrub.txt   |  6 ++++--
 Documentation/ndctl/ndctl-wait-scrub.txt    |  6 ++++--
 configure.ac                                | 17 ++++++++++++++--
 12 files changed, 136 insertions(+), 28 deletions(-)
 create mode 100644 Documentation/asciidoctor-extensions.rb.in

-- 
2.16.3

_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

[PATCH ndctl v3 1/3] Documentation: fix title and section markers

[Takashi Iwai]

The length of the title and section marker has to be aligned with the
previous line.  This was caught when running asciidoctor, which is
more strict than asciidoc.

Also since asciidoctor doesn't like the verse block in some cases,
replace the code examples with simpler markers.

Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
 Documentation/daxctl/daxctl-list.txt        | 13 +++++++------
 Documentation/ndctl/ndctl-disable-dimm.txt  |  2 +-
 Documentation/ndctl/ndctl-enable-region.txt |  2 +-
 Documentation/ndctl/ndctl-init-labels.txt   | 15 ++++++++++-----
 Documentation/ndctl/ndctl-list.txt          | 13 ++++++++-----
 Documentation/ndctl/ndctl-start-scrub.txt   |  6 ++++--
 Documentation/ndctl/ndctl-wait-scrub.txt    |  6 ++++--
 7 files changed, 35 insertions(+), 22 deletions(-)

diff --git a/Documentation/daxctl/daxctl-list.txt b/Documentation/daxctl/daxctl-list.txt
index 99ca4a1b4f28..cb82c3cc6fb2 100644
--- a/Documentation/daxctl/daxctl-list.txt
+++ b/Documentation/daxctl/daxctl-list.txt
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0
 
 daxctl-list(1)
-=============
+==============
 
 NAME
 ----
@@ -24,10 +24,9 @@ daxctl list --devices
 
 EXAMPLE
 -------
-[verse]
+----
 # daxctl list --regions --devices
 
-["literal"]
 {
   "id":1,
   "devices":[
@@ -37,6 +36,7 @@ EXAMPLE
     }
   ]
 }
+----
 
 OPTIONS
 -------
@@ -54,14 +54,14 @@ OPTIONS
 	tuple, or keyword 'all' to filter the listing. For
 	example to list the first device instance in region1:
 
-[verse]
+----
 # daxctl list --dev=1.0
 
-["literal"]
 {
   "chardev":"dax1.0",
   "size":3233808384
 }
+----
 
 -D::
 --devices::
@@ -82,7 +82,7 @@ OPTIONS
 	will be formatted as human readable strings with units, other
 	fields are converted to hexadecimal strings.  Example:
 
-[verse]
+----
 # daxctl list
 {
   "chardev":"dax1.0",
@@ -94,5 +94,6 @@ OPTIONS
   "chardev":"dax1.0",
   "size":"30.57 GiB (32.83 GB)"
 }
+----
 
 include::../copyright.txt[]
diff --git a/Documentation/ndctl/ndctl-disable-dimm.txt b/Documentation/ndctl/ndctl-disable-dimm.txt
index d5a8d19966cf..7706ac351abc 100644
--- a/Documentation/ndctl/ndctl-disable-dimm.txt
+++ b/Documentation/ndctl/ndctl-disable-dimm.txt
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0
 
 ndctl-disable-dimm(1)
-=======================
+=====================
 
 NAME
 ----
diff --git a/Documentation/ndctl/ndctl-enable-region.txt b/Documentation/ndctl/ndctl-enable-region.txt
index 6c4ad9fefb0a..e5cbddbe6cf7 100644
--- a/Documentation/ndctl/ndctl-enable-region.txt
+++ b/Documentation/ndctl/ndctl-enable-region.txt
@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0
 
 ndctl-enable-region(1)
-====================
+======================
 
 NAME
 ----
diff --git a/Documentation/ndctl/ndctl-init-labels.txt b/Documentation/ndctl/ndctl-init-labels.txt
index 580d82aa99cf..736d52d03cab 100644
--- a/Documentation/ndctl/ndctl-init-labels.txt
+++ b/Documentation/ndctl/ndctl-init-labels.txt
@@ -26,7 +26,7 @@ the DIMM.
 EXAMPLE
 -------
 Find the DIMMs that comprise a given region:
-[verse]
+----
 # ndctl list -RD --region=region1
 {
   "dimms":[
@@ -51,23 +51,28 @@ Find the DIMMs that comprise a given region:
     }
   ]
 }
+----
 
 Disable that region so the DIMM label area can be written from
 userspace:
-[verse]
+----
 # ndctl disable-region region1
+----
 
 Initialize labels:
-[verse]
+----
 # ndctl init-labels nmem0
+----
 
 Re-enable the region:
-[verse]
+----
 # ndctl enable-region region1
+----
 
 Create a namespace in that region:
-[verse]
+----
 # ndctl create-namespace --region=region1
+----
 
 OPTIONS
 -------
diff --git a/Documentation/ndctl/ndctl-list.txt b/Documentation/ndctl/ndctl-list.txt
index 2abc572a6ad5..13ebdcdd55ff 100644
--- a/Documentation/ndctl/ndctl-list.txt
+++ b/Documentation/ndctl/ndctl-list.txt
@@ -23,10 +23,9 @@ ndctl list --namespaces --bus=all --region=all
 
 EXAMPLE
 -------
-[verse]
+----
 # ndctl list --buses --namespaces
 
-["literal"]
 {
   "provider":"nfit_test.1",
   "dev":"ndbus2",
@@ -55,6 +54,7 @@ EXAMPLE
     }
   ]
 }
+----
 
 OPTIONS
 -------
@@ -67,8 +67,9 @@ include::xable-region-options.txt[]
 	An 'nmemX' device name, or dimm id number. Filter listing by
 	devices that reference the given dimm. For example to see all
 	namespaces comprised of storage capacity on nmem0:
-[verse]
+----
 # ndctl list --dimm=nmem0 --namespaces
+----
 
 -n::
 --namespace=::
@@ -201,7 +202,7 @@ include::xable-region-options.txt[]
 
 include::human-option.txt[]
 
-[verse]
+----
 # ndctl list --region=7
 {
   "dev":"region7",
@@ -211,8 +212,9 @@ include::human-option.txt[]
   "iset_id":-6382611090938810793,
   "badblock_count":8
 }
+----
 
-[verse]
+----
 # ndctl list --human --region=7
 {
   "dev":"region7",
@@ -222,6 +224,7 @@ include::human-option.txt[]
   "iset_id":"0xa76c6907811fae57",
   "badblock_count":8
 }
+----
 
 include::../copyright.txt[]
 
diff --git a/Documentation/ndctl/ndctl-start-scrub.txt b/Documentation/ndctl/ndctl-start-scrub.txt
index 365918dec920..eb49fc28e9bc 100644
--- a/Documentation/ndctl/ndctl-start-scrub.txt
+++ b/Documentation/ndctl/ndctl-start-scrub.txt
@@ -24,7 +24,7 @@ EXAMPLE
 -------
 Start a scrub on all nvdimm buses in the system. The json listing report
 only includes the buses that support ARS operations.
-[verse]
+----
 
 # ndctl start-scrub
 [
@@ -39,12 +39,14 @@ only includes the buses that support ARS operations.
     "scrub_state":"active"
   }
 ]
+----
 
 When specifying an individual bus, or if there is only one bus in the
 system, the command reports whether ARS support is available.
-[verse]
+----
 # ndctl start-scrub e820
 error starting scrub: Operation not supported
+----
 
 OPTIONS
 -------
diff --git a/Documentation/ndctl/ndctl-wait-scrub.txt b/Documentation/ndctl/ndctl-wait-scrub.txt
index 6b5f61fcf48f..9aef68704d6b 100644
--- a/Documentation/ndctl/ndctl-wait-scrub.txt
+++ b/Documentation/ndctl/ndctl-wait-scrub.txt
@@ -25,7 +25,7 @@ EXAMPLE
 -------
 Wait for scrub on all nvdimm buses in the system. The json listing
 report at the end only includes the buses that support ARS operations.
-[verse]
+----
 # ndctl wait-scrub
 [
   {
@@ -39,12 +39,14 @@ report at the end only includes the buses that support ARS operations.
     "scrub_state":"idle"
   }
 ]
+----
 
 When specifying an individual bus, or if there is only one bus in the
 system, the command reports whether ARS support is available.
-[verse]
+----
 # ndctl wait-scrub e820
 error waiting for scrub completion: Operation not supported
+----
 
 OPTIONS
 -------
-- 
2.16.3

_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

[PATCH ndctl v3 2/3] Documentation: Add the support for asciidoctor

[Takashi Iwai]

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 | 30 ++++++++++++++++++++++++++++++
 Documentation/daxctl/Makefile.am           | 29 +++++++++++++++++++++++++++--
 Documentation/ndctl/Makefile.am            | 29 +++++++++++++++++++++++++++--
 configure.ac                               | 17 +++++++++++++++--
 4 files changed, 99 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..a0307d0cacef
--- /dev/null
+++ b/Documentation/asciidoctor-extensions.rb.in
@@ -0,0 +1,30 @@
+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? 'manpage'
+          "#{target}(#{attrs[1]})"
+        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..fc0fbe138d93 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,22 @@ 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 \
+		-I. -rasciidoctor-extensions \
+		-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 +60,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 fab05b91b23a..4fd9636faa0f 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 \
@@ -42,7 +53,7 @@ CLEANFILES = $(man1_MANS)
 XML_DEPS = \
 	../../version.m4 \
 	Makefile \
-	asciidoc.conf \
+	$(CONFFILE) \
 	../copyright.txt \
 	region-description.txt \
 	xable-region-options.txt \
@@ -55,6 +66,18 @@ XML_DEPS = \
 
 RM ?= rm -f
 
+if USE_ASCIIDOCTOR
+
+%.1: %.txt $(XML_DEPS)
+	$(AM_V_GEN)$(RM) $@+ $@ && \
+		$(ASCIIDOC) -b manpage -d manpage -acompat-mode \
+		-I. -rasciidoctor-extensions \
+		-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 \
@@ -64,3 +87,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.])
-- 
2.16.3

_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

[PATCH ndctl v3 3/3] Documentation: add asciidoctor-extensions.rb to .gitignore

[Takashi Iwai]

Two new files were added for asciidoctor support.

Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
 .gitignore | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 20a04dedd862..c7d11d91398c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,8 @@ Makefile.in
 *.1
 Documentation/daxctl/asciidoc.conf
 Documentation/ndctl/asciidoc.conf
+Documentation/daxctl/asciidoctor-extensions.rb
+Documentation/ndctl/asciidoctor-extensions.rb
 .dirstamp
 daxctl/daxctl
 daxctl/lib/libdaxctl.la
-- 
2.16.3

_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

Re: [PATCH ndctl v3 0/3] Documentation: add asciidoctor support

[Verma, Vishal L]

On Tue, 2018-04-24 at 12:17 +0200, Takashi Iwai wrote:
> Hi,
> 
> this is a revised patchset to add the support for asciidoctor to
> generate documents.  The reason for adding this feature is that the
> future of asciidoc isn't clear as it's written in python2, which is
> now hated by all people out of sudden :)
> 
> The asciidoctor support is enabled via configure option, the default
> is still asciidoc for now.
> 
> thanks,
> 
> Takashi
> 
> 
> v1->v2:
>  * more marker fixes to ndctl man pages
>  * skip superfluous xmlto processing for asciidoctor
>  * add .gitignore entries
>  * rebased to v60
> 
> v2->v3:
>  * fix the link processing regression in v2

Thanks for the fix! Looks good now, queued for v61.

> 
> ===
> 
> Takashi Iwai (3):
>   Documentation: fix title and section markers
>   Documentation: Add the support for asciidoctor
>   Documentation: add asciidoctor-extensions.rb to .gitignore
> 
>  .gitignore                                  |  2 ++
>  Documentation/asciidoctor-extensions.rb.in  | 30
> +++++++++++++++++++++++++++++
>  Documentation/daxctl/Makefile.am            | 29
> ++++++++++++++++++++++++++--
>  Documentation/daxctl/daxctl-list.txt        | 13 +++++++------
>  Documentation/ndctl/Makefile.am             | 29
> ++++++++++++++++++++++++++--
>  Documentation/ndctl/ndctl-disable-dimm.txt  |  2 +-
>  Documentation/ndctl/ndctl-enable-region.txt |  2 +-
>  Documentation/ndctl/ndctl-init-labels.txt   | 15 ++++++++++-----
>  Documentation/ndctl/ndctl-list.txt          | 13 ++++++++-----
>  Documentation/ndctl/ndctl-start-scrub.txt   |  6 ++++--
>  Documentation/ndctl/ndctl-wait-scrub.txt    |  6 ++++--
>  configure.ac                                | 17 ++++++++++++++--
>  12 files changed, 136 insertions(+), 28 deletions(-)
>  create mode 100644 Documentation/asciidoctor-extensions.rb.in
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm