[PATCH ndctl 0/2] Documentation: add asciidoctor support

[PATCH ndctl 0/2] Documentation: add asciidoctor support

[Takashi Iwai]

Hi,

this is a 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

===

Takashi Iwai (2):
  Documentation: fix title and section markers
  Documentation: Add the support for asciidoctor

 Documentation/asciidoctor-extensions.rb.in  |   28 ++++++++++++++++++++++++++++
 Documentation/daxctl/Makefile.am            |   23 ++++++++++++++++++++---
 Documentation/daxctl/daxctl-io.txt          |    5 +++--
 Documentation/daxctl/daxctl-list.txt        |   13 +++++++------
 Documentation/ndctl/Makefile.am             |   23 ++++++++++++++++++++---
 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 ++++++++-----
 configure.ac                                |   14 ++++++++++++--
 10 files changed, 110 insertions(+), 28 deletions(-)
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

[PATCH ndctl 1/2] 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-io.txt          |    5 +++--
 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 ++++++++-----
 6 files changed, 30 insertions(+), 20 deletions(-)

--- a/Documentation/ndctl/ndctl-init-labels.txt
+++ b/Documentation/ndctl/ndctl-init-labels.txt
@@ -24,7 +24,7 @@ the DIMM.
 EXAMPLE
 -------
 Find the DIMMs that comprise a given region:
-[verse]
+----
 # ndctl list -RD --region=region1
 {
   "dimms":[
@@ -49,23 +49,28 @@ Find the DIMMs that comprise a given reg
     }
   ]
 }
+----
 
 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
 -------
--- a/Documentation/ndctl/ndctl-disable-dimm.txt
+++ b/Documentation/ndctl/ndctl-disable-dimm.txt
@@ -1,5 +1,5 @@
 ndctl-disable-dimm(1)
-=======================
+=====================
 
 NAME
 ----
--- a/Documentation/ndctl/ndctl-enable-region.txt
+++ b/Documentation/ndctl/ndctl-enable-region.txt
@@ -1,5 +1,5 @@
 ndctl-enable-region(1)
-====================
+======================
 
 NAME
 ----
--- a/Documentation/daxctl/daxctl-io.txt
+++ b/Documentation/daxctl/daxctl-io.txt
@@ -1,5 +1,5 @@
 daxctl-io(1)
-===========
+============
 
 NAME
 ----
@@ -25,7 +25,7 @@ will be performed.
 
 EXAMPLE
 -------
-[verse]
+----
 # daxctl io --zero /dev/dax1.0
 
 # daxctl io --input=/dev/dax1.0 --output=/home/myfile --len=2M --seek=4096
@@ -33,6 +33,7 @@ EXAMPLE
 # cat /dev/zero | daxctl io --output=/dev/dax1.0
 
 # daxctl io --input=/dev/zero --output=/dev/dax1.0 --skip=4096
+----
 
 OPTIONS
 -------
--- a/Documentation/daxctl/daxctl-list.txt
+++ b/Documentation/daxctl/daxctl-list.txt
@@ -1,5 +1,5 @@
 daxctl-list(1)
-=============
+==============
 
 NAME
 ----
@@ -22,10 +22,9 @@ daxctl list --devices
 
 EXAMPLE
 -------
-[verse]
+----
 # daxctl list --regions --devices
 
-["literal"]
 {
   "id":1,
   "devices":[
@@ -35,6 +34,7 @@ EXAMPLE
     }
   ]
 }
+----
 
 OPTIONS
 -------
@@ -52,14 +52,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::
@@ -80,7 +80,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",
@@ -92,6 +92,7 @@ OPTIONS
   "chardev":"dax1.0",
   "size":"30.57 GiB (32.83 GB)"
 }
+----
 
 COPYRIGHT
 ---------
--- a/Documentation/ndctl/ndctl-list.txt
+++ b/Documentation/ndctl/ndctl-list.txt
@@ -21,10 +21,9 @@ ndctl list --namespaces --bus=all --regi
 
 EXAMPLE
 -------
-[verse]
+----
 # ndctl list --buses --namespaces
 
-["literal"]
 {
   "provider":"nfit_test.1",
   "dev":"ndbus2",
@@ -53,6 +52,7 @@ EXAMPLE
     }
   ]
 }
+----
 
 OPTIONS
 -------
@@ -65,8 +65,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=::
@@ -182,7 +183,7 @@ include::xable-region-options.txt[]
 
 include::human-option.txt[]
 
-[verse]
+----
 # ndctl list --region=7
 {
   "dev":"region7",
@@ -192,8 +193,9 @@ include::human-option.txt[]
   "iset_id":-6382611090938810793,
   "badblock_count":8
 }
+----
 
-[verse]
+----
 # ndctl list --human --region=7
 {
   "dev":"region7",
@@ -203,6 +205,7 @@ include::human-option.txt[]
   "iset_id":"0xa76c6907811fae57",
   "badblock_count":8
 }
+----
 
 COPYRIGHT
 ---------
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

[PATCH ndctl 2/2] 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

Signed-off-by: Takashi Iwai <tiwai@suse.de>

---
 Documentation/asciidoctor-extensions.rb.in |   28 ++++++++++++++++++++++++++++
 Documentation/daxctl/Makefile.am           |   23 ++++++++++++++++++++---
 Documentation/ndctl/Makefile.am            |   23 ++++++++++++++++++++---
 configure.ac                               |   14 ++++++++++++--
 4 files changed, 80 insertions(+), 8 deletions(-)

