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

[Alan Mackenzie]

Hello, Kaushal.

Thanks for taking on the task of finishing up the documentation of this
new facility.

On Mon, May 22, 2017 at 13:38:51 +0000, Kaushal Modi wrote:
> On Mon, May 22, 2017 at 12:14 AM Eli Zaretskii <address@hidden> wrote:

> > Our style for documenting Lisp data structures is less abstract:

> >   This option's value is a list of the form (WIDTH TYPE),
> >   where WIDTH specifies ...


> Attached patch has docstring updates for both mode-line-percentage-position
> and mode-line-format.

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.

> From 3c5dd77ad2c59c64e96456c2629c446f3a8c4107 Mon Sep 17 00:00:00 2001
> From: Kaushal Modi <address@hidden>
> Date: Sun, 21 May 2017 22:16:57 -0400
> Subject: [PATCH] Add detail to mode-line-percentage-position and
>  mode-line-format doc
>
> * lisp/bindings.el (mode-line-percent-position): Mention that this
>   variable requires a 2-element list.  Also add detail about what
>   those elements should be.

How about: "Also add detail about what these elements typically are."

>
> * src/buffer.c (syms_of_buffer): Add description for the new %o and %q
>   constructs in `mode-line-format'.
> ---
>  lisp/bindings.el | 17 +++++++++++++----
>  src/buffer.c     |  5 +++++
>  2 files changed, 18 insertions(+), 4 deletions(-)
>
> diff --git a/lisp/bindings.el b/lisp/bindings.el
> index 0e6ffc275e..895faa8a7e 100644
> --- a/lisp/bindings.el
> +++ b/lisp/bindings.el
> @@ -366,10 +366,19 @@ column-number-indicator-zero-based
>    :version "26.1")
>
>  (defcustom mode-line-percent-position '(-3 "%p")
> -  "Specification of \"percentage offset\" of window through buffer
> -This option specifies both the field width and the type of offset
> -displayed in `mode-line-position', a component of the default
> -`mode-line-format'."
> +  "Specification of \"percentage offset\" of window through buffer.
> +
> +This option's value is a list of the form (WIDTH TYPE) where
> +WIDTH specifies the field width to space-fill or truncate to,
> +and TYPE specifies the type of buffer offset to display in
> +`mode-line-position'.
> +

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

> +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.

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

> diff --git a/src/buffer.c b/src/buffer.c
> index 80dbd3318d..9fd39c5fb4 100644
> --- a/src/buffer.c
> +++ b/src/buffer.c
> @@ -5496,6 +5496,11 @@ A string is printed verbatim in the mode line except 
> for %-constructs:
>    %p -- print percent of buffer above top of window, or Top, Bot or All.
>    %P -- print percent of buffer above bottom of window, perhaps plus Top,
>          or print Bottom or All.
> +  %q -- print percentages of buffer above both the top and the bottom
> +        of the window, separated by -, or All.
> +  %o -- print percent of buffer above top of window vs the total buffer
> +        content excluding the text visible in the window, or Top, Bot
> +        or All.

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

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.  ;-)

>    %n -- print Narrow if appropriate.
>    %t -- visited file is text or binary (if OS supports this distinction).
>    %z -- print mnemonics of keyboard, terminal, and buffer coding systems.
> --
> 2.13.0

> -- 

> Kaushal Modi

-- 
Alan Mackenzie (Nuremberg, Germany).