Skip to contentSkip to conversation

Documentation: add asciidoctor support

PATCH Superseded Takashi Iwai 2 participants 5 messages Apr 12, 2018 – Apr 13, 2018

Subsystems (2)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

cover Documentation: add asciidoctor support

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
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm

#1 lore raw

PATCH 1/2 Documentation: fix title and section markers

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.

---
 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(-)
Documentation/ndctl/ndctl-init-labels.txt +10 -5
@@ -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
 -------
Documentation/ndctl/ndctl-disable-dimm.txt +1 -1
@@ -1,5 +1,5 @@
 ndctl-disable-dimm(1)
-=======================
+=====================
 
 NAME
 ----
Documentation/ndctl/ndctl-enable-region.txt +1 -1
@@ -1,5 +1,5 @@
 ndctl-enable-region(1)
-====================
+======================
 
 NAME
 ----
Documentation/daxctl/daxctl-io.txt +3 -2
@@ -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
 -------
Documentation/daxctl/daxctl-list.txt +7 -6
@@ -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
 ---------
Documentation/ndctl/ndctl-list.txt +8 -5
@@ -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
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm

#2 lore raw

PATCH 2/2 Documentation: Add the support for asciidoctor

In reply to 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

---
 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(-)
Documentation/asciidoctor-extensions.rb.in new file +28 -0
@@ -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
Documentation/daxctl/Makefile.am +20 -3
@@ -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
Documentation/ndctl/Makefile.am +20 -3
@@ -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
configure.ac +12 -2
@@ -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
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm

maintainer
#3 lore raw
In reply to Takashi Iwai
Quoted 7 lines · 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 :)

Quoted 7 lines

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

Quoted 21 lines

===

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(-)
Quoted 4 lines

_______________________________________________
Linux-nvdimm mailing list
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm

_______________________________________________
Linux-nvdimm mailing list
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm

#4 lore raw
Quoted 17 lines · Vishal L
Quoted 7 lines · 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 :)

Quoted 7 lines

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

thanks,

Takashi

Quoted 8 lines

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
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm