From: "Johannes Schindelin via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: "Jeff Hostetler" <jeffhost@microsoft.com>,
"Jeff Hostetler" <git@jeffhostetler.com>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
"Johannes Schindelin" <johannes.schindelin@gmx.de>
Subject: [PATCH v2 0/6] A couple of fixes for the Trace2 documentation
Date: Tue, 03 May 2022 10:26:41 +0000 [thread overview]
Message-ID: <pull.1172.v2.git.1651573607.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1172.git.1646919331.gitgitgadget@gmail.com>
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
--
gitgitgadget
next prev parent reply other threads:[~2022-05-03 10:26 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-03-10 13:35 [PATCH 0/4] A couple of fixes for the Trace2 documentation Johannes Schindelin via GitGitGadget
2022-03-10 13:35 ` [PATCH 1/4] trace2 docs: a couple of grammar fixes Johannes Schindelin via GitGitGadget
2022-03-10 14:35 ` Ævar Arnfjörð Bjarmason
2022-03-10 18:55 ` Junio C Hamano
2022-03-10 19:00 ` Junio C Hamano
2022-03-10 13:35 ` [PATCH 2/4] trace2 docs: surround more terms in backticks Johannes Schindelin via GitGitGadget
2022-03-10 18:56 ` Junio C Hamano
2022-03-10 13:35 ` [PATCH 3/4] trace2 docs: fix a JSON formatted example Johannes Schindelin via GitGitGadget
2022-03-10 13:35 ` [PATCH 4/4] trace2 docs: clarify what `varargs` is all about Johannes Schindelin via GitGitGadget
2022-03-10 14:37 ` Ævar Arnfjörð Bjarmason
2022-03-10 13:50 ` [PATCH 0/4] A couple of fixes for the Trace2 documentation Jeff Hostetler
2022-05-03 10:26 ` Johannes Schindelin via GitGitGadget [this message]
2022-05-03 10:26 ` [PATCH v2 1/6] trace2 docs: a couple of grammar fixes Johannes Schindelin via GitGitGadget
2022-05-03 10:26 ` [PATCH v2 2/6] trace2 docs: "printf" is not an English word Johannes Schindelin via GitGitGadget
2022-05-03 10:26 ` [PATCH v2 3/6] trace2 docs: surround more terms in backticks Johannes Schindelin via GitGitGadget
2022-05-03 10:26 ` [PATCH v2 4/6] trace2 docs: fix a JSON formatted example Johannes Schindelin via GitGitGadget
2022-05-03 10:26 ` [PATCH v2 5/6] trace2 docs: clarify what `varargs` is all about Johannes Schindelin via GitGitGadget
2022-05-03 10:26 ` [PATCH v2 6/6] trace2 docs: add missing full stop Johannes Schindelin via GitGitGadget
2022-05-03 15:40 ` [PATCH v2 0/6] A couple of fixes for the Trace2 documentation Jeff Hostetler
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=pull.1172.v2.git.1651573607.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=avarab@gmail.com \
--cc=git@jeffhostetler.com \
--cc=git@vger.kernel.org \
--cc=jeffhost@microsoft.com \
--cc=johannes.schindelin@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).