* [PATCH ndctl 1/2] Documentation: fix title and section markers
2018-04-12 11:07 [PATCH ndctl 0/2] Documentation: add asciidoctor support Takashi Iwai
@ 2018-04-12 11:07 ` Takashi Iwai
2018-04-12 11:07 ` [PATCH ndctl 2/2] Documentation: Add the support for asciidoctor Takashi Iwai
2018-04-13 1:03 ` [PATCH ndctl 0/2] Documentation: add asciidoctor support Verma, Vishal L
2 siblings, 0 replies; 5+ messages in thread
From: Takashi Iwai @ 2018-04-12 11:07 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-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
^ permalink raw reply [flat|nested] 5+ messages in thread* [PATCH ndctl 2/2] Documentation: Add the support for asciidoctor
2018-04-12 11:07 [PATCH ndctl 0/2] Documentation: add asciidoctor support Takashi Iwai
2018-04-12 11:07 ` [PATCH ndctl 1/2] Documentation: fix title and section markers Takashi Iwai
@ 2018-04-12 11:07 ` Takashi Iwai
2018-04-13 1:03 ` [PATCH ndctl 0/2] Documentation: add asciidoctor support Verma, Vishal L
2 siblings, 0 replies; 5+ messages in thread
From: Takashi Iwai @ 2018-04-12 11:07 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
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
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH ndctl 0/2] Documentation: add asciidoctor support
2018-04-12 11:07 [PATCH ndctl 0/2] Documentation: add asciidoctor support Takashi Iwai
2018-04-12 11:07 ` [PATCH ndctl 1/2] Documentation: fix title and section markers Takashi Iwai
2018-04-12 11:07 ` [PATCH ndctl 2/2] Documentation: Add the support for asciidoctor Takashi Iwai
@ 2018-04-13 1:03 ` Verma, Vishal L
2018-04-13 7:28 ` Takashi Iwai
2 siblings, 1 reply; 5+ messages in thread
From: Verma, Vishal L @ 2018-04-13 1:03 UTC (permalink / raw)
To: linux-nvdimm@lists.01.org, tiwai@suse.de
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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH ndctl 0/2] Documentation: add asciidoctor support
2018-04-13 1:03 ` [PATCH ndctl 0/2] Documentation: add asciidoctor support Verma, Vishal L
@ 2018-04-13 7:28 ` Takashi Iwai
0 siblings, 0 replies; 5+ messages in thread
From: Takashi Iwai @ 2018-04-13 7:28 UTC (permalink / raw)
To: Verma, Vishal L; +Cc: linux-nvdimm@lists.01.org
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
^ permalink raw reply [flat|nested] 5+ messages in thread