Improve README.md

Changes:

* Harmonize voice and style.

* Add non-breaking spaces and hyphens where missing.

* Add many internal and external links.

* Add `lttng-crash` and the Python bindings to the list of components.

* Use `≥` instead of `>=` (welcome to 2020).

* Do not specify why you need to configure with `--disable-epoll` to use
  a Linux kernel < 2.6.27: I don't think the end user needs to know
  about poll() vs. epoll().

* Do not mention Mathieu Desnoyers and Paul E. McKenney (this is a
  README, not the `THANKS` file).

* Mention Babeltrace 2 instead of Babeltrace.

* Use `https://babeltrace.org/` instead of
  `https://lttng.org/babeltrace`.

* Add kmod to the list of optional dependencies.

* Specify that you can use `--enable-embedded-help` at build
  configuration time if you don't plan to have a manual pager installed
  on your system.

* Don't mention the known GNU gold bug
  (`http://sourceware.org/bugzilla/show_bug.cgi?id=11317`).

  Again, the end user only cares about which minimal version of the tool
  to use, not why.

* Use clear, ordered build steps.

  For the configuration step, specify which options are available and
  what they change.

* Remove the link to `doc/quickstart.txt`.

  Link to the LTTng Documentation and online manual pages instead, which
  are more complete.

* Remove the link to `doc/streaming-howto.txt`: the LTTng Documentation
  and online manual pages cover this topic.

* Change the "Contact" section for the "Community" section and put all
  the community/communication links in there.

* Remove the "Package contents" section: end users do not care about
  this and we're not keeping it updated as we amend the project's source
  anyway.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I4e4c0b183d9a18243db23cde3edb608e32c5e30e
