Convert man pages to AsciiDoc

.gitignore

@@ -40,6 +40,14 @@ doc/examples/gen-tp/sample_tracepoint.h
 doc/examples/demo-tracef/demo-tracef
 doc/examples/demo-tracelog/demo-tracelog
 
+doc/man/*.xml
+doc/man/lttng-gen-tp.1
+doc/man/lttng-ust-cyg-profile.3
+doc/man/lttng-ust-dl.3
+doc/man/lttng-ust.3
+doc/man/tracef.3
+doc/man/tracelog.3
+
 tests/hello/hello
 tests/hello.cxx/hello
 tests/same_line_tracepoint/same_line_tracepoint

README.md

@@ -24,10 +24,32 @@ This source tree is based on the Autotools suite from GNU to simplify
 portability. Here are some things you should have on your system in order to
 compile the Git repository tree:
 
-  - GNU Autotools (Automake >= 1.10, Autoconf >= 2.50, Autoheader >= 2.50;
+  - [GNU Autotools](http://www.gnu.org/software/autoconf/)
+    (**Automake >= 1.10**, **Autoconf >= 2.50**,
+    **Autoheader >= 2.50**;
     make sure your system-wide `automake` points to a recent version!)
-  - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2
-  - Perl (optional: needed for `make check` and tests)
+  - **[GNU Libtool](https://www.gnu.org/software/libtool/) >= 2.2**
+
+
+### Optional dependencies
+
+Optional packages to build LTTng-tools man pages:
+
+  - **[AsciiDoc](http://www.methods.co.nz/asciidoc/) >= 8.4.5**
+    (previous versions may work, but were not tested)
+  - **[xmlto](https://fedorahosted.org/xmlto/) >= 0.0.21** (previous
+    versions may work, but were not tested)
+
+Note that the man pages are already built in a distribution tarball.
+In this case, you only need AsciiDoc and xmlto if you indend to modify
+the AsciiDoc man page sources.
+
+Needed for `make check` and tests:
+
+  - **[Perl](https://www.perl.org/)**
+
+
+### Building steps
 
 If you get the tree from the Git repository, you will need to run
 

configure.ac

@@ -368,10 +368,67 @@ AC_DEFINE_UNQUOTED([LTTNG_SYSTEM_RUNDIR], ["$lttng_system_rundir"],
 AC_CHECK_PROG([BUILD_GEN_TP_EXAMPLES], [python], ["yes"])
 AM_CONDITIONAL([BUILD_GEN_TP_EXAMPLES], [test "x$BUILD_GEN_TP_EXAMPLES" = "xyes"])
 
+# Set $IN_GIT_REPO if we're in the Git repository; the `bootstrap` file
+# is not distributed in tarballs.
+AS_IF([test -f "$srcdir/bootstrap"], [in_git_repo=yes], [in_git_repo=no])
+AM_CONDITIONAL([IN_GIT_REPO], [test "x$in_git_repo" = "xyes"])
+
+# Enable building man pages (user's intention).
+AC_ARG_ENABLE(
+	man-pages,
+	AS_HELP_STRING(
+		[--disable-man-pages],
+		[Do not build and install man pages (already built in a distributed tarball)]
+	),
+	[man_pages_opt=$enableval],
+	[man_pages_opt=yes]
+)
+
+# Check for asciidoc and xmlto if we enabled building the man pages.
+have_asciidoc_xmlto=no
+
+AS_IF([test "x$man_pages_opt" = "xyes"], [
+	AC_PATH_PROG([ASCIIDOC], [asciidoc], [no])
+	AC_PATH_PROG([XMLTO], [xmlto], [no])
+
+	AS_IF([test "x$ASCIIDOC" = "xno" || test "x$XMLTO" = "xno"], [
+		AS_IF([test "x$in_git_repo" = "xyes"], [
+			# This is an error because we're in the Git repo, which
+			# means the man pages are not already generated for us,
+			# thus asciidoc/xmlto are required because we were asked
+			# to build the man pages.
+			AC_MSG_ERROR([
+Both asciidoc and xmlto are needed to build the LTTng-UST man pages. Use
+--disable-man-pages to disable building the man pages, in which case
+they will not be installed.
+			])
+		], [
+			# Only warn here: since we're in the tarball, the man
+			# pages should already be generated at this point, thus
+			# asciidoc/xmlto are not strictly required.
+			AC_MSG_WARN([
+Both asciidoc and xmlto are needed to build the LTTng-UST man pages.
+Note that the man pages are already built in this distribution tarball,
+so asciidoc and xmlto are only needed if you intend to modify their
+sources. Use --disable-man-pages to completely disable building
+and installing the man pages.
+			])
+		])
+	], [
+		have_asciidoc_xmlto=yes
+	])
+])
+
+# Export man page build condition: build the man pages if the user
+# asked for it, and if the tools are available.
+AM_CONDITIONAL([MAN_PAGES_OPT], [test "x$man_pages_opt" != "xno"])
+AM_CONDITIONAL([HAVE_ASCIIDOC_XMLTO], [test "x$have_asciidoc_xmlto" = "xyes"])
+
 AC_CONFIG_FILES([
 	Makefile
 	doc/Makefile
 	doc/examples/Makefile
+	doc/man/Makefile
 	include/Makefile
 	include/lttng/ust-version.h
 	snprintf/Makefile

doc/Makefile.am

@@ -1,8 +1,3 @@
-SUBDIRS = . examples
-
-dist_man_MANS = man/lttng-gen-tp.1 \
-	man/lttng-ust.3 \
-	man/lttng-ust-dl.3 \
-	man/lttng-ust-cyg-profile.3
+SUBDIRS = . man examples
 
 dist_doc_DATA = java-agent.txt

doc/man/Makefile.am

@@ -0,0 +1,115 @@
+# Man pages are only built if they are enabled at configure time.
+#
+# They should always be built before creating a distribution tarball.
+
+# Function which adds the source directory prefix and adds a given suffix:
+manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2)))
+
+# List only the names without the .*.txt extension here:
+MAN1_NAMES = \
+	lttng-gen-tp
+MAN3_NAMES = \
+	lttng-ust \
+	tracef \
+	tracelog \
+	lttng-ust-dl \
+	lttng-ust-cyg-profile
+
+# troff man pages:
+MAN3_TROFF = do_tracepoint.3 tracepoint.3 tracepoint_enabled.3
+
+# AsciiDoc sources and outputs:
+MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES))
+MAN3_TXT = $(call manaddsuffix,.3.txt,$(MAN3_NAMES))
+MAN_TXT = $(MAN1_TXT) $(MAN3_TXT) $(MAN8_TXT)
+MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT))
+
+# Common AsciiDoc source files:
+COMMON_TXT = \
+	$(srcdir)/common-footer.txt \
+	$(srcdir)/common-authors.txt \
+	$(srcdir)/common-copyrights.txt \
+	$(srcdir)/log-levels.txt \
+	$(srcdir)/tracef-tracelog-limitations.txt
+
+# AsciiDoc configuration and XSL files:
+ASCIIDOC_CONF = $(srcdir)/asciidoc.conf
+XSL_FILES = \
+	manpage.xsl \
+	manpage-callouts.xsl \
+	manpage-bold-literal.xsl \
+	manpage-links.xsl \
+	manpage-headings.xsl
+XSL_SRC_FILES = $(addprefix $(srcdir)/xsl/,$(XSL_FILES))
+
+# Common dependencies:
+COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT)
+
+# Man pages destinations:
+MAN1 = $(addsuffix .1,$(MAN1_NAMES))
+MAN3 = $(addsuffix .3,$(MAN3_NAMES))
+MAN = $(MAN1) $(MAN3)
+
+if MAN_PAGES_OPT
+# At this point, we know the user asked to build the man pages.
+if HAVE_ASCIIDOC_XMLTO
+# Tools to execute:
+ADOC = $(ASCIIDOC) -f $(ASCIIDOC_CONF) -d manpage \
+	-a lttng_version="$(PACKAGE_VERSION)"
+ADOC_DOCBOOK = $(ADOC) -b docbook
+XTO = $(XMLTO) -m $(firstword $(XSL_SRC_FILES)) man
+
+# Recipes:
+%.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS)
+	$(ADOC_DOCBOOK) -o $@ $<
+
+%.1: %.1.xml $(XSL_SRC_FILES)
+	$(XTO) $<
+
+%.3.xml: $(srcdir)/%.3.txt $(COMMON_DEPS)
+	$(ADOC_DOCBOOK) -o $@ $<
+
+%.3: %.3.xml $(XSL_SRC_FILES)
+	$(XTO) $<
+
+# Only clean the generated files if we have the tools to generate them again.
+CLEANFILES = $(MAN_XML) $(MAN)
+else # HAVE_ASCIIDOC_XMLTO
+# Create man page targets used to stop the build if we want to
+# build the man pages, but we don't have the necessary tools to do so.
+ERR_MSG = "Error: Cannot build target because asciidoc or xmlto tool is missing."
+ERR_MSG += "Make sure both tools are installed and run the configure script again."
+
+%.1: $(srcdir)/%.1.txt $(COMMON_DEPS)
+	@echo $(ERR_MSG)
+	@false
+
+%.3: $(srcdir)/%.3.txt $(COMMON_DEPS)
+	@echo $(ERR_MSG)
+	@false
+endif # HAVE_ASCIIDOC_XMLTO
+endif # MAN_PAGES_OPT
+
+# Start with empty distributed/installed man pages:
+dist_man1_MANS =
+dist_man3_MANS =
+EXTRA_DIST =
+
+if MAN_PAGES_OPT
+# Building man pages: we can install and distribute them.
+dist_man1_MANS += $(MAN1)
+dist_man3_MANS += $(MAN3) $(MAN3_TROFF)
+else # MAN_PAGES_OPT
+# Those are not known by automake yet because dist_man3_MANS is empty
+# at this point, so make sure they are distributed.
+EXTRA_DIST += $(MAN3_TROFF)
+endif # MAN_PAGES_OPT
+
+if !MAN_PAGES_OPT
+dist-hook:
+	@echo "Error: Please enable the man pages before creating a distribution tarball."
+	@false
+endif # !MAN_PAGES_OPT
+
+# Always distribute the source files.
+EXTRA_DIST += $(MAN_TXT) $(COMMON_TXT) $(XSL_SRC_FILES) $(ASCIIDOC_CONF)

doc/man/README.md

@@ -0,0 +1,100 @@
+LTTng-UST man pages
+===================
+
+This directory contains the sources of the LTTng-UST man pages.
+
+LTTng-UST man pages are written in
+[AsciiDoc](http://www.methods.co.nz/asciidoc/), and then converted to
+DocBook (XML) using the `asciidoc` command, and finally to troff using
+the appropriate DocBook XSL stylesheet (using the `xmlto` command).
+
+
+Custom XSL stylesheets
+----------------------
+
+There are a few custom XSL stylesheets applied for customizing the
+generated man pages in the `xsl` directory.
+
+
+Macros
+------
+
+AsciiDoc is configured with `asciidoc.conf` which contains a few
+macro definitions used everywhere in the man page sources.
+
+
+### `man`
+
+The `man` macro is used to specify a reference to another man page.
+Using the provided `asciidoc.conf` configuration file, the man page
+name is rendered in bold and the section is normal.
+
+Usage example: `man:lttng-enable-channel(1)`, `man:dlopen(3)`
+
+
+### `option`
+
+The option macro is used to write a command-line option which is
+**defined in the same man page**.
+
+Usage example: `option:--output`, `option:--verbose`
+
+
+### `nloption`
+
+Command-line option generating no link. This is used when writing
+about an option which is **not defined in the same man page**.
+
+Usage example: `nloption:-finstrument-functions`
+
+
+### `not`
+
+The `:not:` macro is used to emphasize on _not_.
+
+
+Includes
+--------
+
+  * `common-authors.txt`: common authors section of the LTTng-UST
+    project. Only use this for man pages which describe
+    a command/library/function written by the main authors of LTTng-UST.
+  * `common-copyright.txt`: common copyrights section of the LTTng-UST
+    project. Only use this for man pages which describe
+    a command/library/function having the common LTTng-UST license.
+  * `common-footer.txt`: common footer for all man pages. This goes
+    before the copyrights section.
+  * `log-levels.txt`: definition list of LTTng-UST log levels.
+  * `tracef-tracelog-limitations.txt`: limitations that apply to both
+    the `tracef(3)` and `tracelog(3)` man pages.
+
+
+Convention
+----------
+
+Please follow those rules when updating the current man pages or writing
+new ones:
+
+  * Always use macros when possible (man page references, command-line
+    options, _not_, etc.).
+  * Use callouts with the `term` role for command-line examples.
+  * Use a verse, possibly with the `term` role, in the synopsis section.
+  * Always refer to _long_ options in the text.
+  * Use the `option:--option='PARAM'` format (with `=`) when providing a
+    parameter to long options.
+  * Prefer writing _user space_ rather than _userspace_, _user-space_,
+    or _user land_.
+  * Write _file system_, not _filesystem_.
+  * Prefer writing _use case_ rather than _use-case_ or _usecase_.
+  * Write _log level_, not _loglevel_.
+  * Write complete LTTng project names: _LTTng-modules_, _LTTng-UST_,
+    and _LTTng-tools_, not _modules_, _UST_ and _tools_.
+  * Prefer simple emphasis to strong emphasis for emphasizing text.
+  * Try to stay behind the 72th column mark if possible, and behind the
+    80th column otherwise.
+  * Do not end directory paths with a forward slash (good:
+    `include/trace/events`, bad: `include/trace/events/`).
+  * Minimize the use of the future tense (_will_).
+  * Use an active voice, and prefer using the second person (_you_) when
+    referring to the user.
+  * Avoid using Latin abbreviations (_e.g._, _i.e._, _etc._).