{"thread":{"id":"57529","subject":"[PATCH 0/4] A couple of fixes for the Trace2 documentation","startedAt":"2022-03-10T13:35:37Z","lastAt":"2022-05-03T15:40:58Z","messageCount":19,"participants":["Johannes Schindelin via GitGitGadget","Jeff Hostetler","Ævar Arnfjörð Bjarmason","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"451000","messageId":"pull.1172.git.1646919331.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":null,"subject":"[PATCH 0/4] A couple of fixes for the Trace2 documentation","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-10T13:35:27Z","receivedAt":"2022-03-10T13:35:37Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"While verifying a suggestion for a contributor before sending it, I noticed\nthat the Trace2 documentation contained an incorrect example. Looking\naround, I found a couple other things I wanted to fix, so here are the\npatches.\n\nJohannes Schindelin (4):\n trace2 docs: a couple of grammar fixes\n trace2 docs: surround more terms in backticks\n trace2 docs: fix a JSON formatted example\n trace2 docs: clarify what `varargs` is all about\n\n Documentation/technical/api-trace2.txt | 22 +++++++++++-----------\n 1 file changed, 11 insertions(+), 11 deletions(-)\n\n\nbase-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1172%2Fdscho%2Ffix-trace2-docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1172/dscho/fix-trace2-docs-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1172\n-- \ngitgitgadget\n"},{"id":"451001","messageId":"07f7ee46232b4ccc53787fa2e08887b436ee11c3.1646919331.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.git.1646919331.gitgitgadget@gmail.com","subject":"[PATCH 1/4] trace2 docs: a couple of grammar fixes","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-10T13:35:28Z","receivedAt":"2022-03-10T13:35:39Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex bb13ca3db8b..77216eff622 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -24,7 +24,7 @@ for example.\n \n Trace2 is controlled using `trace2.*` config values in the system and\n global config files and `GIT_TRACE2*` environment variables. Trace2 does\n-not read from repo local or worktree config files or respect `-c`\n+not read from repo local or worktree config files nor does it respect `-c`\n command line config settings.\n \n == Trace2 Targets\n@@ -34,8 +34,8 @@ Format details are given in a later section.\n \n === The Normal Format Target\n \n-The normal format target is a tradition printf format and similar\n-to GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n+The normal format target is a traditional printf format and similar\n+to the GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n environment variable or the `trace2.normalTarget` system or global\n config setting.\n \n@@ -635,7 +635,7 @@ process may be a shell script which doesn't have a session-id.)\n +\n This event is generated after the child is started in the background\n and given a little time to boot up and start working. If the child\n-startups normally and while the parent is still waiting, the \"ready\"\n+starts up normally while the parent is still waiting, the \"ready\"\n field will have the value \"ready\".\n If the child is too slow to start and the parent times out, the field\n will have the value \"timeout\".\n@@ -949,7 +949,7 @@ atexit elapsed:3.868970 code:0\n \n Regions::\n \n-\tRegions can be use to time an interesting section of code.\n+\tRegions can be used to time an interesting section of code.\n +\n ----------------\n void wt_status_collect(struct wt_status *s)\n@@ -1103,9 +1103,9 @@ Thread Events::\n \n \tThread messages added to a thread-proc.\n +\n-For example, the multithreaded preload-index code can be\n+For example, the multi-threaded preload-index code can be\n instrumented with a region around the thread pool and then\n-per-thread start and exit events within the threadproc.\n+per-thread start and exit events within the thread-proc.\n +\n ----------------\n static void *preload_thread(void *_data)\n-- \ngitgitgadget\n\n"},{"id":"451002","messageId":"284c6a3df84bed669790fe2f44905328269d1f4f.1646919331.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.git.1646919331.gitgitgadget@gmail.com","subject":"[PATCH 2/4] trace2 docs: surround more terms in backticks","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-10T13:35:29Z","receivedAt":"2022-03-10T13:35:41Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex 77216eff622..8ef921a4e4d 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -70,7 +70,7 @@ $ cat ~/log.normal\n \n The performance format target (PERF) is a column-based format to\n replace GIT_TRACE_PERFORMANCE and is suitable for development and\n-testing, possibly to complement tools like gprof. This format is\n+testing, possibly to complement tools like `gprof`. This format is\n enabled with the `GIT_TRACE2_PERF` environment variable or the\n `trace2.perfTarget` system or global config setting.\n \n@@ -172,7 +172,7 @@ take a `va_list` argument.\n Some functions have a `_printf_fl()` suffix to indicate that they also\n take a varargs argument.\n \n-There are CPP wrapper macros and ifdefs to hide most of these details.\n+There are CPP wrapper macros and `#ifdef`s to hide most of these details.\n See `trace2.h` for more details. The following discussion will only\n describe the simplified forms.\n \n-- \ngitgitgadget\n\n"},{"id":"451003","messageId":"b893f6a7faf8e27fc7ba3d214bc44925614638cf.1646919331.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.git.1646919331.gitgitgadget@gmail.com","subject":"[PATCH 3/4] trace2 docs: fix a JSON formatted example","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-10T13:35:30Z","receivedAt":"2022-03-10T13:35:49Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nThe example was not in valid JSON format due to a duplicate key \"sid\".\n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex 8ef921a4e4d..285f713ed84 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -128,7 +128,7 @@ yields\n \n ------------\n $ cat ~/log.event\n-{\"event\":\"version\",\"sid\":\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.620713Z\",\"file\":\"common-main.c\",\"line\":38,\"evt\":\"3\",\"exe\":\"2.20.1.155.g426c96fcdb\"}\n+{\"event\":\"version\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.620713Z\",\"file\":\"common-main.c\",\"line\":38,\"evt\":\"3\",\"exe\":\"2.20.1.155.g426c96fcdb\"}\n {\"event\":\"start\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.621027Z\",\"file\":\"common-main.c\",\"line\":39,\"t_abs\":0.001173,\"argv\":[\"git\",\"version\"]}\n {\"event\":\"cmd_name\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.621122Z\",\"file\":\"git.c\",\"line\":432,\"name\":\"version\",\"hierarchy\":\"version\"}\n {\"event\":\"exit\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.621236Z\",\"file\":\"git.c\",\"line\":662,\"t_abs\":0.001227,\"code\":0}\n-- \ngitgitgadget\n\n"},{"id":"451004","messageId":"2eecea50e5132b09574451f37ca76a5d4af8697f.1646919331.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.git.1646919331.gitgitgadget@gmail.com","subject":"[PATCH 4/4] trace2 docs: clarify what `varargs` is all about","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-03-10T13:35:31Z","receivedAt":"2022-03-10T13:35:49Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex 285f713ed84..91985512867 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -170,7 +170,7 @@ Some functions have a `_va_fl()` suffix to indicate that they also\n take a `va_list` argument.\n \n Some functions have a `_printf_fl()` suffix to indicate that they also\n-take a varargs argument.\n+take a `printf()` style format with a variable number of arguments.\n \n There are CPP wrapper macros and `#ifdef`s to hide most of these details.\n See `trace2.h` for more details. The following discussion will only\n-- \ngitgitgadget\n"},{"id":"451006","messageId":"f1fb96f3-6fec-0552-0fe9-74bfd935cca1@jeffhostetler.com","threadId":"57529","inReplyTo":"pull.1172.git.1646919331.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/4] A couple of fixes for the Trace2 documentation","fromName":"Jeff Hostetler","fromEmail":"git@jeffhostetler.com","sentAt":"2022-03-10T13:50:28Z","receivedAt":"2022-03-10T13:50:35Z","isPatch":true,"sender":{"key":"git@jeffhostetler.com","avatar":null},"body":"\n\nOn 3/10/22 8:35 AM, Johannes Schindelin via GitGitGadget wrote:\n> While verifying a suggestion for a contributor before sending it, I noticed\n> that the Trace2 documentation contained an incorrect example. Looking\n> around, I found a couple other things I wanted to fix, so here are the\n> patches.\n> \n> Johannes Schindelin (4):\n> trace2 docs: a couple of grammar fixes\n> trace2 docs: surround more terms in backticks\n> trace2 docs: fix a JSON formatted example\n> trace2 docs: clarify what `varargs` is all about\n> \n> Documentation/technical/api-trace2.txt | 22 +++++++++++-----------\n> 1 file changed, 11 insertions(+), 11 deletions(-)\n> \n> \n> base-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1172%2Fdscho%2Ffix-trace2-docs-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1172/dscho/fix-trace2-docs-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/1172\n> \n\nLGTM\n\nThanks\nJeff\n"},{"id":"451022","messageId":"220310.86ee39kh0v.gmgdl@evledraar.gmail.com","threadId":"57529","inReplyTo":"2eecea50e5132b09574451f37ca76a5d4af8697f.1646919331.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/4] trace2 docs: clarify what `varargs` is all about","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-03-10T14:37:44Z","receivedAt":"2022-03-10T14:54:00Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Mar 10 2022, Johannes Schindelin via GitGitGadget wrote:\n\n> From: Johannes Schindelin \n>\n> Signed-off-by: Johannes Schindelin \n> ---\n> Documentation/technical/api-trace2.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\n> index 285f713ed84..91985512867 100644\n> --- a/Documentation/technical/api-trace2.txt\n> +++ b/Documentation/technical/api-trace2.txt\n> @@ -170,7 +170,7 @@ Some functions have a `_va_fl()` suffix to indicate that they also\n> take a `va_list` argument.\n> \n> Some functions have a `_printf_fl()` suffix to indicate that they also\n> -take a varargs argument.\n> +take a `printf()` style format with a variable number of arguments.\n\nThis is correct, but I think better would be to explicitly describe the\n_printf_va_fl() suffix in this list, i.e. now that implicitly falls\nunder _va_fl(), so it's *technically* redundant.\n\nBut either describing it explicitly, or saying that `_printf_*_fl()` are\nfunction that take a printf format before either a \"va_args\" or \"...\"\nwould make the end-state a bit more obvious.\n\nI wonder if the pre-image wanted to describe `_printf_va_fl()` (which\nwould make it correct), and we just omitted a `printf_fl()` description.\n"},{"id":"451023","messageId":"220310.86ilslkh6n.gmgdl@evledraar.gmail.com","threadId":"57529","inReplyTo":"07f7ee46232b4ccc53787fa2e08887b436ee11c3.1646919331.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/4] trace2 docs: a couple of grammar fixes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-03-10T14:35:43Z","receivedAt":"2022-03-10T14:54:03Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Mar 10 2022, Johannes Schindelin via GitGitGadget wrote:\n\n> From: Johannes Schindelin \n>\n> Signed-off-by: Johannes Schindelin \n> ---\n> Documentation/technical/api-trace2.txt | 14 +++++++-------\n> 1 file changed, 7 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\n> index bb13ca3db8b..77216eff622 100644\n> --- a/Documentation/technical/api-trace2.txt\n> +++ b/Documentation/technical/api-trace2.txt\n> @@ -24,7 +24,7 @@ for example.\n> \n> Trace2 is controlled using `trace2.*` config values in the system and\n> global config files and `GIT_TRACE2*` environment variables. Trace2 does\n> -not read from repo local or worktree config files or respect `-c`\n> +not read from repo local or worktree config files nor does it respect `-c`\n\nPerhaps adding a comma before \"nor\" would also be a good addition.\n"},{"id":"451063","messageId":"xmqqk0d1eixc.fsf@gitster.g","threadId":"57529","inReplyTo":"220310.86ilslkh6n.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH 1/4] trace2 docs: a couple of grammar fixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-10T18:55:43Z","receivedAt":"2022-03-10T18:55:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> On Thu, Mar 10 2022, Johannes Schindelin via GitGitGadget wrote:\n>\n>> From: Johannes Schindelin \n>>\n>> Signed-off-by: Johannes Schindelin \n>> ---\n>> Documentation/technical/api-trace2.txt | 14 +++++++-------\n>> 1 file changed, 7 insertions(+), 7 deletions(-)\n>>\n>> diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\n>> index bb13ca3db8b..77216eff622 100644\n>> --- a/Documentation/technical/api-trace2.txt\n>> +++ b/Documentation/technical/api-trace2.txt\n>> @@ -24,7 +24,7 @@ for example.\n>> \n>> Trace2 is controlled using `trace2.*` config values in the system and\n>> global config files and `GIT_TRACE2*` environment variables. Trace2 does\n>> -not read from repo local or worktree config files or respect `-c`\n>> +not read from repo local or worktree config files nor does it respect `-c`\n>\n> Perhaps adding a comma before \"nor\" would also be a good addition.\n\nYup, that sounds sensible. All other hunks looked good, too.\n\nThanks, both.\n"},{"id":"451064","messageId":"xmqqee39eivs.fsf@gitster.g","threadId":"57529","inReplyTo":"284c6a3df84bed669790fe2f44905328269d1f4f.1646919331.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/4] trace2 docs: surround more terms in backticks","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-10T18:56:39Z","receivedAt":"2022-03-10T18:56:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Johannes Schindelin via GitGitGadget\" \nwrites:\n\n> From: Johannes Schindelin \n>\n> Signed-off-by: Johannes Schindelin \n> ---\n> Documentation/technical/api-trace2.txt | 4 ++--\n> 1 file changed, 2 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\n> index 77216eff622..8ef921a4e4d 100644\n> --- a/Documentation/technical/api-trace2.txt\n> +++ b/Documentation/technical/api-trace2.txt\n> @@ -70,7 +70,7 @@ $ cat ~/log.normal\n> \n> The performance format target (PERF) is a column-based format to\n> replace GIT_TRACE_PERFORMANCE and is suitable for development and\n\n`GIT_TRACE_PERFORMANCE` to match `GIT_TRACE2_PERF` we see below.\n\n> -testing, possibly to complement tools like gprof. This format is\n> +testing, possibly to complement tools like `gprof`. This format is\n> enabled with the `GIT_TRACE2_PERF` environment variable or the\n> `trace2.perfTarget` system or global config setting.\n> \n> @@ -172,7 +172,7 @@ take a `va_list` argument.\n> Some functions have a `_printf_fl()` suffix to indicate that they also\n> take a varargs argument.\n> \n> -There are CPP wrapper macros and ifdefs to hide most of these details.\n> +There are CPP wrapper macros and `#ifdef`s to hide most of these details.\n> See `trace2.h` for more details. The following discussion will only\n> describe the simplified forms.\n"},{"id":"451065","messageId":"xmqq8rtheiov.fsf@gitster.g","threadId":"57529","inReplyTo":"07f7ee46232b4ccc53787fa2e08887b436ee11c3.1646919331.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/4] trace2 docs: a couple of grammar fixes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-03-10T19:00:48Z","receivedAt":"2022-03-10T19:00:54Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Johannes Schindelin via GitGitGadget\" \nwrites:\n\n> @@ -34,8 +34,8 @@ Format details are given in a later section.\n> \n> === The Normal Format Target\n> \n> -The normal format target is a tradition printf format and similar\n> -to GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n> +The normal format target is a traditional printf format and similar\n> +to the GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n\nIn the same spirit as [2/4] and match the part that [4/4] touches,\nthis probably is better:\n\n The normal format target is a traditional `printf()` format and similar\n to the `GIT_TRACE` format. This format is enabled with the `GIT_TRACE2`\n\n"},{"id":"454772","messageId":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.git.1646919331.gitgitgadget@gmail.com","subject":"[PATCH v2 0/6] A couple of fixes for the Trace2 documentation","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-03T10:26:41Z","receivedAt":"2022-05-03T10:26:59Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"While verifying a suggestion for a contributor before sending it, I noticed\nthat the Trace2 documentation contained an incorrect example. Looking\naround, I found a couple other things I wanted to fix, so here are the\npatches.\n\nNote: This patch series is not intended to be perfectionist. I just want the\nresult to be good enough, and move on to more important things.\n\nChanges since v1:\n\n * Added an Oxford comma (at least I think it is a stylistic one, not a\n required one, but then, all three people involved in the discussion are\n non-native speakers, so there).\n * Added a patch to use a consistent style for function names.\n * I now surround even more terms in backticks.\n * I spotted and fixed a missing full stop, too.\n\nJohannes Schindelin (6):\n trace2 docs: a couple of grammar fixes\n trace2 docs: \"printf\" is not an English word\n trace2 docs: surround more terms in backticks\n trace2 docs: fix a JSON formatted example\n trace2 docs: clarify what `varargs` is all about\n trace2 docs: add missing full stop\n\n Documentation/technical/api-trace2.txt | 44 +++++++++++++-------------\n 1 file changed, 22 insertions(+), 22 deletions(-)\n\n\nbase-commit: 1a4874565fa3b6668042216189551b98b4dc0b1b\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1172%2Fdscho%2Ffix-trace2-docs-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1172/dscho/fix-trace2-docs-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1172\n\nRange-diff vs v1:\n\n 1: 07f7ee46232 ! 1: 3b944102ff2 trace2 docs: a couple of grammar fixes\n @@ Documentation/technical/api-trace2.txt: for example.\n Trace2 is controlled using `trace2.*` config values in the system and\n global config files and `GIT_TRACE2*` environment variables. Trace2 does\n -not read from repo local or worktree config files or respect `-c`\n -+not read from repo local or worktree config files nor does it respect `-c`\n - command line config settings.\n +-command line config settings.\n ++not read from repo local or worktree config files, nor does it respect\n ++`-c` command line config settings.\n \n == Trace2 Targets\n + \n @@ Documentation/technical/api-trace2.txt: Format details are given in a later section.\n \n === The Normal Format Target\n -: ----------- > 2: 3c1ca34927a trace2 docs: \"printf\" is not an English word\n 2: 284c6a3df84 ! 3: 2ddd9ff4506 trace2 docs: surround more terms in backticks\n @@ Commit message\n Signed-off-by: Johannes Schindelin \n \n ## Documentation/technical/api-trace2.txt ##\n +@@ Documentation/technical/api-trace2.txt: Format details are given in a later section.\n + === The Normal Format Target\n + \n + The normal format target is a traditional `printf()` format and similar\n +-to the GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n ++to the `GIT_TRACE` format. This format is enabled with the `GIT_TRACE2`\n + environment variable or the `trace2.normalTarget` system or global\n + config setting.\n + \n @@ Documentation/technical/api-trace2.txt: $ cat ~/log.normal\n + === The Performance Format Target\n \n The performance format target (PERF) is a column-based format to\n - replace GIT_TRACE_PERFORMANCE and is suitable for development and\n +-replace GIT_TRACE_PERFORMANCE and is suitable for development and\n -testing, possibly to complement tools like gprof. This format is\n ++replace `GIT_TRACE_PERFORMANCE` and is suitable for development and\n +testing, possibly to complement tools like `gprof`. This format is\n enabled with the `GIT_TRACE2_PERF` environment variable or the\n `trace2.perfTarget` system or global config setting.\n @@ Documentation/technical/api-trace2.txt: take a `va_list` argument.\n See `trace2.h` for more details. The following discussion will only\n describe the simplified forms.\n \n +@@ Documentation/technical/api-trace2.txt: as each thread starts and allocates TLS storage.\n + There are a few issues to resolve before we can completely\n + switch to Trace2.\n + \n +-* Updating existing tests that assume GIT_TRACE format messages.\n ++* Updating existing tests that assume `GIT_TRACE` format messages.\n + \n +-* How to best handle custom GIT_TRACE_ messages?\n ++* How to best handle custom `GIT_TRACE_` messages?\n + \n +-** The GIT_TRACE_ mechanism allows each to write to a\n ++** The `GIT_TRACE_` mechanism allows each to write to a\n + different file (in addition to just stderr).\n + \n + ** Do we want to maintain that ability or simply write to the existing\n 3: b893f6a7faf = 4: 1c5a7008382 trace2 docs: fix a JSON formatted example\n 4: 2eecea50e51 = 5: 0c09fd000a6 trace2 docs: clarify what `varargs` is all about\n -: ----------- > 6: e1a94b0d1ae trace2 docs: add missing full stop\n\n-- \ngitgitgadget\n"},{"id":"454773","messageId":"3b944102ff28ca8d8b66ddac707a48252f0843b2.1651573607.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","subject":"[PATCH v2 1/6] trace2 docs: a couple of grammar fixes","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-03T10:26:42Z","receivedAt":"2022-05-03T10:27:02Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex bb13ca3db8b..adf867e1013 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -24,8 +24,8 @@ for example.\n \n Trace2 is controlled using `trace2.*` config values in the system and\n global config files and `GIT_TRACE2*` environment variables. Trace2 does\n-not read from repo local or worktree config files or respect `-c`\n-command line config settings.\n+not read from repo local or worktree config files, nor does it respect\n+`-c` command line config settings.\n \n == Trace2 Targets\n \n@@ -34,8 +34,8 @@ Format details are given in a later section.\n \n === The Normal Format Target\n \n-The normal format target is a tradition printf format and similar\n-to GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n+The normal format target is a traditional printf format and similar\n+to the GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n environment variable or the `trace2.normalTarget` system or global\n config setting.\n \n@@ -635,7 +635,7 @@ process may be a shell script which doesn't have a session-id.)\n +\n This event is generated after the child is started in the background\n and given a little time to boot up and start working. If the child\n-startups normally and while the parent is still waiting, the \"ready\"\n+starts up normally while the parent is still waiting, the \"ready\"\n field will have the value \"ready\".\n If the child is too slow to start and the parent times out, the field\n will have the value \"timeout\".\n@@ -949,7 +949,7 @@ atexit elapsed:3.868970 code:0\n \n Regions::\n \n-\tRegions can be use to time an interesting section of code.\n+\tRegions can be used to time an interesting section of code.\n +\n ----------------\n void wt_status_collect(struct wt_status *s)\n@@ -1103,9 +1103,9 @@ Thread Events::\n \n \tThread messages added to a thread-proc.\n +\n-For example, the multithreaded preload-index code can be\n+For example, the multi-threaded preload-index code can be\n instrumented with a region around the thread pool and then\n-per-thread start and exit events within the threadproc.\n+per-thread start and exit events within the thread-proc.\n +\n ----------------\n static void *preload_thread(void *_data)\n-- \ngitgitgadget\n\n"},{"id":"454774","messageId":"3c1ca34927a6634bcfaf444cf0712f74ac48311e.1651573607.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","subject":"[PATCH v2 2/6] trace2 docs: \"printf\" is not an English word","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-03T10:26:43Z","receivedAt":"2022-05-03T10:27:06Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nWe append an ellipsis and enclose it in backticks to indicate that it is\na function elsewhere, let's also use that here.\n\nWhile at it, ensure the same for `waitpid()`.\n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex adf867e1013..1f1a06eabc6 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -5,7 +5,7 @@ information to stderr or a file. The Trace2 feature is inactive unless\n explicitly enabled by enabling one or more Trace2 Targets.\n \n The Trace2 API is intended to replace the existing (Trace1)\n-printf-style tracing provided by the existing `GIT_TRACE` and\n+`printf()`-style tracing provided by the existing `GIT_TRACE` and\n `GIT_TRACE_PERFORMANCE` facilities. During initial implementation,\n Trace2 and Trace1 may operate in parallel.\n \n@@ -34,7 +34,7 @@ Format details are given in a later section.\n \n === The Normal Format Target\n \n-The normal format target is a traditional printf format and similar\n+The normal format target is a traditional `printf()` format and similar\n to the GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n environment variable or the `trace2.normalTarget` system or global\n config setting.\n@@ -234,7 +234,7 @@ Events are written as lines of the form:\n \tis the event name.\n \n ``::\n-\tis a free-form printf message intended for human consumption.\n+\tis a free-form `printf()` message intended for human consumption.\n +\n Note that this may contain embedded LF or CRLF characters that are\n not escaped, so the event may spill across multiple lines.\n@@ -300,7 +300,7 @@ This field is in anticipation of in-proc submodules in the future.\n \tindicate a broad category, such as \"index\" or \"status\".\n \n ``::\n-\tis a free-form printf message intended for human consumption.\n+\tis a free-form `printf()` message intended for human consumption.\n \n ------------\n 15:33:33.532712 wt-status.c:2310 | d0 | main | region_enter | r1 | 0.126064 | | status | label:print\n@@ -588,7 +588,7 @@ with \"?\".\n \n `\"child_exit\"`::\n \tThis event is generated after the current process has returned\n-\tfrom the waitpid() and collected the exit information from the\n+\tfrom the `waitpid()` and collected the exit information from the\n \tchild.\n +\n ------------\n@@ -609,7 +609,7 @@ process may be a shell script which doesn't have a session-id.)\n +\n Note that the `t_rel` field contains the observed run time in seconds\n for the child process (starting before the fork/exec/spawn and\n-stopping after the waitpid() and includes OS process creation overhead).\n+stopping after the `waitpid()` and includes OS process creation overhead).\n So this time will be slightly larger than the atexit time reported by\n the child process itself.\n \n-- \ngitgitgadget\n\n"},{"id":"454775","messageId":"e1a94b0d1ae6032036c26ae96bec37718eaab752.1651573607.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","subject":"[PATCH v2 6/6] trace2 docs: add missing full stop","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-03T10:26:47Z","receivedAt":"2022-05-03T10:27:14Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex 05fa38cf651..f4a8a690878 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -533,7 +533,7 @@ these special values are used:\n ------------\n \n `\"cmd_mode\"`::\n-\tThis event, when present, describes the command variant This\n+\tThis event, when present, describes the command variant. This\n \tevent may be emitted more than once.\n +\n ------------\n-- \ngitgitgadget\n"},{"id":"454776","messageId":"0c09fd000a6ee9827d78df8993e0310623f9fd56.1651573607.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","subject":"[PATCH v2 5/6] trace2 docs: clarify what `varargs` is all about","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-03T10:26:46Z","receivedAt":"2022-05-03T10:27:16Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex bf0f0750733..05fa38cf651 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -170,7 +170,7 @@ Some functions have a `_va_fl()` suffix to indicate that they also\n take a `va_list` argument.\n \n Some functions have a `_printf_fl()` suffix to indicate that they also\n-take a varargs argument.\n+take a `printf()` style format with a variable number of arguments.\n \n There are CPP wrapper macros and `#ifdef`s to hide most of these details.\n See `trace2.h` for more details. The following discussion will only\n-- \ngitgitgadget\n\n"},{"id":"454777","messageId":"2ddd9ff4506475c44f68e14a4e0a9abce2806e3b.1651573607.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","subject":"[PATCH v2 3/6] trace2 docs: surround more terms in backticks","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-03T10:26:44Z","receivedAt":"2022-05-03T10:27:18Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex 1f1a06eabc6..e8a5d7c78d0 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -35,7 +35,7 @@ Format details are given in a later section.\n === The Normal Format Target\n \n The normal format target is a traditional `printf()` format and similar\n-to the GIT_TRACE format. This format is enabled with the `GIT_TRACE2`\n+to the `GIT_TRACE` format. This format is enabled with the `GIT_TRACE2`\n environment variable or the `trace2.normalTarget` system or global\n config setting.\n \n@@ -69,8 +69,8 @@ $ cat ~/log.normal\n === The Performance Format Target\n \n The performance format target (PERF) is a column-based format to\n-replace GIT_TRACE_PERFORMANCE and is suitable for development and\n-testing, possibly to complement tools like gprof. This format is\n+replace `GIT_TRACE_PERFORMANCE` and is suitable for development and\n+testing, possibly to complement tools like `gprof`. This format is\n enabled with the `GIT_TRACE2_PERF` environment variable or the\n `trace2.perfTarget` system or global config setting.\n \n@@ -172,7 +172,7 @@ take a `va_list` argument.\n Some functions have a `_printf_fl()` suffix to indicate that they also\n take a varargs argument.\n \n-There are CPP wrapper macros and ifdefs to hide most of these details.\n+There are CPP wrapper macros and `#ifdef`s to hide most of these details.\n See `trace2.h` for more details. The following discussion will only\n describe the simplified forms.\n \n@@ -1214,11 +1214,11 @@ as each thread starts and allocates TLS storage.\n There are a few issues to resolve before we can completely\n switch to Trace2.\n \n-* Updating existing tests that assume GIT_TRACE format messages.\n+* Updating existing tests that assume `GIT_TRACE` format messages.\n \n-* How to best handle custom GIT_TRACE_ messages?\n+* How to best handle custom `GIT_TRACE_` messages?\n \n-** The GIT_TRACE_ mechanism allows each to write to a\n+** The `GIT_TRACE_` mechanism allows each to write to a\n different file (in addition to just stderr).\n \n ** Do we want to maintain that ability or simply write to the existing\n-- \ngitgitgadget\n\n"},{"id":"454778","messageId":"1c5a700838201d7002351c8664b9a2c16a00688d.1651573607.git.gitgitgadget@gmail.com","threadId":"57529","inReplyTo":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","subject":"[PATCH v2 4/6] trace2 docs: fix a JSON formatted example","fromName":"Johannes Schindelin via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-05-03T10:26:45Z","receivedAt":"2022-05-03T10:27:21Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"From: Johannes Schindelin \n\nThe example was not in valid JSON format due to a duplicate key \"sid\".\n\nSigned-off-by: Johannes Schindelin \n---\n Documentation/technical/api-trace2.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt\nindex e8a5d7c78d0..bf0f0750733 100644\n--- a/Documentation/technical/api-trace2.txt\n+++ b/Documentation/technical/api-trace2.txt\n@@ -128,7 +128,7 @@ yields\n \n ------------\n $ cat ~/log.event\n-{\"event\":\"version\",\"sid\":\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.620713Z\",\"file\":\"common-main.c\",\"line\":38,\"evt\":\"3\",\"exe\":\"2.20.1.155.g426c96fcdb\"}\n+{\"event\":\"version\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.620713Z\",\"file\":\"common-main.c\",\"line\":38,\"evt\":\"3\",\"exe\":\"2.20.1.155.g426c96fcdb\"}\n {\"event\":\"start\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.621027Z\",\"file\":\"common-main.c\",\"line\":39,\"t_abs\":0.001173,\"argv\":[\"git\",\"version\"]}\n {\"event\":\"cmd_name\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.621122Z\",\"file\":\"git.c\",\"line\":432,\"name\":\"version\",\"hierarchy\":\"version\"}\n {\"event\":\"exit\",\"sid\":\"20190408T191610.507018Z-H9b68c35f-P000059a8\",\"thread\":\"main\",\"time\":\"2019-01-16T17:28:42.621236Z\",\"file\":\"git.c\",\"line\":662,\"t_abs\":0.001227,\"code\":0}\n-- \ngitgitgadget\n\n"},{"id":"454795","messageId":"7c805fc4-63a0-3329-1829-6b7212f3a6b7@jeffhostetler.com","threadId":"57529","inReplyTo":"pull.1172.v2.git.1651573607.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/6] A couple of fixes for the Trace2 documentation","fromName":"Jeff Hostetler","fromEmail":"git@jeffhostetler.com","sentAt":"2022-05-03T15:40:49Z","receivedAt":"2022-05-03T15:40:58Z","isPatch":true,"sender":{"key":"git@jeffhostetler.com","avatar":null},"body":"\n\nOn 5/3/22 6:26 AM, Johannes Schindelin via GitGitGadget wrote:\n> While verifying a suggestion for a contributor before sending it, I noticed\n> that the Trace2 documentation contained an incorrect example. Looking\n> around, I found a couple other things I wanted to fix, so here are the\n> patches.\n\nNice. Thanks for your attention to detail here.\n\nJeff\n\n"}]}