Documentation: add asciidoctor support
Subsystems (2)
v3 cover Documentation: add asciidoctor support
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
Signature · 6 lines
2.16.3 _______________________________________________ Linux-nvdimm mailing list [email protected] https://lists.01.org/mailman/listinfo/linux-nvdimm
PATCH 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.
--- 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(-)
Documentation/daxctl/daxctl-list.txt +7 -6
@@ -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[]
Documentation/ndctl/ndctl-disable-dimm.txt +1 -1
@@ -1,7 +1,7 @@ // SPDX-License-Identifier: GPL-2.0 ndctl-disable-dimm(1) -======================= +===================== NAME ----
Documentation/ndctl/ndctl-enable-region.txt +1 -1
@@ -1,7 +1,7 @@ // SPDX-License-Identifier: GPL-2.0 ndctl-enable-region(1) -==================== +====================== NAME ----
Documentation/ndctl/ndctl-init-labels.txt +10 -5
@@ -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 -------
Documentation/ndctl/ndctl-list.txt +8 -5
@@ -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[]
Documentation/ndctl/ndctl-start-scrub.txt +4 -2
@@ -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 -------
Documentation/ndctl/ndctl-wait-scrub.txt +4 -2
@@ -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 -------
Signature · 6 lines
2.16.3 _______________________________________________ Linux-nvdimm mailing list [email protected] https://lists.01.org/mailman/listinfo/linux-nvdimm
PATCH v3 2/3 Documentation: Add the support for asciidoctor
In reply to Takashi IwaiThis 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
--- 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
Documentation/asciidoctor-extensions.rb.in new file +30 -0
@@ -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
Documentation/daxctl/Makefile.am +27 -2
@@ -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
Documentation/ndctl/Makefile.am +27 -2
@@ -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
configure.ac +15 -2
@@ -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.])
Signature · 6 lines
2.16.3 _______________________________________________ Linux-nvdimm mailing list [email protected] https://lists.01.org/mailman/listinfo/linux-nvdimm
PATCH v3 3/3 Documentation: add asciidoctor-extensions.rb to .gitignore
In reply to Takashi IwaiTwo new files were added for asciidoctor support.
--- .gitignore | 2 ++ 1 file changed, 2 insertions(+)
.gitignore +2 -0
@@ -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
Signature · 6 lines
2.16.3 _______________________________________________ Linux-nvdimm mailing list [email protected] https://lists.01.org/mailman/listinfo/linux-nvdimm
Verma, Vishal L
maintainerQuoted 15 lines · Takashi Iwai
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
Quoted 8 lines
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.
Quoted 17 lines
===
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 +-
Quoted 8 lines
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
_______________________________________________
Linux-nvdimm mailing list
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm