Convert `README.md` to `README.adoc`

Asciidoctor offers more features than Markdown which this README can
benefit from (attributes, table of contents, description lists, and
non-HTML internal anchors to name a few).

On GitHub, the table of contents is placed right after the preamble,
before the first section's heading. Otherwise, it's placed on the left
for increased readability (not supported by GitHub).

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: Id4965abaa7151cb0fc3caca290fcf5d3669f0b80

diff --git a/INSTALL b/INSTALL
index e146eab3d6c1142b3399bfa0261c2da448c0ca46..0d6fc07efd4c1e97f29991bda48e9c6c30e1d7e0 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -14,7 +14,7 @@ Basic Installation
 
    Briefly, the shell commands `./configure; make; make install' should
 configure, build, and install this package.  The following
 
    Briefly, the shell commands `./configure; make; make install' should
 configure, build, and install this package.  The following

-more-detailed instructions are generic; see the `README.md' file for
+more-detailed instructions are generic; see the `README.adoc' file for

 instructions specific to this package.  Some packages provide this
 `INSTALL' file but do not implement all of the features documented
 below.  The lack of an optional feature in a given package is not
 instructions specific to this package.  Some packages provide this
 `INSTALL' file but do not implement all of the features documented
 below.  The lack of an optional feature in a given package is not


@@ -38,10 +38,10 @@ cache files.
 
    If you need to do unusual things to compile the package, please try
 to figure out how `configure' could check whether to do them, and mail
 
    If you need to do unusual things to compile the package, please try
 to figure out how `configure' could check whether to do them, and mail

-diffs or instructions to the address given in the `README.md' so they can
-be considered for the next release.  If you are using the cache, and at
-some point `config.cache' contains results you don't want to keep, you
-may remove or edit it.
+diffs or instructions to the address given in the `README.adoc' so they
+can be considered for the next release.  If you are using the cache, and
+at some point `config.cache' contains results you don't want to keep,
+you may remove or edit it.

 
    The file `configure.ac' (or `configure.in') is used to create
 `configure' by a program called `autoconf'.  You need `configure.ac' if
 
    The file `configure.ac' (or `configure.in') is used to create
 `configure' by a program called `autoconf'.  You need `configure.ac' if


@@ -200,7 +200,7 @@ option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
 `configure', where FEATURE indicates an optional part of the package.
 They may also pay attention to `--with-PACKAGE' options, where PACKAGE
 is something like `gnu-as' or `x' (for the X Window System).  The
 `configure', where FEATURE indicates an optional part of the package.
 They may also pay attention to `--with-PACKAGE' options, where PACKAGE
 is something like `gnu-as' or `x' (for the X Window System).  The

-`README.md' should mention any `--enable-' and `--with-' options that
+`README.adoc' should mention any `--enable-' and `--with-' options that

 the package recognizes.
 
    For packages that use the X Window System, `configure' can usually
 the package recognizes.
 
    For packages that use the X Window System, `configure' can usually

diff --git a/Makefile.am b/Makefile.am
index 3001e2d372b08cf664e3e1fac6b40ba217c42241..0240558c8d44444239e98aa9ca59c5c209d2a9d7 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -12,7 +12,7 @@ endif
 
 dist_doc_DATA = LICENSE \
                 ChangeLog \
 
 dist_doc_DATA = LICENSE \
                 ChangeLog \

-               README.md
+               README.adoc

 
 dist_noinst_DATA = CodingStyle
 
 
 dist_noinst_DATA = CodingStyle
 

diff --git a/README.adoc b/README.adoc
new file mode 100644 (file)
index 0000000..24d85c1
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,253 @@
+// Render with Asciidoctor
+
+:nbh: ‑
+:lt: LTTng{nbh}tools
+:lib: liblttng{nbh}ctl
+
+ifdef::env-github[]
+:toc: macro
+endif::env-github[]
+
+ifndef::env-github[]
+:toc: left
+endif::env-github[]
+
+= {lt}
+5 May 2020
+
+[.normal]
+https://ci.lttng.org/job/lttng-tools_master_build/[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/lttng-tools_master_build.svg[Jenkins, title="Jenkins"]]
+https://scan.coverity.com/projects/lttng-tools[image:https://img.shields.io/coverity/scan/lttng-tools.svg[Coverity, title="Coverity"]]
+
+[.lead]
+_**{lt}**_ is a set of components to control https://lttng.org/[LTTng]
+tracing.
+
+The project includes:
+
+* The LTTng https://lttng.org/man/8/lttng-sessiond/[session daemon].
+
+* The LTTng consumer daemon.
+
+* The LTTng https://lttng.org/man/8/lttng-relayd/[relay daemon].
+
+* {lib}, a library with a C{nbsp}API used to communicate with
+  the session daemon.
+
+* Python{nbsp}3 bindings of liblttng{nbh}ctl.
+
+* https://lttng.org/man/1/lttng/[`lttng`], a command-line tool over
+  {lib}.
+
+* https://lttng.org/man/1/lttng-crash/[`lttng{nbh}crash`], a command-line
+  tool to recover and view LTTng{nbsp}2 trace buffers in the event of a
+  crash.
+
+ifdef::env-github[]
+toc::[]
+endif::env-github[]
+
+== Required and optional dependencies
+
+You need the following dependencies to build and run the {lt}
+components:
+
+* **Linux kernel{nbsp}≥{nbsp}2.6.27**
++
+Use `{nbh}{nbh}disable{nbh}epoll` at <<configure,build configuration>>
+time to build {lt} for an older kernel. However, note that we can't
+provide any guarantee below 2.6.27.
+
+* **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.9.0**.
++
+Debian/Ubuntu package: `liburcu{nbh}dev`.
+
+* **popt{nbsp}≥{nbsp}1.13**
++
+Debian/Ubuntu package: `libpopt{nbh}dev`.
+
+* **http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6**
++
+Debian/Ubuntu package: `libxml2{nbh}dev`
+
+The following dependencies are optional:
+
+* **https://babeltrace.org/[Babeltrace{nbsp}2]**: default viewer
+  of the https://lttng.org/man/1/lttng-view/[`lttng view`] command.
++
+Debian/Ubuntu package: `babeltrace2`
+
+* **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}):
+  LTTng user space tracing (applications and libraries).
++
+Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev`
+
+* **Perl**: `make{nbsp}check` and tests.
+
+* **https://www.python.org/[Python]{nbsp}≥{nbsp}3.0**:
+  `make{nbsp}check` and tests.
++
+Debian/Ubuntu package: `python3`
+
+* **http://www.swig.org/[SWIG]{nbsp}≥{nbsp}2.0** and
+  **Python{nbsp}3 development headers**: Python bindings
+  (enabled at <<configure,build configuration>> time with the
+  `{nbh}{nbh}enable{nbh}python{nbh}bindings` option).
++
+Debian/Ubuntu packages: `swig2.0` and `python3{nbh}dev`
+
+* **modprobe** and/or
+  **https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22**:
+  automatic LTTng kernel modules loading (kernel tracing).
+
+* **Bash**: `make{nbsp}check`.
+
+* **http://man7.org/linux/man-pages/man1/man.1.html[`man`]**
+  (manual pager): view `lttng` command manual
+  pages with the `{nbh}{nbh}help` option or with the
+  https://lttng.org/man/1/lttng-help/[`lttng{nbsp}help`] command.
++
+NOTE: You can use the <<configure,build configuration>> option
+`{nbh}{nbh}enable{nbh}embedded{nbh}help` to embed the manual pages into
+the `lttng`, `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and
+`lttng{nbh}crash` programs so that you don't need `man` to view them.
+
+* **http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0**:
+  perf regression test suite.
++
+Debian/Ubuntu package: `libpfm4-dev`
+
+{lt} supports both the LTTng Linux kernel tracer and LTTng user space
+tracer sharing the same _minor_ version. While some minor releases do
+not change the tracer ABIs and _could_ work, no testing is performed to
+ensure that cross-version compatibility is maintained.
+
+You don't need to rebuild or modify applications instrumented with older
+versions of the LTTng{nbh}UST project to make them work with the
+components of the latest {lt} release.
+
+See the https://lttng.org/docs/[LTTng Documentation] for more
+information on versioning.
+
+== Build from source
+
+=== Dependencies
+
+You need the following tools to build {lt}:
+
+* **https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools]**
+  (**Automake{nbsp}≥{nbsp}1.10**,
+  **Autoconf{nbsp}≥{nbsp}2.64**, and **Autoheader{nbsp}≥{nbsp}2.50**)
+
+* **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2**
+
+* **https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35**
+
+* **https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4**
+
+To build the {lt} manual pages:
+
+* **https://www.methods.co.nz/asciidoc/[AsciiDoc]{nbsp}≥{nbsp}8.4.5**
++
+NOTE: Previous versions could work, but were not tested.
+
+* **https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21**
++
+NOTE: Previous versions could work, but were not tested.
+
+If you use GNU{nbsp}gold, which is _not_ mandatory:
+
+* **GNU{nbsp}gold{nbsp}≥{nbsp}2.22**
+
+NOTE: With GNU{nbsp}gold, you might need to add
+`-L/usr/local/lib` to the `LDFLAGS` environment variable.
+
+=== Build steps
+
+. **If you have the {lt} Git source**, run:
++
+----
+$ ./bootstrap
+----
++
+This script creates the `configure` script.
+
+. [[configure]]Configure the build:
++
+--
+----
+$ ./configure
+----
+
+If you want the {lib} Python bindings, use the
+`{nbh}{nbh}enable{nbh}python{nbh}bindings` option. See also the `PYTHON`
+and `PYTHON_CONFIG` environment variables in
+`./configure{nbsp}{nbh}{nbh}help`.
+
+If you don't want to build the manual pages, use the
+`{nbh}{nbh}disable{nbh}man{nbh}pages` option.
+
+If you want to embed the manual pages into the `lttng`,
+`lttng{nbh}sessiond`, `lttng{nbh}relayd`, and `lttng{nbh}crash` programs
+so that you don't need `man` to view them, use the
+`{nbh}{nbh}enable{nbh}embedded{nbh}help` option.
+
+If your Linux kernel is older than 2.6.27, use the
+`{nbh}{nbh}disable{nbh}epoll` option.
+
+This build configuration script finds LTTng{nbh}UST with
+https://www.freedesktop.org/wiki/Software/pkg-config/[pkg{nbh}config]:
+set the `PKG_CONFIG_PATH` environment variable accordingly if
+pkg{nbh}config cannot find the `lttng{nbh}ust` package information.
+
+See `./configure{nbsp}{nbh}{nbh}help` for the complete list of options.
+--
+
+. Build the project:
++
+----
+$ make
+----
+
+. Install the project:
++
+----
+$ sudo make install
+$ sudo ldconfig
+----
+
+== Usage
+
+See the https://lttng.org/docs/#doc-controlling-tracing[Tracing control]
+section of the LTTng Documentation to learn how to use the {lt}
+components.
+
+See also the https://lttng.org/man/[LTTng manual pages] (all
+section{nbsp}1 and{nbsp}8 pages).
+
+As there's no official {lib} Python bindings yet, see
+link:doc/python-howto.txt[`doc/python-howto.txt`] to understand how to
+use them.
+
+== Community
+
+Mailing list::
+    https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
+    (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
+
+IRC channel::
+    irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
+
+Bug tracker::
+    https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker]
+
+GitHub project::
+    https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools]
+
+Continuous integration::
+    https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build]
+    on LTTng's CI
+
+Code review::
+    https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project]
+    on LTTng Review

diff --git a/README.md b/README.md
deleted file mode 100644 (file)
index 3e9f91e..0000000
--- a/README.md
+++ /dev/null
@@ -1,217 +0,0 @@
-LTTng‑tools
-=================
-
-[![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/lttng-tools_master_build.svg)](https://ci.lttng.org/job/lttng-tools_master_build/)
-[![Coverity](https://img.shields.io/coverity/scan/lttng-tools.svg)](https://scan.coverity.com/projects/lttng-tools)
-
-_**LTTng‑tools**_ is a set of components to control
-[LTTng](https://lttng.org/) tracing.
-
-The project includes:
-
-* The LTTng [session daemon](https://lttng.org/man/8/lttng-sessiond/).
-* The LTTng consumer daemon.
-* The LTTng [relay daemon](https://lttng.org/man/8/lttng-relayd/).
-* liblttng‑ctl, a library with a C API used to communicate
-  with the session daemon.
-* Python 3 bindings of liblttng‑ctl.
-* [`lttng`](https://lttng.org/man/1/lttng/),
-  a command-line tool over liblttng‑ctl.
-* [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line
-  tool to recover and view LTTng 2 trace buffers in the event of
-  a crash.
-
-Required and optional dependencies
-----------------------------------
-You need the following dependencies to build and run the
-LTTng‑tools components:
-
-* **Linux kernel ≥ 2.6.27**
-
-  Use `--disable-epoll` at [build configuration](#configure) time to
-  build LTTng‑tools for an older kernel. However, note that we
-  can't provide any guarantee below 2.6.27.
-
-* **[Userspace RCU](http://www.liburcu.org/) ≥ 0.9.0**.
-
-  Debian/Ubuntu package: `liburcu-dev`.
-
-* **popt ≥ 1.13**
-
-  Debian/Ubuntu package: `libpopt-dev`.
-
-* **[Libxml2](http://xmlsoft.org/) ≥ 2.7.6**
-
-  Debian/Ubuntu package: `libxml2-dev`
-
-The following dependencies are optional:
-
-* **[Babeltrace 2](https://babeltrace.org/)**: default viewer
-  of the [`lttng view`](https://lttng.org/man/1/lttng-view/)
-  command.
-
-  Debian/Ubuntu package: `babeltrace2`
-
-* **[LTTng‑UST](https://lttng.org/)** (same minor version as
-  LTTng‑tools):
-  LTTng user space tracing (applications and libraries).
-
-  Debian/Ubuntu package: `liblttng-ust-dev`
-
-* **Perl**: `make check` and tests.
-
-* **[Python](https://www.python.org/) ≥ 3.0**:
-  `make check` and tests.
-
-  Debian/Ubuntu package: `python3`
-
-* **[SWIG](http://www.swig.org/) ≥ 2.0** and
-  **Python 3 development headers**: Python bindings
-  (enabled at [build configuration](#configure) time with the
-  `--enable-python-bindings` option).
-
-  Debian/Ubuntu packages: `swig2.0` and `python3-dev`
-
-* **modprobe** and/or
-  **[kmod](https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/) ≥ 22**:
-  automatic LTTng kernel modules loading (kernel tracing).
-
-* **Bash**: `make check`.
-
-* **[`man`](http://man7.org/linux/man-pages/man1/man.1.html)**
-  (manual pager): view `lttng` command manual
-  pages with the `--help` option or with the
-  [`lttng help`](https://lttng.org/man/1/lttng-help/) command.
-
-  Note that you can use the [build configuration](#configure) option
-  `--enable-embedded-help` to embed the manual pages into the
-  `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs
-  so that you don't need `man` to view them.
-
-* **[libpfm](http://perfmon2.sourceforge.net/) ≥ 4.0**:
-  perf regression test suite.
-
-  Debian/Ubuntu package: `libpfm4-dev`
-
-LTTng‑tools supports both the LTTng Linux kernel tracer and LTTng
-user space tracer sharing the same _minor_ version. While some minor
-releases do not change the tracer ABIs and _could_ work, no testing is
-performed to ensure that cross-version compatibility is maintained.
-
-You don't need to rebuild or modify applications instrumented with older
-versions of the LTTng‑UST project to make them work with the
-components of the latest LTTng‑tools release.
-
-See the [LTTng Documentation](https://lttng.org/docs/) for more
-information on versioning.
-
-Build from source
------------------
-### Dependencies
-
-You need the following tools to build LTTng‑tools:
-
-* **[GNU Autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html)**
-  (**Automake ≥ 1.10**,
-  **Autoconf ≥ 2.64**, and **Autoheader ≥ 2.50**)
-
-* **[GNU Libtool](http://www.gnu.org/software/autoconf/) ≥ 2.2**
-
-* **[Flex](https://github.com/westes/flex/) ≥ 2.5.35**
-
-* **[Bison](https://www.gnu.org/software/bison/) ≥ 2.4**
-
-To build the LTTng‑tools manual pages:
-
-* **[AsciiDoc](https://www.methods.co.nz/asciidoc/) ≥ 8.4.5**
-
-  Previous versions could work, but were not tested.
-
-* **[xmlto](https://pagure.io/xmlto) ≥ 0.0.21**
-
-  Previous versions could work, but were not tested.
-
-If you use GNU gold, which is _not_ mandatory:
-
-* **GNU gold ≥ 2.22**
-
-Note that with GNU gold, you might have to add
-`-L/usr/local/lib` to the `LDFLAGS` environment variable.
-
-### Build steps
-
-1. **If you have the LTTng‑tools Git source**, run:
-
-       $ ./bootstrap
-
-   This script creates the `configure` script.
-
-2. <span id="configure"></span>Configure the build:
-
-       $ ./configure
-
-   If you want the liblttng&#8209;ctl Python bindings, use the
-   `--enable-python-bindings` option. See also the
-   `PYTHON` and `PYTHON_CONFIG` environment variables in
-   `./configure --help`.
-
-   If you don't want to build the manual pages, use the
-   `--disable-man-pages` option.
-
-   If you want to embed the manual pages into the
-   `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs
-   so that you don't need `man` to view them, use the
-   `--enable-embedded-help` option.
-
-   If your Linux kernel is older than 2.6.27, use the
-   `--enable-epoll` option.
-
-   This build configuration script finds LTTng&#8209;UST with
-   [pkg&#8209;config](https://www.freedesktop.org/wiki/Software/pkg-config/):
-   set the `PKG_CONFIG_PATH` environment variable accordingly if
-   pkg&#8209;config cannot find the `lttng-ust` package information.
-
-   See `./configure --help` for the complete list of options.
-
-3. Build the project:
-
-       $ make
-
-4. Install the project:
-
-       $ sudo make install
-       $ sudo ldconfig
-
-Usage
------
-See the [Tracing control](https://lttng.org/docs/#doc-controlling-tracing)
-section of the LTTng Documentation to learn how to use the
-LTTng&#8209;tools components.
-
-See also the [LTTng manual pages](https://lttng.org/man/) (all
-section&nbsp;1 and&nbsp;8 pages).
-
-As there's no official liblttng&#8209;ctl Python bindings yet, see
-[`doc/python-howto.txt`](doc/python-howto.txt) to understand how to
-use them.
-
-Community
----------
-* **Mailing list**:
-  [lttng&#8209;dev](https://lists.lttng.org/cgi-bin/mailman/listinfo).
-
-* **IRC channel**:
-  [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network.
-
-* **Bug tracker**::
-  [LTTng&#8209;tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/).
-
-* **GitHub project**:
-  [lttng/lttng&#8209;tools](https://github.com/lttng/lttng-tools/).
-
-* **Continuous integration**:
-  [LTTng CI](https://ci.lttng.org/).
-
-* **Code review**:
-  [_lttng&#8209;tools_ project](https://review.lttng.org/q/project:lttng-tools)
-  on LTTng Review.

diff --git a/doc/quickstart.txt b/doc/quickstart.txt
index 0e9751b599185e6719758b82436cee821c1448b4..9bcb8460469505f8834b86cce940111ca8bd0aa2 100644 (file)
--- a/doc/quickstart.txt
+++ b/doc/quickstart.txt
@@ -13,7 +13,7 @@ This is a quick start guide for the complete LTTng tool chain. This is divided
 in three sections respectively kernel tracing, user-space tracing and reading a
 trace.
 
 in three sections respectively kernel tracing, user-space tracing and reading a
 trace.
 

-See the README.md file for installation procedure or use the various Linux
+See the README.adoc file for installation procedure or use the various Linux

 distribution packages.
 
 In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and
 distribution packages.
 
 In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and

diff --git a/doc/streaming-howto.txt b/doc/streaming-howto.txt
index 9ba6fea22657fa76e5d80cca6361db24e6c7d424..db1938dfaab3bb6b54dd623aa30a60fa116a0e0f 100644 (file)
--- a/doc/streaming-howto.txt
+++ b/doc/streaming-howto.txt
@@ -5,7 +5,7 @@ STREAMING
 
 This is a brief howto for network streaming feature of lttng 2.0 toolchain.
 
 
 This is a brief howto for network streaming feature of lttng 2.0 toolchain.
 

-See the README.md file for installation procedure or use the various Linux
+See the README.adoc file for installation procedure or use the various Linux

 distribution packages.
 
 Terminology:
 distribution packages.
 
 Terminology: