doc: --stdin on notes and core.commentChar mentions

From: Kristoffer Haugsbakk <[email protected]>

I wanted to fix --stdin in the git-notes(1) documentation. Then I found some other things on that doc as well as things to do with core.commentChar.

§ Changes in v3

Suggestions on patches 6 and 8 were implemented. See the patch notes and the interdiff.

Kristoffer Haugsbakk (9):
doc: stripspace: mention where the default comes from
doc: config: mention core.commentChar on commit.cleanup
doc: notes: split out options with negated forms
doc: notes: rework --[no-]stripspace
doc: notes: remove stripspace discussion from other options
doc: notes: clearly state that --stripspace is the default
doc: notes: point out copy --stdin use with argv
doc: notes: treat --stdin equally between copy/remove
doc: notes: use stuck form throughout

 Documentation/config/commit.adoc  |  7 ++--
 Documentation/git-notes.adoc      | 54 ++++++++++++++++++-------------
 Documentation/git-stripspace.adoc |  3 +-
 3 files changed, 38 insertions(+), 26 deletions(-)

Interdiff against v2:

index 43436daeccc..46a232ca718 100644
@@ -197,7 +197,8 @@ OPTIONS
 `-C`/`--reuse-message`. However, keep in mind that this depends on the
 order of similar options. For example, for `-C <object> -m<message>`,
 `--stripspace` will be used because the default for `-m` overrides the
-previous `-C`.
+previous `-C`. This is a known limitation that may be fixed in the
+future.
 
 `--ref=<ref>`::
 	Manipulate the notes tree in _<ref>_.  This overrides

@@ -211,7 +212,7 @@ previous `-C`.
 	object that does not have notes attached to it.
 
 `--stdin`::
-	For `remove` and `copy`. See the respective subcommands.
+	Only valid for `remove` and `copy`. See the respective subcommands.
 
 `-n`::
 `--dry-run`::

Range-diff against v2:

 1:  bf3ea7f23c0 =  1:  bf3ea7f23c0 doc: stripspace: mention where the default comes from
 2:  e9cf956a824 =  2:  e9cf956a824 doc: config: mention core.commentChar on commit.cleanup
 3:  14dc58120e3 =  3:  14dc58120e3 doc: notes: split out options with negated forms
 4:  c68a91f81ba =  4:  c68a91f81ba doc: notes: rework --[no-]stripspace
 5:  f4755040f38 =  5:  f4755040f38 doc: notes: remove stripspace discussion from other options
 6:  be89c3349d2 !  6:  184cf032abf doc: notes: clearly state that --stripspace is the default

@@ Commit message
Clearly state when which of the regular and negated form of the option take effect.[1]

+ Also mention the subtle behavior that occurs when you mix options like
+ -m and -C, including a note that it might be fixed in the future.
+ The topic was brought up on v8 of the --separator series.[2][3]
+
[1]: https://lore.kernel.org/git/[email protected]/
+ [2]: https://lore.kernel.org/git/[email protected]/
+ † 3: v11 was the version that landed

+ Helped-by: Junio C Hamano <[email protected]>

## Notes (series) ##
+ v3:
+ • Mention that it is a bug (“known limitation”) which might be fixed.
+
+ Link: https://lore.kernel.org/git/[email protected]/
+ • Message: discuss this new “subtle behavior” part
v2:
• New
• The -- are to prevent the new paragraph from becoming a continuation
@@ Documentation/git-notes.adoc: OPTIONS
+-C/--reuse-message. However, keep in mind that this depends on the +order of similar options. For example, for -C <object> -m<message>, +--stripspace will be used because the default for -m overrides the
-+previous -C.
++previous -C. This is a known limitation that may be fixed in the ++future.

--ref <ref>::
Manipulate the notes tree in _<ref>_. This overrides

 7:  d8a22847a7d =  7:  e18472f735d doc: notes: point out copy --stdin use with argv
 8:  3e8ecf1b668 !  8:  530dd953170 doc: notes: treat --stdin equally between copy/remove

@@ Commit message

## Notes (series) ##
+ v3:
+ • Rephrase to “Only valid for”
+
+ Link: https://lore.kernel.org/git/[email protected]/
v2:
• On --stdin: just refer to the respective subcommands and stop there. As suggested.
@@ Documentation/git-notes.adoc: When done, the user can either finalize the merge

prune::
Remove all notes for non-existing/unreachable objects.
-@@ Documentation/git-notes.adoc: previous -C. +@@ Documentation/git-notes.adoc: future.
object that does not have notes attached to it.

--stdin::
- Also read the object names to remove notes from the standard
- input (there is no reason you cannot combine this with object
- names from the command line).
-+ For remove and copy. See the respective subcommands.
++ Only valid for remove and copy. See the respective subcommands.

-n::
--dry-run::
9: 73bdcaecae5 ! 9: 7751330daa4 doc: notes: use stuck form throughout
@@ Notes (series)

## Documentation/git-notes.adoc ##
@@ Documentation/git-notes.adoc: order of similar options. For example, for -C <object> -m<message>,
- --stripspace will be used because the default for -m overrides the
- previous -C.
+ previous -C. This is a known limitation that may be fixed in the
+ future.

---ref <ref>::
+--ref=<ref>::

base-commit: cb96e1697ad6e54d11fc920c95f82977f8e438f8

2.49.0.780.g892193c3f50