Discussion of local options is misleading

[Rich]

In all your discussion of how local options work (e.g. Chapter 11, Chapter 19) you instruct the reader to first open two windows, and then use :setlocal or :let &l: to set various options differently in the two windows. Then you note that the two windows now display differently.

However, this implies that had the reader used the regular set or let commands the outcome would have been different, which is not the case.

The problem is that the windows always use their own local values for the option, and this value is copied over from the global value (or when creating a split, from the current window value) when the window is created. Using an unadorned set will change both the local value for the current window/buffer and the global value, but it will not change the local values for other windows. So the difference between the two commands will only become apparent:

• when new buffers/windows are opened,
• when a :setglobal ...? command is used to specifically query the global value.

N.B. This (and more--e.g. the difference between "local to buffer" and "local to window" options) is all detailed in :h local-options. It might be helpful to add reading this as one of the exercises in chapter 11.

[Steve Losh]

Yeah, this is icky. I'm going to defer to the :h local-options you mentioned because it does a good job of explaining it and there's no sense in me repeating it.