tools/lib/traceevent: Implement libtraceevent man pages
PATCH v2 1/1 tools/lib/traceevent: Implement libtraceevent man pages
This patch adds initial support for libtraceevent man pages - Documentation directory, templates, configurations, Makefiles. The first man page is also part of the patch - summary of the library and all its APIs. Building of the documentation is integrated into the libtraceevent build process, new targets are added to its Makefile:
make doc
make doc-clean
make doc-install
make doc-uninstall
--- tools/lib/traceevent/Documentation/Makefile | 205 ++++++++++++++++++ .../traceevent/Documentation/asciidoc.conf | 91 ++++++++ .../Documentation/libtraceevent.txt | 202 +++++++++++++++++ .../traceevent/Documentation/manpage-1.72.xsl | 14 ++ .../traceevent/Documentation/manpage-base.xsl | 35 +++ .../Documentation/manpage-bold-literal.xsl | 17 ++ .../Documentation/manpage-normal.xsl | 13 ++ .../Documentation/manpage-suppress-sp.xsl | 21 ++ tools/lib/traceevent/Makefile | 13 ++ 9 files changed, 611 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/Makefile create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl
tools/lib/traceevent/Documentation/Makefile new file +205 -0
@@ -0,0 +1,205 @@ +include ../../../scripts/Makefile.include +include ../../../scripts/utilities.mak + +MAN3_TXT= \ + $(wildcard libtraceevent-*.txt) \ + libtraceevent.txt + +MAN_TXT = $(MAN3_TXT) +_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +_DOC_MAN3=$(patsubst %.txt,%.3,$(MAN3_TXT)) + +MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML)) +MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML)) +DOC_MAN3=$(addprefix $(OUTPUT),$(_DOC_MAN3)) + +# Make the path relative to DESTDIR, not prefix +ifndef DESTDIR +prefix?=$(HOME) +endif +bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/libtraceevent-doc +pdfdir?=$(prefix)/share/doc/libtraceevent-doc +mandir?=$(prefix)/share/man +man3dir=$(mandir)/man3 + +ASCIIDOC=asciidoc +ASCIIDOC_EXTRA = --unsafe -f asciidoc.conf +ASCIIDOC_HTML = xhtml11 +MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = +INSTALL?=install +RM ?= rm -f + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_EXTRA = -a compat-mode +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -a mansource="libtraceevent" -a manmanual="libtraceevent Manual" +ASCIIDOC_HTML = xhtml5 +endif + +XMLTO=xmlto + +_tmp_tool_path := $(call get-executable,$(ASCIIDOC)) +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 ... +# -7.1.2, no extra settings are needed. +# 8.0-, set ASCIIDOC8. +# + +# +# For docbook-xsl ... +# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) +# 1.69.0, no extra settings are needed? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, no extra settings are needed? +# 1.72.0, set DOCBOOK_XSL_172. +# 1.73.0-, set ASCIIDOC_NO_ROFF +# + +# +# If you had been using DOCBOOK_XSL_172 in an attempt to get rid +# of 'the ".ft C" problem' in your generated manpages, and you +# instead ended up with weird characters around callouts, try +# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). +# + +ifdef ASCIIDOC8 +ASCIIDOC_EXTRA += -a asciidoc7compatible +endif +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff +MANPAGE_XSL = manpage-1.72.xsl +else + ifdef ASCIIDOC_NO_ROFF + # docbook-xsl after 1.72 needs the regular XSL, but will not + # pass-thru raw roff codes from asciidoc.conf, so turn them off. + ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff + endif +endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +DESTDIR ?= +DESTDIR_SQ = '$(subst ','\'',$(DESTDIR))' + +export DESTDIR DESTDIR_SQ + +# +# Please note that there is a minor bug in asciidoc. +# The version after 6.0.3 _will_ include the patch found here: +# http://marc.theaimsgroup.com/?l=libtraceevent&m=111558757202243&w=2 +# +# Until that version is released you may have to apply the patch +# yourself - yes, all 6 characters of it! +# +QUIET_SUBDIR0 = +$(MAKE) -C # space to separate -C and subdir +QUIET_SUBDIR1 = + +ifneq ($(findstring $(MAKEFLAGS),w),w) +PRINT_DIR = --no-print-directory +else # "make -w" +NO_SUBDIR = : +endif + +ifneq ($(findstring $(MAKEFLAGS),s),s) +ifneq ($(V),1) + QUIET_ASCIIDOC = @echo ' ASCIIDOC '$@; + QUIET_XMLTO = @echo ' XMLTO '$@; + QUIET_SUBDIR0 = +@subdir= + QUIET_SUBDIR1 = ;$(NO_SUBDIR) \ + echo ' SUBDIR ' $$subdir; \ + $(MAKE) $(PRINT_DIR) -C $$subdir + export V +endif +endif + +all: html man + +man: man3 +man3: $(DOC_MAN3) + +html: $(MAN_HTML) + +$(MAN_HTML) $(DOC_MAN3): asciidoc.conf + +install: install-man + +check-man-tools: +ifdef missing_tools + $(error "You need to install $(missing_tools) for man pages") +endif + +do-install-man: man + $(call QUIET_INSTALL, Documentation-man) \ + $(INSTALL) -d -m 755 $(DESTDIR)$(man3dir); \ + $(INSTALL) -m 644 $(DOC_MAN3) $(DESTDIR)$(man3dir); + +install-man: check-man-tools man do-install-man + +uninstall: uninstall-man + +uninstall-man: + $(call QUIET_UNINST, Documentation-man) \ + $(Q)$(RM) $(addprefix $(DESTDIR)$(man3dir)/,$(DOC_MAN3)) + + +ifdef missing_tools + DO_INSTALL_MAN = $(warning Please install $(missing_tools) to have the man pages installed) +else + DO_INSTALL_MAN = do-install-man +endif + +CLEAN_FILES = \ + $(MAN_XML) $(addsuffix +,$(MAN_XML)) \ + $(MAN_HTML) $(addsuffix +,$(MAN_HTML)) \ + $(DOC_MAN3) + +clean: + $(call QUIET_CLEAN, Documentation) $(RM) $(CLEAN_FILES) + +ifdef USE_ASCIIDOCTOR +$(OUTPUT)%.3 : $(OUTPUT)%.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b manpage -d manpage \ + $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ +endif + +$(OUTPUT)%.3 : $(OUTPUT)%.xml + $(QUIET_XMLTO)$(RM) $@ && \ + $(XMLTO) -o $(OUTPUT). -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $< + +$(OUTPUT)%.xml : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b docbook -d manpage \ + $(ASCIIDOC_EXTRA) -alibtraceevent_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ + +$(MAN_HTML): $(OUTPUT)%.html : %.txt + $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \ + $(ASCIIDOC) -b $(ASCIIDOC_HTML) -d manpage \ + $(ASCIIDOC_EXTRA) -aperf_version=$(EVENT_PARSE_VERSION) -o $@+ $< && \ + mv $@+ $@ +
tools/lib/traceevent/Documentation/asciidoc.conf new file +91 -0
91 lines not on this page · raw message
tools/lib/traceevent/Documentation/libtraceevent.txt new file +202 -0
202 lines not on this page · raw message
tools/lib/traceevent/Documentation/manpage-1.72.xsl new file +14 -0
@@ -0,0 +1,14 @@ +<!-- manpage-1.72.xsl: + special settings for manpages rendered from asciidoc+docbook + handles peculiarities in docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the special values for the roff control characters + needed for docbook-xsl 1.72.0 --> +<xsl:param name="git.docbook.backslash">▓</xsl:param> +<xsl:param name="git.docbook.dot" >⌂</xsl:param> + +</xsl:stylesheet>
tools/lib/traceevent/Documentation/manpage-base.xsl new file +35 -0
@@ -0,0 +1,35 @@ +<!-- manpage-base.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- these params silence some output from xmlto --> +<xsl:param name="man.output.quietly" select="1"/> +<xsl:param name="refentry.meta.get.quietly" select="1"/> + +<!-- convert asciidoc callouts to man page format; + git.docbook.backslash and git.docbook.dot params + must be supplied by another XSL file or other means --> +<xsl:template match="co"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB(', + substring-after(@id,'-'),')', + $git.docbook.backslash,'fR')"/> +</xsl:template> +<xsl:template match="calloutlist"> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>sp </xsl:text> + <xsl:apply-templates/> + <xsl:text> </xsl:text> +</xsl:template> +<xsl:template match="callout"> + <xsl:value-of select="concat( + $git.docbook.backslash,'fB', + substring-after(@arearefs,'-'), + '. ',$git.docbook.backslash,'fR')"/> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.dot"/> + <xsl:text>br </xsl:text> +</xsl:template> + +</xsl:stylesheet>
tools/lib/traceevent/Documentation/manpage-bold-literal.xsl new file +17 -0
@@ -0,0 +1,17 @@ +<!-- manpage-bold-literal.xsl: + special formatting for manpages rendered from asciidoc+docbook --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- render literal text as bold (instead of plain or monospace); + this makes literal text easier to distinguish in manpages + viewed on a tty --> +<xsl:template match="literal"> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fB</xsl:text> + <xsl:apply-templates/> + <xsl:value-of select="$git.docbook.backslash"/> + <xsl:text>fR</xsl:text> +</xsl:template> + +</xsl:stylesheet>
tools/lib/traceevent/Documentation/manpage-normal.xsl new file +13 -0
@@ -0,0 +1,13 @@ +<!-- manpage-normal.xsl: + special settings for manpages rendered from asciidoc+docbook + handles anything we want to keep away from docbook-xsl 1.72.0 --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<xsl:import href="manpage-base.xsl"/> + +<!-- these are the normal values for the roff control characters --> +<xsl:param name="git.docbook.backslash">\</xsl:param> +<xsl:param name="git.docbook.dot" >.</xsl:param> + +</xsl:stylesheet>
tools/lib/traceevent/Documentation/manpage-suppress-sp.xsl new file +21 -0
@@ -0,0 +1,21 @@ +<!-- manpage-suppress-sp.xsl: + special settings for manpages rendered from asciidoc+docbook + handles erroneous, inline .sp in manpage output of some + versions of docbook-xsl --> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + +<!-- attempt to work around spurious .sp at the tail of the line + that some versions of docbook stylesheets seem to add --> +<xsl:template match="simpara"> + <xsl:variable name="content"> + <xsl:apply-templates/> + </xsl:variable> + <xsl:value-of select="normalize-space($content)"/> + <xsl:if test="not(ancestor::authorblurb) and + not(ancestor::personblurb)"> + <xsl:text> </xsl:text> + </xsl:if> +</xsl:template> + +</xsl:stylesheet>
tools/lib/traceevent/Makefile +13 -0
@@ -53,6 +53,7 @@ pkgconfig_dir ?= $(word 1,$(shell $(PKG_CONFIG) \ export man_dir man_dir_SQ INSTALL export DESTDIR DESTDIR_SQ +export EVENT_PARSE_VERSION set_plugin_dir := 1
@@ -313,6 +314,18 @@ clean: $(RM) TRACEEVENT-CFLAGS tags TAGS; \ $(RM) $(PKG_CONFIG_FILE) +doc: + $(call descend,Documentation) + +doc-clean: + $(call descend,Documentation,clean) + +doc-install: + $(call descend,Documentation,install) + +doc-uninstall: + $(call descend,Documentation,uninstall) + PHONY += force plugins force:
Signature · 1 line
2.17.2
I noticed that your other patches are based off of this one, so I'm assuming that this is the one you want to add.
I'm getting a lot of patches in my inbox from you that are not applied yet. It may be a good idea to just include all the patches that should be applied into one patch series, as, I have no idea which patch needs to be applied, or which ones to just ignore.
Quoted 3 lines · On Fri, 19 Oct 2018 09:15:45 +0000 Tzvetomir Stoyanov <[email protected]>…
This patch adds initial support for libtraceevent man pages - Documentation directory, templates, configurations, Makefiles. The first man page is also part of the patch - summary of the
The first man page will now have functions that are no longer going to be part of the API. This is fine, as long as the patches that remove them remove them from this man page too.
Quoted 104 lines
library and all its APIs. Building of the documentation is integrated into the libtraceevent build process, new targets are added to its
Makefile:
make doc
make doc-clean
make doc-install
make doc-uninstallSigned-off-by Tzvetomir Stoyanov <[email protected]>--- tools/lib/traceevent/Documentation/Makefile | 205 ++++++++++++++++++ .../traceevent/Documentation/asciidoc.conf | 91 ++++++++ .../Documentation/libtraceevent.txt | 202 +++++++++++++++++ .../traceevent/Documentation/manpage-1.72.xsl | 14 ++ .../traceevent/Documentation/manpage-base.xsl | 35 +++ .../Documentation/manpage-bold-literal.xsl | 17 ++ .../Documentation/manpage-normal.xsl | 13 ++ .../Documentation/manpage-suppress-sp.xsl | 21 ++ tools/lib/traceevent/Makefile | 13 ++ 9 files changed, 611 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/Makefile create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsltools/lib/traceevent/Documentation/Makefile new file +69
-0@@ -0,0 +1,205 @@ +include ../../../scripts/Makefile.include +include ../../../scripts/utilities.mak + +MAN3_TXT= \ + $(wildcard libtraceevent-*.txt) \ + libtraceevent.txt + +MAN_TXT = $(MAN3_TXT) +_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +_DOC_MAN3=$(patsubst %.txt,%.3,$(MAN3_TXT)) + +MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML)) +MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML)) +DOC_MAN3=$(addprefix $(OUTPUT),$(_DOC_MAN3)) + +# Make the path relative to DESTDIR, not prefix +ifndef DESTDIR +prefix?=$(HOME) +endif +bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/libtraceevent-doc +pdfdir?=$(prefix)/share/doc/libtraceevent-doc +mandir?=$(prefix)/share/man +man3dir=$(mandir)/man3 + +ASCIIDOC=asciidoc +ASCIIDOC_EXTRA = --unsafe -f asciidoc.conf +ASCIIDOC_HTML = xhtml11 +MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = +INSTALL?=install +RM ?= rm -f + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_EXTRA = -a compat-mode +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -a mansource="libtraceevent" -a manmanual="libtraceevent Manual" +ASCIIDOC_HTML = xhtml5 +endif + +XMLTO=xmlto + +_tmp_tool_path := $(call get-executable,$(ASCIIDOC)) +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 ... +# -7.1.2, no extra settings are needed. +# 8.0-, set ASCIIDOC8. +# + +# +# For docbook-xsl ... +# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) +# 1.69.0, no extra settings are needed? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, no extra settings are needed? +# 1.72.0, set DOCBOOK_XSL_172.
tools/lib/traceevent/Documentation/Makefile line 79
Quoted 10 lines
tools/lib/traceevent/Documentation/Makefile new file +10
-0+# 1.73.0-, set ASCIIDOC_NO_ROFF +# + +# +# If you had been using DOCBOOK_XSL_172 in an attempt to get rid +# of 'the ".ft C" problem' in your generated manpages, and you +# instead ended up with weird characters around callouts, try +# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). +# +
Looks like this was copied from the perf documentation make files, we need to state that somewhere. like at the top of this file:
# This was taken from tools/perf/Documentation and modified for
# libtraceevent.
Always state where code or text came from when copied.
Quoted 29 lines
tools/lib/traceevent/Documentation/Makefile new file +29
-0+ifdef ASCIIDOC8 +ASCIIDOC_EXTRA += -a asciidoc7compatible +endif +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff +MANPAGE_XSL = manpage-1.72.xsl +else + ifdef ASCIIDOC_NO_ROFF + # docbook-xsl after 1.72 needs the regular XSL, but will not + # pass-thru raw roff codes from asciidoc.conf, so turn them off. + ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff + endif +endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +DESTDIR ?= +DESTDIR_SQ = '$(subst ','\'',$(DESTDIR))' + +export DESTDIR DESTDIR_SQ +
[...]
Quoted 18 lines
tools/lib/traceevent/Makefile +3
-0@@ -53,6 +53,7 @@ pkgconfig_dir ?= $(word 1,$(shell $(PKG_CONFIG) \ export man_dir man_dir_SQ INSTALL export DESTDIR DESTDIR_SQ +export EVENT_PARSE_VERSION set_plugin_dir := 1@@ -313,6 +314,18 @@ clean: $(RM) TRACEEVENT-CFLAGS tags TAGS; \ $(RM) $(PKG_CONFIG_FILE) +doc: + $(call descend,Documentation)
tools/lib/traceevent/Makefile clean: · line 328
Quoted 10 lines
tools/lib/traceevent/Makefile +10
-0+ +doc-clean: + $(call descend,Documentation,clean) + +doc-install: + $(call descend,Documentation,install) + +doc-uninstall: + $(call descend,Documentation,uninstall) +
We probably should add a "make help" here too, that describes all this.
-- Steve
Quoted 3 lines
tools/lib/traceevent/Makefile +0
-0PHONY += force plugins force:
Quoted 212 lines · Steven Rostedt
I noticed that your other patches are based off of this one, so I'm assuming that this is the one you want to add.
I'm getting a lot of patches in my inbox from you that are not applied yet. It may be a good idea to just include all the patches that should be applied into one patch series, as, I have no idea which patch needs to be applied, or which ones to just ignore.
Quoted 3 lines · On Fri, 19 Oct 2018 09:15:45 +0000 Tzvetomir Stoyanov <[email protected]>…
This patch adds initial support for libtraceevent man pages - Documentation directory, templates, configurations, Makefiles. The first man page is also part of the patch - summary of the
The first man page will now have functions that are no longer going to be part of the API. This is fine, as long as the patches that remove them remove them from this man page too.
Quoted 104 lines
library and all its APIs. Building of the documentation is integrated into the libtraceevent build process, new targets are added to its
Makefile:
make doc
make doc-clean
make doc-install
make doc-uninstallSigned-off-by Tzvetomir Stoyanov <[email protected]>--- tools/lib/traceevent/Documentation/Makefile | 205 ++++++++++++++++++ .../traceevent/Documentation/asciidoc.conf | 91 ++++++++ .../Documentation/libtraceevent.txt | 202 +++++++++++++++++ .../traceevent/Documentation/manpage-1.72.xsl | 14 ++ .../traceevent/Documentation/manpage-base.xsl | 35 +++ .../Documentation/manpage-bold-literal.xsl | 17 ++ .../Documentation/manpage-normal.xsl | 13 ++ .../Documentation/manpage-suppress-sp.xsl | 21 ++ tools/lib/traceevent/Makefile | 13 ++ 9 files changed, 611 insertions(+) create mode 100644 tools/lib/traceevent/Documentation/Makefile create mode 100644 tools/lib/traceevent/Documentation/asciidoc.conf create mode 100644 tools/lib/traceevent/Documentation/libtraceevent.txt create mode 100644 tools/lib/traceevent/Documentation/manpage-1.72.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-base.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-bold-literal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-normal.xsl create mode 100644 tools/lib/traceevent/Documentation/manpage-suppress-sp.xsltools/lib/traceevent/Documentation/Makefile new file +69
-0@@ -0,0 +1,205 @@ +include ../../../scripts/Makefile.include +include ../../../scripts/utilities.mak + +MAN3_TXT= \ + $(wildcard libtraceevent-*.txt) \ + libtraceevent.txt + +MAN_TXT = $(MAN3_TXT) +_MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) +_MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +_DOC_MAN3=$(patsubst %.txt,%.3,$(MAN3_TXT)) + +MAN_XML=$(addprefix $(OUTPUT),$(_MAN_XML)) +MAN_HTML=$(addprefix $(OUTPUT),$(_MAN_HTML)) +DOC_MAN3=$(addprefix $(OUTPUT),$(_DOC_MAN3)) + +# Make the path relative to DESTDIR, not prefix +ifndef DESTDIR +prefix?=$(HOME) +endif +bindir?=$(prefix)/bin +htmldir?=$(prefix)/share/doc/libtraceevent-doc +pdfdir?=$(prefix)/share/doc/libtraceevent-doc +mandir?=$(prefix)/share/man +man3dir=$(mandir)/man3 + +ASCIIDOC=asciidoc +ASCIIDOC_EXTRA = --unsafe -f asciidoc.conf +ASCIIDOC_HTML = xhtml11 +MANPAGE_XSL = manpage-normal.xsl +XMLTO_EXTRA = +INSTALL?=install +RM ?= rm -f + +ifdef USE_ASCIIDOCTOR +ASCIIDOC = asciidoctor +ASCIIDOC_EXTRA = -a compat-mode +ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions +ASCIIDOC_EXTRA += -a mansource="libtraceevent" -a manmanual="libtraceevent Manual" +ASCIIDOC_HTML = xhtml5 +endif + +XMLTO=xmlto + +_tmp_tool_path := $(call get-executable,$(ASCIIDOC)) +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 ... +# -7.1.2, no extra settings are needed. +# 8.0-, set ASCIIDOC8. +# + +# +# For docbook-xsl ... +# -1.68.1, set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0) +# 1.69.0, no extra settings are needed? +# 1.69.1-1.71.0, set DOCBOOK_SUPPRESS_SP? +# 1.71.1, no extra settings are needed? +# 1.72.0, set DOCBOOK_XSL_172.tools/lib/traceevent/Documentation/Makefile line 79
Quoted 10 lines
tools/lib/traceevent/Documentation/Makefile new file +10
-0+# 1.73.0-, set ASCIIDOC_NO_ROFF +# + +# +# If you had been using DOCBOOK_XSL_172 in an attempt to get rid +# of 'the ".ft C" problem' in your generated manpages, and you +# instead ended up with weird characters around callouts, try +# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8). +# +Looks like this was copied from the perf documentation make files, we need to state that somewhere. like at the top of this file:
# This was taken from
tools/perf/Documentationand modified for# libtraceevent.Always state where code or text came from when copied.
Quoted 29 lines
tools/lib/traceevent/Documentation/Makefile new file +29
-0+ifdef ASCIIDOC8 +ASCIIDOC_EXTRA += -a asciidoc7compatible +endif +ifdef DOCBOOK_XSL_172 +ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff +MANPAGE_XSL = manpage-1.72.xsl +else + ifdef ASCIIDOC_NO_ROFF + # docbook-xsl after 1.72 needs the regular XSL, but will not + # pass-thru raw roff codes from asciidoc.conf, so turn them off. + ASCIIDOC_EXTRA += -a libtraceevent-asciidoc-no-roff + endif +endif +ifdef MAN_BOLD_LITERAL +XMLTO_EXTRA += -m manpage-bold-literal.xsl +endif +ifdef DOCBOOK_SUPPRESS_SP +XMLTO_EXTRA += -m manpage-suppress-sp.xsl +endif + +SHELL_PATH ?= $(SHELL) +# Shell quote; +SHELL_PATH_SQ = $(subst ','\'',$(SHELL_PATH)) + +DESTDIR ?= +DESTDIR_SQ = '$(subst ','\'',$(DESTDIR))' + +export DESTDIR DESTDIR_SQ +[...]
Quoted 19 lines
tools/lib/traceevent/Makefile +3
-0@@ -53,6 +53,7 @@ pkgconfig_dir ?= $(word 1,$(shell $(PKG_CONFIG) \ export man_dir man_dir_SQ INSTALL export DESTDIR DESTDIR_SQ +export EVENT_PARSE_VERSION set_plugin_dir := 1@@ -313,6 +314,18 @@ clean: $(RM) TRACEEVENT-CFLAGS tags TAGS; \ $(RM) $(PKG_CONFIG_FILE) +doc: + $(call descend,Documentation)tools/lib/traceevent/Makefile clean: · line 329
Quoted 10 lines
tools/lib/traceevent/Makefile +10
-0+ +doc-clean: + $(call descend,Documentation,clean) + +doc-install: + $(call descend,Documentation,install) + +doc-uninstall: + $(call descend,Documentation,uninstall) +We probably should add a "make help" here too, that describes all this.
Quoted 6 lines
-- Steve
Quoted 3 lines
tools/lib/traceevent/Makefile +0
-0PHONY += force plugins force:
I'll prepare v3 of this patch, addressing the comments:
- Update head man page, will remove the functions which are no
longer part of the API.
I'm going to change the names of the input parameters in the head
man page from
"pevent" to "tep", as "tep" is used in all other man pages.
- Update the Makefile with "help" target and perf comments.
- Resend again all man pages related patches as one series, with
fixed subjects.
--
Tzvetomir (Ceco) Stoyanov
VMware Open Source Technology Center