A couple of fixes for the Trace2 documentation

While verifying a suggestion for a contributor before sending it, I noticed that the Trace2 documentation contained an incorrect example. Looking around, I found a couple other things I wanted to fix, so here are the patches.

Note: This patch series is not intended to be perfectionist. I just want the result to be good enough, and move on to more important things.

Changes since v1:

* Added an Oxford comma (at least I think it is a stylistic one, not a required one, but then, all three people involved in the discussion are non-native speakers, so there).
* Added a patch to use a consistent style for function names.
* I now surround even more terms in backticks.
* I spotted and fixed a missing full stop, too.

Johannes Schindelin (6):
trace2 docs: a couple of grammar fixes trace2 docs: "printf" is not an English word trace2 docs: surround more terms in backticks trace2 docs: fix a JSON formatted example trace2 docs: clarify what varargs is all about trace2 docs: add missing full stop

 Documentation/technical/api-trace2.txt | 44 +++++++++++++-------------
 1 file changed, 22 insertions(+), 22 deletions(-)

base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1172%2Fdscho%2Ffix-trace2-docs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1172/dscho/fix-trace2-docs-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1172

Range-diff vs v1:

1: 07f7ee46232 ! 1: 3b944102ff2 trace2 docs: a couple of grammar fixes
@@ Documentation/technical/api-trace2.txt: for example.
Trace2 is controlled using trace2.* config values in the system and global config files and GIT_TRACE2* environment variables. Trace2 does
-not read from repo local or worktree config files or respect -c
-+not read from repo local or worktree config files nor does it respect -c
- command line config settings.
+-command line config settings.
++not read from repo local or worktree config files, nor does it respect ++-c command line config settings.

== Trace2 Targets
+
@@ Documentation/technical/api-trace2.txt: Format details are given in a later section.

=== The Normal Format Target

 -:  ----------- > 2:  3c1ca34927a trace2 docs: "printf" is not an English word
 2:  284c6a3df84 ! 3:  2ddd9ff4506 trace2 docs: surround more terms in backticks

@@ Commit message

## Documentation/technical/api-trace2.txt ##
+@@ Documentation/technical/api-trace2.txt: Format details are given in a later section.
+ === The Normal Format Target
+
+ The normal format target is a traditional printf() format and similar +-to the GIT_TRACE format. This format is enabled with the GIT_TRACE2 ++to the GIT_TRACE format. This format is enabled with the GIT_TRACE2
+ environment variable or the trace2.normalTarget system or global
+ config setting.
+
@@ Documentation/technical/api-trace2.txt: $ cat ~/log.normal
+ === The Performance Format Target

The performance format target (PERF) is a column-based format to
- replace GIT_TRACE_PERFORMANCE and is suitable for development and +-replace GIT_TRACE_PERFORMANCE and is suitable for development and -testing, possibly to complement tools like gprof. This format is
++replace GIT_TRACE_PERFORMANCE and is suitable for development and
+testing, possibly to complement tools like gprof. This format is
enabled with the GIT_TRACE2_PERF environment variable or the trace2.perfTarget system or global config setting.
@@ Documentation/technical/api-trace2.txt: take a va_list argument.
See trace2.h for more details. The following discussion will only describe the simplified forms.

+@@ Documentation/technical/api-trace2.txt: as each thread starts and allocates TLS storage.
+ There are a few issues to resolve before we can completely
+ switch to Trace2.
+
+-* Updating existing tests that assume GIT_TRACE format messages.
++* Updating existing tests that assume GIT_TRACE format messages.
+
+-* How to best handle custom GIT_TRACE_<key> messages?
++* How to best handle custom GIT_TRACE_<key> messages?
+
+-** The GIT_TRACE_<key> mechanism allows each <key> to write to a
++** The GIT_TRACE_<key> mechanism allows each <key> to write to a
+ different file (in addition to just stderr).
+
+ ** Do we want to maintain that ability or simply write to the existing

 3:  b893f6a7faf = 4:  1c5a7008382 trace2 docs: fix a JSON formatted example
 4:  2eecea50e51 = 5:  0c09fd000a6 trace2 docs: clarify what `varargs` is all about
 -:  ----------- > 6:  e1a94b0d1ae trace2 docs: add missing full stop

gitgitgadget