12:17 p.m.
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
12:17 p.m.
New subject: [PATCH ndctl v3 1/3] 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.
Signed-off-by: Takashi Iwai <tiwai(a)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
12:17 p.m.
New subject: [PATCH ndctl v3 2/3] Documentation: Add the support for asciidoctor
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(a)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
12:17 p.m.
New subject: [PATCH ndctl v3 3/3] Documentation: add asciidoctor-extensions.rb to .gitignore
Two new files were added for asciidoctor support.
Signed-off-by: Takashi Iwai <tiwai(a)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
9:24 p.m.
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
953
days inactive
953
days old
4 comments
2 participants
participants (2)
-
Takashi Iwai -
Verma, Vishal L