On Mon, May 22, 2017 at 2:21 PM Alan Mackenzie <
address@hidden> wrote:
Thanks for taking on the task of finishing up the documentation of this
new facility.
Sure. I was just attempting to clarify things that were not clear to me as the mode-line-format is not very familiar to me.
I'm not completely happy with these changes, because I think they're a
bit misleading. Primarily, mode-line-percent-position _DOESN'T_ require
a 2-element list - just that that's what's most likely to be used. It
could also be nil, or (I think) a bare "%o", etc., or any other valid
mode line format fragment.
When I saw the defcustom options for mode-line-percent-position, it wasn't evident to me why %q had 6 as the first element and why the rest had -3.
How about: "Also add detail about what these elements typically are."
Sure. I was just reverse-engineering your patch, and documenting for my future-self :)
Or: "The option's value is typically a list of the form (WIDTH TYPE)
where WIDTH specifies the field width ... to display in
`mode-line-position' (see ....). It could be nil, or any other valid mode
line format construct."
Same as above.
> +WIDTH is specified as an integer. If the integer is negative (-N),
> +the width is truncated to N characters, and if it is positive (N),
> +padding is added, if needed, to make the field N characters wide.
> +
Here, I'm a bit bothered that we'd be documenting something which
doesn't really belong here. This meaning of an integer applies
throughout the whole of the mode line format, not just in
mode-line-percent-position.
I wasn't aware of that. Being not acquainted to mode-line-format. I thought that the the reason for -3 and 6 as first elements needed to be explained. mode-line-format docstring has this:
> A list whose car is an integer is processed by processing the cadr of
> the list, and padding (if the number is positive) or truncating (if
> negative) to the width specified by that number.
But I wanted the integer element description to be made even clearer. May be the mode-line-format docstring should be improved?
> +TYPE can be one of \"%o\", \"%p\", \"%P\" or \"%q\". See
> +`mode-line-format' for more information on these % constructs."
> :type `(radio
> (const :tag "nil: No offset is displayed" nil)
> (const :tag "\"%o\": Proportion of \"travel\" of the window through the buffer"
or ... "TYPE is typically one of \"%o\", ...."
OK.
This description of %o seems a bit clumsy and unintuitive, even though it
is accurate. What was wrong with my phrase "the proportion of
\"travel\" of the window through the buffer".
At first, I could not understand what that meant. But the analogy of a/(a+b) earlier in the thread made complete sense to me. So I just spelled that out in English, while also stealing the verbiage used in the Info manual text.
The last clause should be "or Top, BotTOM, or All". %o, %p, and %P
actually output "Bottom"; it is only the field width (-3) which
truncates it to "Bot". (I just learned that over the weekend. ;-)
I learned that just now :)
So in summary I was just attempting to explain the defcustom values of mode-line-percent-position better, by reverse-engineering. I had to refer to the initial discussion in this thread, docstring of mode-line-format and parts from the Info manual changes made by your commit to completely understand these options. So then I distilled all of that into the mode-line-percent-position docstring.
Can you please rephrase the mode-line-format and mode-line-percent-position docstrings taking that into account?