--- /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
--- a/Documentation/daxctl/Makefile.am
+++ b/Documentation/daxctl/Makefile.am
@@ -9,11 +9,28 @@
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 # General Public License for more details.
 
+if USE_ASCIIDOCTOR
+
+do_subst = sed -e 's,@Utility@,Daxctl,g' -e's,@utility@,daxctl,g'
+do_asciidoc = $(ASCIIDOC) -acompat-mode \
+	-amansource=daxctl -amanmanual="daxctl Manual"
+
+XMLTO += --skip-validation
+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'
+do_asciidoc = $(ASCIIDOC) -f asciidoc.conf --unsafe
 
+CONFFILE = asciidoc.conf
 asciidoc.conf: ../asciidoc.conf.in
 	$(AM_V_GEN) $(do_subst) < $< > $@
 
+endif
+
 man1_MANS = \
 	daxctl.1 \
 	daxctl-list.1 \
@@ -24,14 +41,14 @@ CLEANFILES = $(man1_MANS)
 XML_DEPS = \
 	../../version.m4 \
 	Makefile \
-	asciidoc.conf
+	$(CONFFILE)
 
 RM ?= rm -f
 
 %.xml: %.txt $(XML_DEPS)
 	$(AM_V_GEN)$(RM) $@+ $@ && \
-		$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
-		--unsafe -adaxctl_version=$(VERSION) -o $@+ $< && \
+		$(do_asciidoc) -b docbook -d manpage \
+		-adaxctl_version=$(VERSION) -o $@+ $< && \
 		mv $@+ $@
 
 %.1: %.xml
--- a/Documentation/ndctl/Makefile.am
+++ b/Documentation/ndctl/Makefile.am
@@ -9,11 +9,28 @@
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 # General Public License for more details.
 
+if USE_ASCIIDOCTOR
+
+do_subst = sed -e 's,@Utility@,Ndctl,g' -e's,@utility@,ndctl,g'
+do_asciidoc = $(ASCIIDOC) -acompat-mode \
+	-amansource=ndctl -amanmanual="ndctl Manual"
+
+XMLTO += --skip-validation
+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'
+do_asciidoc = $(ASCIIDOC) -f asciidoc.conf --unsafe
 
+CONFFILE = asciidoc.conf
 asciidoc.conf: ../asciidoc.conf.in
 	$(AM_V_GEN) $(do_subst) < $< > $@
 
+endif
+
 man1_MANS = \
 	ndctl.1 \
 	ndctl-zero-labels.1 \
@@ -39,7 +56,7 @@ CLEANFILES = $(man1_MANS)
 XML_DEPS = \
 	../../version.m4 \
 	Makefile \
-	asciidoc.conf \
+	$(CONFFILE) \
 	region-description.txt \
 	xable-region-options.txt \
 	dimm-description.txt \
@@ -52,8 +69,8 @@ RM ?= rm -f
 
 %.xml: %.txt $(XML_DEPS)
 	$(AM_V_GEN)$(RM) $@+ $@ && \
-		$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
-		--unsafe -andctl_version=$(VERSION) -o $@+ $< && \
+		$(ASCIIDOC) -b docbook -d manpage \
+		-andctl_version=$(VERSION) -o $@+ $< && \
 		mv $@+ $@
 
 %.1: %.xml
--- a/configure.ac
+++ b/configure.ac
@@ -42,9 +42,19 @@ 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])
 AC_CHECK_PROG(XMLTO, [xmlto], [$(which xmlto)], [missing])
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

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

[Verma, Vishal L]

On Thu, 2018-04-12 at 13:07 +0200, Takashi Iwai wrote:
> Hi,
> 
> this is a 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

Hi Takashi,

Thanks for these patches - they look good in general. However since we are
so close to the v60 release, may I ask you to rebase these once v60 is out?
(targeting early next week..)

There will be a few documentation updates in v60, and it would be nice to
get this series applied right after v60 is out.

	-Vishal

> 
> ===
> 
> Takashi Iwai (2):
>   Documentation: fix title and section markers
>   Documentation: Add the support for asciidoctor
> 
>  Documentation/asciidoctor-extensions.rb.in  |   28
> ++++++++++++++++++++++++++++
>  Documentation/daxctl/Makefile.am            |   23 ++++++++++++++++++++-
> --
>  Documentation/daxctl/daxctl-io.txt          |    5 +++--
>  Documentation/daxctl/daxctl-list.txt        |   13 +++++++------
>  Documentation/ndctl/Makefile.am             |   23 ++++++++++++++++++++-
> --
>  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 ++++++++-----
>  configure.ac                                |   14 ++++++++++++--
>  10 files changed, 110 insertions(+), 28 deletions(-)
> _______________________________________________
> Linux-nvdimm mailing list
> Linux-nvdimm@lists.01.org
> https://lists.01.org/mailman/listinfo/linux-nvdimm
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

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

[Takashi Iwai]

On Fri, 13 Apr 2018 03:03:37 +0200,
Verma, Vishal L wrote:
> 
> On Thu, 2018-04-12 at 13:07 +0200, Takashi Iwai wrote:
> > Hi,
> > 
> > this is a 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
> 
> Hi Takashi,
> 
> Thanks for these patches - they look good in general. However since we are
> so close to the v60 release, may I ask you to rebase these once v60 is out?
> (targeting early next week..)
> 
> There will be a few documentation updates in v60, and it would be nice to
> get this series applied right after v60 is out.

Sure, will rebase and resubmit later.


thanks,

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