fix/bug-57080-mode-line-format-docs 79e570b2b0d 5/5: Re-ordering/formatting the `mode-line-format' %-construct docs

[Phil Sainty]

branch: fix/bug-57080-mode-line-format-docs
commit 79e570b2b0dc58b81757a9b3172071545ec37634
Author: Phil Sainty <psainty@orcon.net.nz>
Commit: Phil Sainty <psainty@orcon.net.nz>

    Re-ordering/formatting the `mode-line-format' %-construct docs
    
    * src/buffer.c (mode-line-format): Reorder and reformat docstring.
    
    The original formatting dates back to the earliest commits.  It saved
    a few lines but was harder to follow.  As windows are typically taller
    now than the terminals of the time, this reformatting now makes better
    sense for readabiity.
    
    * doc/lispref/modes.texi: Order change for consistency.  Add index.
---
 doc/lispref/modes.texi |  7 ++++---
 src/buffer.c           | 31 +++++++++++++++++--------------
 2 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 3da716a3b8a..c3abba368aa 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2390,6 +2390,7 @@ specifies addition of text properties.
 
 @node %-Constructs
 @subsection @code{%}-Constructs in the Mode Line
+@cindex @code{%}-constructs in the mode line
 
   Strings used as mode line constructs can use certain
 @code{%}-constructs to substitute various kinds of data.  The
@@ -2486,6 +2487,9 @@ The mnemonics of keyboard, terminal, and buffer coding 
systems.
 @item %Z
 Like @samp{%z}, but including the end-of-line format.
 
+@item %&
+@samp{*} if the buffer is modified, and @samp{-} otherwise.
+
 @item %*
 @samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
 @samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@@ -2497,9 +2501,6 @@ Like @samp{%z}, but including the end-of-line format.
 @samp{-} otherwise.  This differs from @samp{%*} only for a modified
 read-only buffer.  @xref{Buffer Modification}.
 
-@item %&
-@samp{*} if the buffer is modified, and @samp{-} otherwise.
-
 @item %@@
 @samp{@@} if the buffer's @code{default-directory} (@pxref{File Name
 Expansion}) is on a remote machine, and @samp{-} otherwise.
diff --git a/src/buffer.c b/src/buffer.c
index 0c740775e5b..31c08cf3650 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5124,35 +5124,38 @@ A list whose car is an integer is processed by 
processing the cadr of
  negative) to the width specified by that number.
 
 A string is printed verbatim in the mode line except for %-constructs:
-  %b -- print buffer name.      %f -- print visited file name.
-  %F -- print frame name.
-  %* -- print %, * or hyphen.   %+ -- print *, % or hyphen.
-       %& is like %*, but ignore read-only-ness.
-       % means buffer is read-only and * means it is modified.
-       For a modified read-only buffer, %* gives % and %+ gives *.
-  %s -- print process status.   %l -- print the current line number.
+  %b -- print buffer name.
   %c -- print the current column number (this makes editing slower).
         Columns are numbered starting from the left margin, and the
         leftmost column is displayed as zero.
         To make the column number update correctly in all cases,
-       `column-number-mode' must be non-nil.
+        `column-number-mode' must be non-nil.
   %C -- Like %c, but the leftmost column is displayed as one.
+  %e -- print error message about full memory.
+  %f -- print visited file name.
+  %F -- print frame name.
   %i -- print the size of the buffer.
   %I -- like %i, but use k, M, G, etc., to abbreviate.
+  %l -- print the current line number.
+  %n -- print Narrow if appropriate.
   %o -- print percent of window travel through buffer, or Top, Bot or All.
   %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 percent of buffer above both the top and the bottom of the
         window, separated by ‘-’, or ‘All’.
-  %n -- print Narrow if appropriate.
+  %s -- print process status.
   %z -- print mnemonics of keyboard, terminal, and buffer coding systems.
   %Z -- like %z, but including the end-of-line format.
-  %e -- print error message about full memory.
-  %@ -- print @ or hyphen.  @ means that default-directory is on a
-        remote machine.
-  %[ -- print one [ for each recursive editing level.  %] similar.
-  %% -- print %.   %- -- print infinitely many dashes.
+  %& -- print * if the buffer is modified, otherwise hyphen.
+  %+ -- print *, % or hyphen (modified, read-only, neither).
+  %* -- print %, * or hyphen (read-only, modified, neither).
+        For a modified read-only buffer, %+ prints * and %* prints %.
+  %@ -- print @ if default-directory is on a remote machine, else hyphen.
+  %[ -- print one [ for each recursive editing level.
+  %] -- print one ] for each recursive editing level.
+  %- -- print enough dashes to fill the mode line.
+  %% -- print %.
 Decimal digits after the % specify field width to which to pad.  */);
 
   DEFVAR_PER_BUFFER ("major-mode", &BVAR (current_buffer, major_mode),