[PATCH v3 0/9] doc: --stdin on notes and core.commentChar mentions

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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:
diff --git a/Documentation/git-notes.adoc b/Documentation/git-notes.adoc
index 43436daeccc..46a232ca718 100644
--- a/Documentation/git-notes.adoc
+++ b/Documentation/git-notes.adoc
@@ -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/xmqqcyct1mtq.fsf@gitster.g/
    +    [2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/
    +    † 3: v11 was the version that landed
     
    +    Helped-by: Junio C Hamano <gitster@pobox.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    +    v3:
    +    • Mention that it is a bug (“known limitation”) which might be fixed.
    +
    +      Link: https://lore.kernel.org/git/xmqqiklrvwl4.fsf@gitster.g/
    +    • 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/xmqqecwfvwdu.fsf@gitster.g/
         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