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@xxxxxx> ## 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
