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

[Kaushal Modi <kaushal.modi@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3700 bytes --]

On Mon, May 22, 2017 at 2:21 PM Alan Mackenzie <acm@muc.de> 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?
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 5586 bytes --]