Commit ffef80ec authored by Takashi Iwai's avatar Takashi Iwai Committed by Arnaldo Carvalho de Melo
Browse files

perf Documentation: Support for asciidoctor 



The asciidoc package seems behind the recent big wave of python3
conversion, and we were advised to switch to asciidoctor instead.  It's
almost compatible but some extensions used for perf documentation don't
work with it.  Here is the patch to cover them, and add the proper
support for asciidoctor.

Pass USE_ASCIIDOCTOR=yes to make for using asciidoctor instead of
asciidoc.  The man source and manual attributes are passed via command
options.  The support for these attributes have been fixed in the
latest asciidoctor code.

Since asciidoctor can covert to a man page and an HTML directly, we
can omit the dependency on xmlto when USE_ASCIIDOCTOR is set.

Signed-off-by: default avatarTakashi Iwai <tiwai@suse.de>
Cc: Peter Zijlstra <peterz@infradead.org>
Link: http://lkml.kernel.org/r/20180424150456.17353-1-tiwai@suse.de


Signed-off-by: default avatarArnaldo Carvalho de Melo <acme@redhat.com>
parent 83cf774b

tools/perf/Documentation/Makefile

+24 −5
Original line number Diff line number Diff line
@@ -47,7 +47,8 @@ man5dir=$(mandir)/man5 
man7dir=$(mandir)/man7



ASCIIDOC=asciidoc

ASCIIDOC_EXTRA = --unsafe

ASCIIDOC_EXTRA = --unsafe -f asciidoc.conf

ASCIIDOC_HTML = xhtml11

MANPAGE_XSL = manpage-normal.xsl

XMLTO_EXTRA =

INSTALL?=install
@@ -55,6 +56,14 @@ RM ?= rm -f 
DOC_REF = origin/man

HTML_REF = origin/html



ifdef USE_ASCIIDOCTOR

ASCIIDOC = asciidoctor

ASCIIDOC_EXTRA = -a compat-mode

ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions

ASCIIDOC_EXTRA += -a mansource="perf" -a manmanual="perf Manual"

ASCIIDOC_HTML = xhtml5

endif



infodir?=$(prefix)/share/info

MAKEINFO=makeinfo

INSTALL_INFO=install-info
@@ -73,10 +82,12 @@ ifeq ($(_tmp_tool_path),) 
	missing_tools = $(ASCIIDOC)

endif



ifndef USE_ASCIIDOCTOR

_tmp_tool_path := $(call get-executable,$(XMLTO))

ifeq ($(_tmp_tool_path),)

	missing_tools += $(XMLTO)

endif

endif



#

# For asciidoc ...
@@ -264,9 +275,17 @@ clean: 


$(MAN_HTML): $(OUTPUT)%.html : %.txt

	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \

	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \

	$(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage \

		$(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \

	mv $@+ $@



ifdef USE_ASCIIDOCTOR

$(OUTPUT)%.1 $(OUTPUT)%.5 $(OUTPUT)%.7 : $(OUTPUT)%.txt

	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \

	$(ASCIIDOC) -b manpage -d manpage \

		$(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \

	mv $@+ $@

endif



$(OUTPUT)%.1 $(OUTPUT)%.5 $(OUTPUT)%.7 : $(OUTPUT)%.xml

	$(QUIET_XMLTO)$(RM) $@ && \
@@ -274,7 +293,7 @@ $(OUTPUT)%.1 $(OUTPUT)%.5 $(OUTPUT)%.7 : $(OUTPUT)%.xml 


$(OUTPUT)%.xml : %.txt

	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \

	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \

	$(ASCIIDOC) -b docbook -d manpage \

		$(ASCIIDOC_EXTRA) -aperf_version=$(PERF_VERSION) -o $@+ $< && \

	mv $@+ $@
@@ -321,13 +340,13 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt) 
	mv $@+ $@



$(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt

	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 $*.txt

	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b $(ASCIIDOC_HTML) $*.txt



WEBDOC_DEST = /pub/software/tools/perf/docs



$(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt

	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \

	sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ && \

	sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b $(ASCIIDOC_HTML) - >$@+ && \

	mv $@+ $@



# UNIMPLEMENTED

tools/perf/Documentation/asciidoctor-extensions.rb

0 → 100644
+29 −0
Original line number Diff line number Diff line 
require 'asciidoctor'

require 'asciidoctor/extensions'



module Perf

  module Documentation

    class LinkPerfProcessor < 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 Perf::Documentation::LinkPerfProcessor, :linkperf

end

CRA Git | Maintained and supported by SUSTech CRA and CCSE