mbox series

[v2,0/6] A couple of fixes for the Trace2 documentation

Message ID pull.1172.v2.git.1651573607.gitgitgadget@gmail.com (mailing list archive)
Headers show
Series A couple of fixes for the Trace2 documentation | expand

Message

Johannes Schindelin via GitGitGadget May 3, 2022, 10:26 a.m. UTC 
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
          Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
      
       ## 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

Comments

Jeff Hostetler May 3, 2022, 3:40 p.m. UTC | #1 
On 5/3/22 6:26 AM, Johannes Schindelin via GitGitGadget wrote:
> 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.

Nice. Thanks for your attention to detail here.

Jeff