docs: clarify some sentences

Add information to reduce ambiguity and make it easier to search for
more details elsewhere if needed.

Change-Id: I0a54b701961dcb2e2225b843eb5d89499bd2a12d
Signed-off-by: Erica Bugden <ebugden@efficios.com>

diff --git a/README.adoc b/README.adoc
index 288f1316f6c61cea61d823844f41b44d278ec883..df85c4e4c909c41a94071897784a55e9399107d0 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -16,7 +16,7 @@ https://ci.lttng.org/job/barectf_master_linuxbuild[image:https://img.shields.io/
 [.lead]
 https://barectf.org/[**_barectf_**] (from _bare_ metal and _CTF_)
 is a generator of
-https://en.wikipedia.org/wiki/Tracing_(software)[tracer] which produces
+https://en.wikipedia.org/wiki/Tracing_(software)[tracers] that produce
 https://diamon.org/ctf/[CTF] data streams.
 
 [NOTE]

diff --git a/docs/modules/how-barectf-works/pages/ctf-primer.adoc b/docs/modules/how-barectf-works/pages/ctf-primer.adoc
index 9dce0ea8e8affaf693564b87b051d77de5131d37..02b2c93400d784211e385268bbe88482e5145914 100644 (file)
--- a/docs/modules/how-barectf-works/pages/ctf-primer.adoc
+++ b/docs/modules/how-barectf-works/pages/ctf-primer.adoc
@@ -34,8 +34,9 @@ A _**CTF trace**_ is exactly one metadata stream and one or more
 [.width-50]
 image::ctf-trace.svg[]
 
-The metadata stream describes the trace's data streams with the TSDL
-language. On the file system, its file name must be `metadata`.
+The metadata stream describes the trace's data streams with TSDL
+(Trace Stream Description Language). On the file system, its file name
+must be `metadata`.
 
 The metadata stream describes things such as:
 
@@ -101,7 +102,8 @@ See the trace type features object's
 xref:yaml:trace-type-obj.adoc#magic-ft-prop[`magic-field-type`
 property].
 
-** [.opt]##Optional##A trace type UUID.
+** [.opt]##Optional##A trace type
+https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID].
 +
 See the trace type object's
 xref:yaml:trace-type-obj.adoc#uuid-prop[`uuid` property] and the

diff --git a/docs/modules/how-barectf-works/pages/index.adoc b/docs/modules/how-barectf-works/pages/index.adoc
index d1d2c9cda62caf2d7a4967e2b584a04702247a3e..124e9852d104b83f6aa170642be2215805400aea 100644 (file)
--- a/docs/modules/how-barectf-works/pages/index.adoc
+++ b/docs/modules/how-barectf-works/pages/index.adoc
@@ -8,9 +8,10 @@ type], xref:yaml:clk-type-obj.adoc[clock types],
 xref:yaml:dst-obj.adoc[data stream types], xref:yaml:ert-obj.adoc[event
 record types], and other options to generate the files.
 
-With the `barectf` Python package, you build the barectf configuration
-programatically by assembling configuration objects. This documentation
-is _not_ about the Python package.
+With the `barectf` https://pypi.org/project/barectf/[Python package],
+you build the barectf configuration programatically by assembling
+configuration objects. This documentation is _not_ about the Python
+package.
 
 The xref:cli:index.adoc[`barectf` CLI tool] can read a
 xref:yaml:index.adoc[YAML configuration file] and generate files out of
@@ -87,7 +88,8 @@ image::barectf-data-flow.svg[]
 
 . barectf also generates the tracer's C{nbsp}files.
 
-. You pass your application's C{nbsp}source file(s),
+. After adding calls to the generated tracing functions in your
+application code, you pass your application's C{nbsp}source file(s),
   xref:platform:index.adoc[platform]
   C{nbsp}source files, and the generated tracer's C{nbsp}source file to
   a xref:build:index.adoc[C{nbsp}compiler to create your final

diff --git a/docs/modules/yaml/pages/index.adoc b/docs/modules/yaml/pages/index.adoc
index 9ef5f737c3549e79e6ae2a666d867f6aefa3c440..f51afea98f3e7a5be6eef122584941e3a61a9cea 100644 (file)
--- a/docs/modules/yaml/pages/index.adoc
+++ b/docs/modules/yaml/pages/index.adoc
@@ -78,7 +78,7 @@ CLI command] shows the effective version of a YAML configuration file.
 == TSDL identifier
 
 Many barectf YAML objects require that a given string key or value
-be a valid TSDL identifier.
+be a valid TSDL (Trace Stream Description Language) identifier.
 
 As per https://diamon.org/ctf/v1.8.3/[CTF{nbsp}1.8.3], a valid TSDL
 identifier is any valid C{nbsp}identifier which is __not__ one of:

diff --git a/docs/modules/yaml/pages/yaml-primer.adoc b/docs/modules/yaml/pages/yaml-primer.adoc
index 03d4a0081a4dd599daa6a8f39098bab24f8039b5..32cd773fde89024a816210e512b6ec5907719787 100644 (file)
--- a/docs/modules/yaml/pages/yaml-primer.adoc
+++ b/docs/modules/yaml/pages/yaml-primer.adoc
@@ -142,7 +142,7 @@ Boolean::
     `true`, `True`, `TRUE`, `false`, `False`, or `FALSE`.
 
 Integer::
-    Anything matching:
+    Anything matching these regular expressions:
 +
 ** `+[-+]?[0-9]++` (decimal)
 ** `+0o[0-7]++` (octal)