Skip to contentSkip to conversation

doc: interpret-trailers: fix cmd examples

PATCH Superseded [email protected] 2 participants 5 messages Sep 27 – Oct 4 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 doc: interpret-trailers: fix cmd examples

From: Kristoffer Haugsbakk <[email protected]>

Fix trailer.<key-alias>.cmd examples which have remained unchanged since they were written in c364b7ef (trailer: add new .cmd config option, 2021-05-03). (Modulo formatting changes.)

Use this example as a guide for how to phrase it:

Configure a see trailer with a command to show the subject of a commit that is related, and show how it works:

---

Notes (series):
Topic name: kh/doc-trailers-cmd-examples

 Documentation/git-interpret-trailers.adoc | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +4 -6
index 77b4f63b05c..3e81632b252 100644
@@ -305,9 +305,8 @@ subject
 Fix #42
 ------------
 
-* Configure a `help` trailer with a cmd use a script `glog-find-author`
-  which search specified author identity from git log in git repository
-  and show how it works:
+* Configure a `help` trailer with a command that searches for an author
+  identity and show how it works:
 +
 ------------
 $ cat ~/bin/glog-find-author
@@ -329,9 +328,8 @@ Helped-by: Junio C Hamano <[email protected]>
 Helped-by: Christian Couder <[email protected]>
 ------------
 
-* Configure a `ref` trailer with a cmd use a script `glog-grep`
-  to grep last relevant commit from git log in the git repository
-  and show how it works:
+* Configure a `ref` trailer with a command that searches for the last
+  relevant commit and show how it works:
 +
 ------------
 $ cat ~/bin/glog-grep

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc

Signature · 1 line
2.55.0.793.gc667de3f2c5
#1 lore raw
Quoted 10 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

Fix trailer.<key-alias>.cmd examples which have remained unchanged since they were written in c364b7ef (trailer: add new .cmd config option, 2021-05-03). (Modulo formatting changes.)

Use this example as a guide for how to phrase it:

Configure a see trailer with a command to show the subject of a commit that is related, and show how it works:

This read as if you are declaring that you use a template that invented to consistently give intro for each example, and made it look like the use of see was as a placeholder. It would have avoided the "Huh?" reaction if it were phrased like so:

Steal how example to show the see trailer is phrased and use it throughout:

Configure a see trailer ...

Other than that, this looks good.

Quoted 39 lines

---

Notes (series):
Topic name: kh/doc-trailers-cmd-examples

 Documentation/git-interpret-trailers.adoc | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +4 -6
index 77b4f63b05c..3e81632b252 100644
@@ -305,9 +305,8 @@ subject
 Fix #42
 ------------
 
-* Configure a `help` trailer with a cmd use a script `glog-find-author`
-  which search specified author identity from git log in git repository
-  and show how it works:
+* Configure a `help` trailer with a command that searches for an author
+  identity and show how it works:
 +
 ------------
 $ cat ~/bin/glog-find-author
@@ -329,9 +328,8 @@ Helped-by: Junio C Hamano <[email protected]>
 Helped-by: Christian Couder <[email protected]>
 ------------
 
-* Configure a `ref` trailer with a cmd use a script `glog-grep`
-  to grep last relevant commit from git log in the git repository
-  and show how it works:
+* Configure a `ref` trailer with a command that searches for the last
+  relevant commit and show how it works:
 +
 ------------
 $ cat ~/bin/glog-grep

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc

#2 lore raw
Quoted 18 lines · Junio C Hamano
Quoted 10 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

Fix trailer.<key-alias>.cmd examples which have remained unchanged since they were written in c364b7ef (trailer: add new .cmd config option, 2021-05-03). (Modulo formatting changes.)

Use this example as a guide for how to phrase it:

Configure a see trailer with a command to show the subject of a commit that is related, and show how it works:

This read as if you are declaring that you use a template that invented to consistently give intro for each example, and made it look like the use of see was as a placeholder. It would have avoided the "Huh?" reaction if it were phrased like so:

Quoted 6 lines

Steal how example to show the see trailer is phrased and use it throughout:

Configure a see trailer ...

Other than that, this looks good.

I’ll make that change.

#3 lore raw

PATCH v2 1/1 doc: interpret-trailers: fix cmd examples

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

Fix trailer.<key-alias>.cmd examples which have remained unchanged since they were written in c364b7ef (trailer: add new .cmd config option, 2021-05-03). (Modulo formatting changes.)

Steal how the see example is phrased and use that as a template:

Configure a see trailer with a command to show the subject of a commit that is related, and show how it works:

---

Notes (series):
Topic name (applied): kh/doc-trailers-cmd-examples

v2:
• *Steal* the *existing* example:
https://lore.kernel.org/git/[email protected]/

 Documentation/git-interpret-trailers.adoc | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)
Documentation/git-interpret-trailers.adoc +4 -6
index 77b4f63b05c..3e81632b252 100644
@@ -305,9 +305,8 @@ subject
 Fix #42
 ------------
 
-* Configure a `help` trailer with a cmd use a script `glog-find-author`
-  which search specified author identity from git log in git repository
-  and show how it works:
+* Configure a `help` trailer with a command that searches for an author
+  identity and show how it works:
 +
 ------------
 $ cat ~/bin/glog-find-author
@@ -329,9 +328,8 @@ Helped-by: Junio C Hamano <[email protected]>
 Helped-by: Christian Couder <[email protected]>
 ------------
 
-* Configure a `ref` trailer with a cmd use a script `glog-grep`
-  to grep last relevant commit from git log in the git repository
-  and show how it works:
+* Configure a `ref` trailer with a command that searches for the last
+  relevant commit and show how it works:
 +
 ------------
 $ cat ~/bin/glog-grep

Interdiff against v1:

Range-diff against v1:
1: c916709d7a3 ! 1: a8c56a91163 doc: interpret-trailers: fix cmd examples
@@ Commit message
since they were written in c364b7ef (trailer: add new .cmd config option, 2021-05-03). (Modulo formatting changes.)

- Use this example as a guide for how to phrase it:
+ Steal how the see example is phrased and use that as a template:

Configure a see trailer with a command to show the subject of a commit that is related, and show how it works:

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc

Signature · 1 line
2.55.0.793.gc667de3f2c5
#4 lore raw
Quoted 6 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>

Fix trailer.<key-alias>.cmd examples which have remained unchanged since they were written in c364b7ef (trailer: add new .cmd config option, 2021-05-03). (Modulo formatting changes.)

Quoted 7 lines

Steal how the see example is phrased and use that as a template:

Configure a see trailer with a command to show the subject of a commit that is related, and show how it works:

---

Let me mark the topic for 'next'.
Thanks.