[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Proposal: new mode-line `%'-construct %o meaning "Degree of travel o

From: Kaushal Modi
Subject: Re: Proposal: new mode-line `%'-construct %o meaning "Degree of travel of window through buffer".
Date: Mon, 22 May 2017 18:55:34 +0000

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

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\", ...."

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?

Kaushal Modi

reply via email to

[Prev in Thread] Current Thread [Next in Thread]