nvdimm.lists.linux.dev archive mirror
 help / color / mirror / Atom feed
* [PATCH ndctl v2 0/3] Documentation: add asciidoctor support
@ 2018-04-19 15:11 Takashi Iwai
  2018-04-19 15:11 ` [PATCH ndctl v2 1/3] Documentation: fix title and section markers Takashi Iwai
                   ` (3 more replies)
  0 siblings, 4 replies; 7+ messages in thread
From: Takashi Iwai @ 2018-04-19 15:11 UTC (permalink / raw)
  To: linux-nvdimm

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

===

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  | 28 ++++++++++++++++++++++++++++
 Documentation/daxctl/Makefile.am            | 28 ++++++++++++++++++++++++++--
 Documentation/daxctl/daxctl-list.txt        | 13 +++++++------
 Documentation/ndctl/Makefile.am             | 28 ++++++++++++++++++++++++++--
 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, 132 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

^ permalink raw reply	[flat|nested] 7+ messages in thread
* [PATCH ndctl v2 1/3] Documentation: fix title and section markers
  2018-04-19 15:11 [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai
@ 2018-04-19 15:11 ` Takashi Iwai
  2018-04-19 15:11 ` [PATCH ndctl v2 2/3] Documentation: Add the support for asciidoctor Takashi Iwai
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 7+ messages in thread
From: Takashi Iwai @ 2018-04-19 15:11 UTC (permalink / raw)
  To: linux-nvdimm

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

^ permalink raw reply related	[flat|nested] 7+ messages in thread
* [PATCH ndctl v2 2/3] Documentation: Add the support for asciidoctor
  2018-04-19 15:11 [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai
  2018-04-19 15:11 ` [PATCH ndctl v2 1/3] Documentation: fix title and section markers Takashi Iwai
@ 2018-04-19 15:11 ` Takashi Iwai
  2018-04-23 21:46   ` Verma, Vishal L
  2018-04-19 15:11 ` [PATCH ndctl v2 3/3] Documentation: add asciidoctor-extensions.rb to .gitignore Takashi Iwai
  2018-04-19 15:12 ` [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai
  3 siblings, 1 reply; 7+ messages in thread
From: Takashi Iwai @ 2018-04-19 15:11 UTC (permalink / raw)
  To: linux-nvdimm

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@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.])
-- 
2.16.3

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

^ permalink raw reply related	[flat|nested] 7+ messages in thread
* [PATCH ndctl v2 3/3] Documentation: add asciidoctor-extensions.rb to .gitignore
  2018-04-19 15:11 [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai
  2018-04-19 15:11 ` [PATCH ndctl v2 1/3] Documentation: fix title and section markers Takashi Iwai
  2018-04-19 15:11 ` [PATCH ndctl v2 2/3] Documentation: Add the support for asciidoctor Takashi Iwai
@ 2018-04-19 15:11 ` Takashi Iwai
  2018-04-19 15:12 ` [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai
  3 siblings, 0 replies; 7+ messages in thread
From: Takashi Iwai @ 2018-04-19 15:11 UTC (permalink / raw)
  To: linux-nvdimm

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

^ permalink raw reply related	[flat|nested] 7+ messages in thread
* Re: [PATCH ndctl v2 0/3] Documentation: add asciidoctor support
  2018-04-19 15:11 [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai
                   ` (2 preceding siblings ...)
  2018-04-19 15:11 ` [PATCH ndctl v2 3/3] Documentation: add asciidoctor-extensions.rb to .gitignore Takashi Iwai
@ 2018-04-19 15:12 ` Takashi Iwai
  3 siblings, 0 replies; 7+ messages in thread
From: Takashi Iwai @ 2018-04-19 15:12 UTC (permalink / raw)
  To: linux-nvdimm

On Thu, 19 Apr 2018 17:11: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

... and of course, rebased to shiny v60.


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

^ permalink raw reply	[flat|nested] 7+ messages in thread
* Re: [PATCH ndctl v2 2/3] Documentation: Add the support for asciidoctor
  2018-04-19 15:11 ` [PATCH ndctl v2 2/3] Documentation: Add the support for asciidoctor Takashi Iwai
@ 2018-04-23 21:46   ` Verma, Vishal L
  2018-04-24 10:13     ` Takashi Iwai
  0 siblings, 1 reply; 7+ messages in thread
From: Verma, Vishal L @ 2018-04-23 21:46 UTC (permalink / raw)
  To: linux-nvdimm, tiwai

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
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

^ permalink raw reply	[flat|nested] 7+ messages in thread
* Re: [PATCH ndctl v2 2/3] Documentation: Add the support for asciidoctor
  2018-04-23 21:46   ` Verma, Vishal L
@ 2018-04-24 10:13     ` Takashi Iwai
  0 siblings, 0 replies; 7+ messages in thread
From: Takashi Iwai @ 2018-04-24 10:13 UTC (permalink / raw)
  To: Verma, Vishal L; +Cc: linux-nvdimm

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
_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm

^ permalink raw reply	[flat|nested] 7+ messages in thread
end of thread, other threads:[~2018-04-24 10:13 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-04-19 15:11 [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai
2018-04-19 15:11 ` [PATCH ndctl v2 1/3] Documentation: fix title and section markers Takashi Iwai
2018-04-19 15:11 ` [PATCH ndctl v2 2/3] Documentation: Add the support for asciidoctor Takashi Iwai
2018-04-23 21:46   ` Verma, Vishal L
2018-04-24 10:13     ` Takashi Iwai
2018-04-19 15:11 ` [PATCH ndctl v2 3/3] Documentation: add asciidoctor-extensions.rb to .gitignore Takashi Iwai
2018-04-19 15:12 ` [PATCH ndctl v2 0/3] Documentation: add asciidoctor support Takashi Iwai

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).