Documentation: add asciidoctor support

Hi,

this is a patchset to add the support for asciidoctor to generate documents. asciidoc is based on python2, and its future isn't clear, so as a plan-B, we can use asciidoctor instead.

The asciidoctor support is opt-in, the default is still kept for asciidoc for now.

thanks,

Takashi

===

Takashi Iwai (2):
Documentation: fix title markers
Documentation: allow to format with asciidoctor

 Documentation/Makefile                   |   13 +++++++++++++
 Documentation/asciidoctor-extensions.rb  |   29 +++++++++++++++++++++++++++++
 Documentation/nvme-discover.txt          |    2 +-
 Documentation/nvme-huawei-id-ctrl.txt    |    2 +-
 Documentation/nvme-wdc-id-ctrl.txt       |    2 +-
 Documentation/nvme-wdc-purge-monitor.txt |    2 +-
 Documentation/nvme-wdc-purge.txt         |    2 +-
 7 files changed, 47 insertions(+), 5 deletions(-)

The length of the title marker has to be aligned with the previous line. This was caught when running asciidoctor, which is more strict than asciidoc.

---
 Documentation/nvme-discover.txt          |    2 +-
 Documentation/nvme-huawei-id-ctrl.txt    |    2 +-
 Documentation/nvme-wdc-id-ctrl.txt       |    2 +-
 Documentation/nvme-wdc-purge-monitor.txt |    2 +-
 Documentation/nvme-wdc-purge.txt         |    2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

@@ -1,5 +1,5 @@
 nvme-discover(1)
-==============
+================
 
 NAME
 ----

@@ -1,5 +1,5 @@
 nvme-huawei-id-ctrl(1)
-=====================
+======================
 
 NAME
 ----

@@ -1,5 +1,5 @@
 nvme-wdc-id-ctrl(1)
-=====================
+===================
 
 NAME
 ----

@@ -1,5 +1,5 @@
 nvme-wdc-purge-monitor(1)
-==========================
+=========================
 
 NAME
 ----

@@ -1,5 +1,5 @@
 nvme-wdc-purge(1)
-==================
+=================
 
 NAME
 ----

Add asciidoctor support. You need to pass USE_ASCIIDOCTOR=yes to make for enabling the feature.

Most of the rb extension code was shamelessly borrowed from git.

---
 Documentation/Makefile                  |   13 +++++++++++++
 Documentation/asciidoctor-extensions.rb |   29 +++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

@@ -35,6 +35,19 @@ MAN_REPO = ../../nvme-manpages
 
 ASCIIDOC_HTML = xhtml11
 ASCIIDOC_CONF = -f asciidoc.conf
+
+ifdef USE_ASCIIDOCTOR
+ASCIIDOC = asciidoctor
+ASCIIDOC_CONF =
+ASCIIDOC_HTML = xhtml5
+ASCIIDOC_DOCBOOK = docbook45
+ASCIIDOC_EXTRA += -acompat-mode
+ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
+ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ASCIIDOC_EXTRA += -amansource='NVMe'
+ASCIIDOC_EXTRA += -amanmanual='NVMe Manual'
+endif
+
 ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF)
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
 

@@ -0,0 +1,29 @@
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+
+module Nvme
+  module Documentation
+    class LinkNvmeProcessor < Asciidoctor::Extensions::InlineMacroProcessor
+      use_dsl
+
+      named :chrome
+
+      def process(parent, target, attrs)
+        if parent.document.basebackend? 'html'
+          %(<a href="#{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 Nvme::Documentation::LinkNvmeProcessor, :linknvme
+end

Just a gentle reminder about this patchset.

I've seen reviewed-by from Sagi, but couldn't find any other reactions, also not on github repo.

Let me know if I need to fix or resend.

thanks,

Takashi

For the series,
Reviewed-by: Johannes Thumshirn <jthumshirn at suse.de>

Johannes Thumshirn                                          Storage
jthumshirn at suse.de                                +49 911 74053 689
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 N?rnberg
GF: Felix Imend?rffer, Jane Smithard, Graham Norton
HRB 21284 (AG N?rnberg)
Key fingerprint = EC38 9CAB C2C4 F25D 8600 D0D0 0393 969D 2D76 0850

Applied, thanks (and sorry for the delay).

Great, thanks!

Takashi