Documentation: add asciidoctor support
Subsystems (2)
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
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
PATCH 2/2 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
--- 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
Verma, Vishal L
maintainerQuoted 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 asciidoctorDocumentation/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
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