"Wesley J. Landaker" [off-list ref] writes:
quoted hunk
From: "Wesley J. Landaker" <redacted>
Update the documentation of the core.whitespace option
"indent-with-non-tab" to correctly reflect that it uses the currently
set tab width, set by the "tabwidth" option, rather than a fixed number.
Signed-off-by: Wesley J. Landaker <redacted>
---
Documentation/config.txt | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 6416cae..113a196 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -559,8 +559,8 @@ core.whitespace::
* `space-before-tab` treats a space character that appears immediately
before a tab character in the initial indent part of the line as an
error (enabled by default).
-* `indent-with-non-tab` treats a line that is indented with 8 or more
- space characters as an error (not enabled by default).
+* `indent-with-non-tab` treats a line that is indented with `tabwidth` space
+ characters or more as an error (not enabled by default).
I would rather see this part left untouched.
Your new text will force people who are not interested in using
non-standard tab width to read through the bulletted list, only to
find "The default tab width is 8". I think that is a regression in
the documentation for more common readers.
When somebody wants to use `indent-with-non-tab` and gets offended
by the seemingly hardcoded "8" in the description, the reader has
incentive to find out if there is a way to change that 8, and will
find `tabwidth=<n>` in the same bulletted list described, with the
effect it has on both `indent-with-non-tab` and `tab-in-indent`.
I think that should be sufficient for people who do use non-standard
tab width using tabwidth=<n>.
On 09/16/2012 11:16 PM, Junio C Hamano wrote:
I would rather see this part left untouched.
Your new text will force people who are not interested in using
non-standard tab width to read through the bulletted list, only to
find "The default tab width is 8". I think that is a regression in
the documentation for more common readers.
When somebody wants to use `indent-with-non-tab` and gets offended
by the seemingly hardcoded "8" in the description, the reader has
incentive to find out if there is a way to change that 8, and will
find `tabwidth=<n>` in the same bulletted list described, with the
effect it has on both `indent-with-non-tab` and `tab-in-indent`.
I think that should be sufficient for people who do use non-standard
tab width using tabwidth=<n>.
Well, I'm not going to push the issue further than this e-mail, but I
very much disagree. Please think about this:
* The whole whitespace section talks generically about "spaces" and
"tab characters". All of the options talk about tab in a generic way,
with the one single exception of "indent-with-non-tab".
* I know all about the tabwidth setting (I have it set in my
configuration), but when I went looking in the whitespace documentation
to try to flag a certain error I wanted to avoid, I was confused because
"indent-with-non-tab" didn't do what I wanted ... instead it apparently
used a hard-coded length of 8 spaces. My first thought was, well, I'd
better fix THAT bug!
* Of course, I did an experiment, and of course, it DOESN'T ACTUALLY
DO WHAT THE DOCUMENTATION SAYS, instead it uses the tabwidth. This is
good, I'm not complaining about how it works: this *is* what I want it
to do. But the documentation is still wrong.
* So, as you say, "the reader has incentive to find out if there is a
way to change that 8". I did get incentive to find that, but it took me
a few minutes of wasted time experimenting around with it, and then
motived me to write a patch so that no one else will ever get confused
about it again.
If I've perhaps convinced you that it would be beneficial to make the
documentation for this option precisely correct, but you don't like how
it's worded (it's the way it is because I tried to make a very minimal
change) I'd be happy to revise the patch, perhaps by changing the order
of presentation of the options (e.g. mentioning tab width earlier in the
section, or in some other way that you or someone may want to suggest).
In any case, please, let's find some way to make the documentation both
easy to read and also absolutely correct! =)