Re: `split-window-preferred-horizontally'

["Juanma Barranquero" <lekktu@gmail.com>]

On Sat, Jun 7, 2008 at 10:21, martin rudalics <rudalics@gmx.at> wrote:
>> And BTW, split-window-preferred-function's docstring is horribly
>> defcustom-oriented. `Vertically', `Horizontally' and `Sensibly' are
>> *not* the values the variable can have...
>
> But the doc-string is also what people customizing this read.

Yes. There are lot of variables that can be customized, and the
docstring usually reflects the values that it can have, not the tags
of the defcustom declaration. That's what the tags are for: to help
the people who's going through the customization interface.

>  I once
> used to put the valid values like `t' in the doc-string, and
> `vertically' plus `t' in parentheses in the tags of the customization
> interface and people complained. Hence, I don't know how to do this
> right.  Please write a better solution than the current one.

If I try to set up this variable out of customize (which I avoid like
hell), the current docstring is simply wrong. I had to go to the
source code to know what  *really* are the allowed values. The
docstring should reflect the truth (which, in this case, is that
`split-window-preferred-function' can have values `horizontally',
`sensibly', nil, or a function); then the defcustom tags would do its
job.

The following is what I would do (the specific wording is irrelevant).

--- window.el	6 Jun 2008 08:00:59 -0000	1.137
+++ window.el	7 Jun 2008 12:40:44 -0000
@@ -743,9 +743,12 @@
 (defcustom split-window-preferred-function nil
   "How `display-buffer' shall split windows.
-Choices are `Vertically', `Horizontally', and `Sensibly' where
-the latter attempts to split wide windows horizontally, narrow
-ones vertically.  Alternatively, you can set this to a function
-called with a window as single argument to split that window in
-two and return the new window."
+Choices are:
+  - `horizontally'   windows are split horizontally
+  - `sensibly'       attempt to split wide windows horizontally,
+                       narrow ones vertically
+  - nil              windows are split vertically
+  - a function       it will be called with a window as a single
+                       argument; it should split it in two and
+                       return the new window."
   :type '(choice
 	  (const :tag "Vertically" nil)