(cherry picked from commit f8bd3a12204c10743dfbc456d363e30894eddfc5)
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/README.md b/README.md
index 92df20daf48c94d410c56ebda8580cd1cbb26052..62622580405c6f9ba2fd702fd2dfe7f74745c000 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,177 +1,217 @@
-LTTng-tools
-===========
+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 tools to control [LTTng](https://lttng.org/)
-tracing. The project includes the LTTng session daemon, consumer daemon
-and relay daemon, as well as `liblttng-ctl`, a C library used to
-communicate with the session daemon, and `lttng`, a command line
-interface to `liblttng-ctl`.
-
-
-Requirements and optional dependencies
---------------------------------------
-
-The following items are _required_ to build and run LTTng-tools
-components:
-
-  - **Linux kernel >= 2.6.27**: for `epoll()` support, at least this
-    version is needed. However, `poll()` is also supported by
-    configuring LTTng-tools with the `--disable-epoll` option. Using
-    that, the kernel version may probably be older, but we can't provide
-    any guarantee. Please let us know if you are able to go lower
-    without any problems.
-  - **[`liburcu`](http://www.liburcu.org/) >= 0.9.0**: userspace RCU library,
-    by Mathieu Desnoyers and Paul E. McKenney.
-  - **`libpopt` >= 1.13**:  command line arguments parsing library.
-    - Debian/Ubuntu package: `libpopt-dev`
-  - **`libxml2` >= 2.7.6**:  XML document parsing library. Needed for
-    tracing session configuration saving/loading and machine interface
-    output support.
-    - Debian/Ubuntu package: `libxml2-dev`
-
-
-The following items are _optional_ dependencies:
-
-  - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
-    Enables the use of `lttng view` command.
-    - Debian/Ubuntu package: `babeltrace`
-  - **[LTTng UST](https://lttng.org) (same minor version as LTTng Tools)**:
-    userspace tracer. Enables the tracing of userspace applications.
-    - Debian/Ubuntu package: `liblttng-ust-dev`
-  - **Perl**: needed for `make check` and tests.
-  - **Python >= 3.0**: needed for `make check` and tests.
-    - Debian/Ubuntu package: `python3`
-  - **SWIG >= 2.0** and **Python 3 development headers**: needed for
-    Python bindings
-    (enabled at configure time with the `--enable-python-bindings` option).
-    - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
-  - **modprobe**: needed for automatic LTTng kernel modules loading
-    (kernel tracing).
-  - **bash**: needed to run `make check`.
-  - **man** (manual pager): needed to view LTTng-tools commands' man
-    pages with the `--help` option or with the `lttng help` command.
-    Note that without `man`, you cannot get offline help with
-    LTTng-tools commands, not even their usage.
-  - **libpfm >= 4.0**: needed to run the perf regression test suite.
-    - Debian/Ubuntu package: `libpfm4-dev`
-
-LTTng-tools supports both the [LTTng Linux Kernel tracer](https://lttng.org)
-and [LTTng user space tracer](https://lttng.org) released as part of the same
-**minor** release series. While some releases do not change the tracer ABIs and
-should work with, no testing is performed to ensure cross-version compatibility
-is maintained.
-
-Note that applications instrumented with older versions of the LTTng UST project
-do not have to be rebuilt or modified to work with the latest LTTng-tools.
-For more information on versioning, please refer to the
-[LTTng documentation](https://lttng.org/docs).
-
-Building
---------
-
-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.64**,
-    **Autoheader >= 2.50**; make sure your system-wide `automake` points
-    to a recent version)
-  - **[GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2**
-  - **Flex >= 2.5.35**
-  - **Bison >= 2.4**
-
-Optional packages to build LTTng-tools man pages:
-
-  - **AsciiDoc >= 8.4.5** (previous versions may work, but were
-    not tested)
-  - **xmlto >= 0.0.21** (previous versions may work, but were
-    not tested)
-
-If you use GNU gold, which is _not_ mandatory, make sure you have this
-version:
-
-  - **GNU gold >= 2.22**
-
-Before this version of GNU gold, we hit a
-[known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
-Be advised that with GNU gold, you might have to specify
-`-L/usr/local/lib` in `LDFLAGS`.
-
-If you get the tree from the Git repository, you will need to run
-
-    ./bootstrap
-
-in its root. It calls all the GNU tools needed to prepare the tree
-configuration.
-
-To build LTTng-tools, do:
-
-    ./configure
-    make
-    sudo make install
-    sudo ldconfig
-
-If you want Python bindings, add the `--enable-python-bindings` option
-to `configure`. Please note that some distributions will need the
-following environment variables set before running configure:
-
-    export PYTHON="python3"
-    export PYTHON_CONFIG="/usr/bin/python3-config"
-
-
-Using
------
+_**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 to liblttng‑ctl.
+* [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line
+  tool 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.
 
-Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
-with LTTng tracing. You can also use the `-h` or `--help` option of
-any `lttng` command, e.g.:
+See the [LTTng Documentation](https://lttng.org/docs/) for more
+information on versioning.
 
-    lttng enable-event --help
+Build from source
+-----------------
+### Dependencies
 
-A network streaming HOWTO can be found in
-[`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
-helps you understand how to stream a LTTng 2.x trace.
+You need the following tools to build LTTng‑tools:
 
-A Python binding HOWTO can be found in
-[`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
-understand how to use the Python module to control LTTng.
+* **[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).
 
-Contact
--------
+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.
 
-Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com)
+Community
+---------
+* **Mailing list**:
+  [lttng&#8209;dev](https://lists.lttng.org/cgi-bin/mailman/listinfo).
 
-Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
+* **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/).
 
-Package contents
-----------------
+* **GitHub project**:
+  [lttng/lttng&#8209;tools](https://github.com/lttng/lttng-tools/).
 
-This package contains the following elements:
+* **Continuous integration**:
+  [LTTng CI](https://ci.lttng.org/).
 
-  - `doc`: LTTng-tools documentation.
-  - `include`: the public header files that will be installed on the system.
-  - `src/bin`: source code of LTTng-tools programs.
-    - `lttng-consumerd`: consumer daemon.
-    - `lttng-crash`: crash trace viewer.
-    - `lttng-relayd`: relay daemon.
-    - `lttng-sessiond`: session daemon.
-    - `lttng`: command line interface for LTTng tracing control.
-  - `src/common`: common LTTng-tools source code.
-    - `compat`: compatibility library mostly for FreeBSD and Linux.
-    - `config`: tracing session configuration saving/loading.
-    - `hashtable`: library wrapper over Userspace RCU hashtables.
-    - `health`: health check subsytem.
-    - `index`: CTF index utilities.
-    - `kernel-consumer`: Linux kernel consumer.
-    - `kernel-ctl`: Linux kernel tracer control.
-    - `relayd`: relay daemon control.
-    - `sessiond-comm`: session daemon communication.
-    - `ust-consumer`: user space consumer.
-  - `src/lib`: source code of LTTng-tools libraries.
-    - `lttng-ctl`: LTTng control library.
-  - `tests`: various test programs.
+* **Code review**:
+  [_lttng&#8209;tools_ project](https://review.lttng.org/q/project:lttng-tools)
+  on LTTng Review.