[RFC/PATCH] Document -B<n>[/<m>], -M<n> and -C<n> variants of -B, -M and -C

These options take an optional argument, but this optional argument was
not documented.

Signed-off-by: Matthieu Moy <redacted>
---
I'm not really happy with my description of -Bn/m, which I essentially
took from eeaa46031479 (Junio, Jun 3 2005, diff: Update -B
heuristics). Someone with better understanding of how it works can
probably propose something better.

 Documentation/diff-options.txt |   18 ++++++++++++++----
 1 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 2371262..d07809c 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt

@@ -206,10 +206,18 @@ endif::git-format-patch[]
 	the diff-patch output format.  Non default number of
 	digits can be specified with `--abbrev=<n>`.
 
--B::
+-B[<n>]::
+-B<n>/<m>::
 	Break complete rewrite changes into pairs of delete and create.
-
--M::
+	If `n` is specified, it gives the threshold (as a percentage
+	of changed lines) above which a change is considered as
+	complete rewrite.  For example, `-B90%` means git will detect a
+	rewrite if more than 90% of the lines have been modified.  If
+	`m` is specified, then it is the minimum amount of deleted
+	lines a surviving broken pair must have to avoid being merged
+	back together.  See linkgit:gitdiffcore[7] for more details.
+
+-M[<n>]::
 ifndef::git-log[]
 	Detect renames.
 endif::git-log[]

@@ -218,9 +226,11 @@ ifdef::git-log[]
 	For following files across renames while traversing history, see
 	`--follow`.
 endif::git-log[]
+	If `n` is specified, it has the same meaning as for `-B<n>`.
 
--C::
+-C[<n>]::
 	Detect copies as well as renames.  See also `--find-copies-harder`.
+	If `n` is specified, it has the same meaning as for `-B<n>`.
 
 ifndef::git-format-patch[]
 --diff-filter=[ACDMRTUXB*]::

-- 
1.7.2.25.g9ebe3

Matthieu Moy [off-list ref] writes:

I'm not really happy with my description of -Bn/m, which I essentially
took from eeaa46031479 (Junio, Jun 3 2005, diff: Update -B
heuristics). Someone with better understanding of how it works can
probably propose something better.

Your explanation for '<n>' being the same across -B/-M/-C is reasonable.
Explanation of '<m>' might want to clarify why it counts only the deletion
and to mention that "100-similarity != dissimilarity", but as the end-user
level documentation, these probably are unnecessary.

+-B[<n>]::
+-B<n>/<m>::
 	Break complete rewrite changes into pairs of delete and create.
+	If `n` is specified, it gives the threshold (as a percentage
+	of changed lines) above which a change is considered as
+	complete rewrite.  For example, `-B90%` means git will detect a
+	rewrite if more than 90% of the lines have been modified. ...

I am fine with the use of word "lines" if it is clear that we are giving a
simplified explanation (white lie) to the readers, but the (dis)similarity
numbers don't have much to do with "lines".  I would of course be happier
if we can come up with a phrase that tells the readers that these numbers
range between 0-100%, and the larger the <n> is, the larger the extent of
change has to be for the filepair to be considered for -B/-M processing,
without use of word "lines".

Thanks.