indent-tabs-mode scope?

[Skip Montanaro <skip.montanaro@gmail.com>]

I'm looking for a bit of confirmation here. I recently customized
indent-tabs-mode to be nil by default. Previously, it was nil for
python-mode (makes sense), but t elsewhere (the Emacs default). It
appears that despite its name, it suppresses tab insertion everywhere
possible, not just at the beginning of a line. For example, suppose
I'm editing an SQL create table statement and want the column types to
line up. I might start with this:

CREATE TABLE Foo
(
  col1               INT NOT NULL,
  col2

then press TAB after typing "2". The cursor will be positioned under
the "I" in "INT", using nothing but SPACE characters to achieve that
effect. This is due to the value of indent-tabs-mode. Looking at the
description for that variable, I see:

  Indentation can insert tabs if this is non-nil.

I casually think of "indentation" as occurring only at the start of a
line, but I suppose anywhere you want to advance the cursor to a "tab
stop" (for those of you, who like me learned to type on a typewriter),
the inserted white space could be considered indentation as well.

Empirically, this looks like the case. I wonder if the doc string for
indent-tabs-mode or for the indent-for-tab-command function should be
tightened up a bit to explicitly describe this behavior. The
indent-for-tab-command function doc string makes no mention of
indent-tabs-mode, though it seems clear it alters the function's
behavior (even without a dive into the code).

If this is deemed a Good Thing, I will try and produce a PR for a doc change.

Thanks,

Skip Montanaro