3 files changed, 62 insertions, 27 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index afd09cfb330..17126ce72b9 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2050,13 +2050,17 @@ calculations.
 
 @defun line-number-display-width &optional pixelwise
 This function returns the width used for displaying the line numbers
-in the selected window.  Optional argument @var{pixelwise}, if
-non-@code{nil}, means return the value in pixels; otherwise the value
-is returned in column units of the font defined for the
-@code{line-number} face.  If line numbers are not displayed in the
-selected window, the value is zero.  Use @code{with-selected-window}
-(@pxref{Selecting Windows}) if you need this information about another
-window.
+in the selected window.  If the optional argument @var{pixelwise} is
+the symbol @code{columns}, the return value is a float number of the
+frame's canonical columns; if @var{pixelwise} is @code{t} or any other
+non-@code{nil} value, the value is an integer and is measured in
+pixels.  If @var{pixelwise} is omitted or @code{nil}, the value is the
+integer number of columns of the font defined for the
+@code{line-number} face, and doesn't include the 2 columns used to pad
+the numbers on display.  If line numbers are not displayed in the
+selected window, the value is zero regardless of the value of
+@var{pixelwise}.  Use @code{with-selected-window} (@pxref{Selecting
+Windows}) if you need this information about another window.
 @end defun
 
 
@@ -4635,7 +4639,7 @@ as an absolute number of pixels.
 
 @smallexample
 @group
-  @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
+  @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{xwidget} | @var{form}
   @var{num}  ::= @var{integer} | @var{float} | @var{symbol}
   @var{unit} ::= in | mm | cm | width | height
 @end group
@@ -4651,22 +4655,34 @@ as an absolute number of pixels.
   The form @var{num} specifies a fraction of the default frame font
 height or width.  The form @code{(@var{num})} specifies an absolute
 number of pixels.  If @var{num} is a symbol, @var{symbol}, its
-buffer-local variable binding is used.
+buffer-local variable binding is used; that binding can be either a
+number or a cons cell of the forms shown above (including yet another
+cons cell whose @code{car} is a symbol that has a buffer-local
+binding).
 
   The @code{in}, @code{mm}, and @code{cm} units specify the number of
 pixels per inch, millimeter, and centimeter, respectively.  The
 @code{width} and @code{height} units correspond to the default width
-and height of the current face.  An image specification @code{image}
-corresponds to the width or height of the image.
+and height of the current face.  An image specification of the form
+@w{@code{(image . @var{props})}} (@pxref{Image Descriptors})
+corresponds to the width or height of the specified image.  Similarly,
+an xwidget specification of the form @w{@code{(xwidget . @var{props})}}
+stands for the width or height of the specified xwidget.
+@xref{Xwidgets}.
 
   The elements @code{left-fringe}, @code{right-fringe},
 @code{left-margin}, @code{right-margin}, @code{scroll-bar}, and
-@code{text} specify to the width of the corresponding area of the
-window.
+@code{text} specify the width of the corresponding area of the window.
+When the window displays line numbers (@pxref{Size of Displayed
+Text}), the width of the @code{text} area is decreased by the screen
+space taken by the line-number display.
 
   The @code{left}, @code{center}, and @code{right} positions can be
 used with @code{:align-to} to specify a position relative to the left
-edge, center, or right edge of the text area.
+edge, center, or right edge of the text area.  When the window
+displays line numbers, the @code{left} and the @code{center} positions
+are offset to account for the screen space taken by the line-number
+display.
 
   Any of the above window elements (except @code{text}) can also be
 used with @code{:align-to} to specify that the position is relative to
@@ -4682,13 +4698,15 @@ the left-margin, use
 
   If no specific base offset is set for alignment, it is always relative
 to the left edge of the text area.  For example, @samp{:align-to 0} in a
-header-line aligns with the first text column in the text area.
+header-line aligns with the first text column in the text area.  When
+the window displays line numbers, the text is considered to start where
+the space used for line-number display ends.
 
   A value of the form @code{(@var{num} . @var{expr})} stands for the
 product of the values of @var{num} and @var{expr}.  For example,
 @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
 @var{image})} specifies half the width (or height) of the specified
-image.
+@var{image} (which should be given by its image spec).
 
   The form @code{(+ @var{expr} ...)} adds up the value of the
 expressions.  The form @code{(- @var{expr} ...)} negates or subtracts
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 07a8b825026..ad853418ac4 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -3202,7 +3202,7 @@ a number of other ways as well.  Here we sketch a few of them:
 @item
 The semantics of maximizing and iconifying child frames is highly
 window-system dependent.  As a rule, applications should never invoke
-these operations for on frames.  By default, invoking
+these operations on child frames.  By default, invoking
 @code{iconify-frame} on a child frame will try to iconify the top-level
 frame corresponding to that child frame instead.  To obtain a different
 behavior, users may customize the option @code{iconify-child-frame}
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 59c269a3084..0cb9de9f9a8 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1486,8 +1486,8 @@ This stands for the full name of the month.
 @item %c
 This is a synonym for @samp{%x %X}.
 @item %C
-This has a locale-specific meaning.  In the default locale (named C), it
-is equivalent to @samp{%A, %B %e, %Y}.
+This stands for the century, that is, the year divided by 100,
+truncated toward zero.
 @item %d
 This stands for the day of month, zero-padded.
 @item %D
@@ -1530,8 +1530,11 @@ This stands for the calendar quarter (1--4).
 This is a synonym for @samp{%I:%M:%S %p}.
 @item %R
 This is a synonym for @samp{%H:%M}.
+@item %s
+This stands for the integer number of seconds since the epoch.
 @item %S
-This stands for the seconds (00--59).
+This stands for the second (00--59, or 00--60 on platforms
+that support leap seconds).
 @item %t
 This stands for a tab character.
 @item %T
@@ -1561,22 +1564,31 @@ This stands for the year with century.
 @item %Z
 This stands for the time zone abbreviation (e.g., @samp{EST}).
 @item %z
-This stands for the time zone numerical offset (e.g., @samp{-0500}).
+This stands for the time zone numerical offset.  The @samp{z} can be
+preceded by one, two, or three colons; if plain @samp{%z} stands for
+@samp{-0500}, then @samp{%:z} stands for @samp{-05:00}, @samp{%::z}
+stands for @samp{-05:00:00}, and @samp{%:::z} is like @samp{%::z}
+except it suppresses trailing instances of @samp{:00} so it stands for
+@samp{-05} in the same example.
+@item %%
+This stands for a single @samp{%}.
 @end table
 
+One or more flag characters can appear immediately after the @samp{%}.
+@samp{0} pads with zeros, @samp{_} pads with blanks, @samp{-}
+suppresses padding, @samp{^} upper-cases letters, and @samp{#}
+reverses the case of letters.
+
 You can also specify the field width and type of padding for any of
 these @samp{%}-sequences.  This works as in @code{printf}: you write
-the field width as digits in the middle of a @samp{%}-sequences.  If you
-start the field width with @samp{0}, it means to pad with zeros.  If you
-start the field width with @samp{_}, it means to pad with spaces.
-
+the field width as digits in a @samp{%}-sequence, after any flags.
 For example, @samp{%S} specifies the number of seconds since the minute;
 @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
 pad with spaces to 3 positions.  Plain @samp{%3S} pads with zeros,
 because that is how @samp{%S} normally pads to two positions.
 
-The characters @samp{E} and @samp{O} act as modifiers when used between
-@samp{%} and one of the letters in the table above.  @samp{E} specifies
+The characters @samp{E} and @samp{O} act as modifiers when used after
+any flags and field widths in a @samp{%}-sequence.  @samp{E} specifies
 using the current locale's alternative version of the date and time.
 In a Japanese locale, for example, @code{%Ex} might yield a date format
 based on the Japanese Emperors' reigns.  @samp{E} is allowed in
@@ -1587,6 +1599,11 @@ based on the Japanese Emperors' reigns.  @samp{E} is allowed in
 representation of numbers, instead of the ordinary decimal digits.  This
 is allowed with most letters, all the ones that output numbers.
 
+To help debug programs, unrecognized @samp{%}-sequences stand for
+themselves and are output as-is.  Programs should not rely on this
+behavior, as future versions of Emacs may recognize new
+@samp{%}-sequences as extensions.
+
 This function uses the C library function @code{strftime}
 (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference
 Manual}) to do most of the work.  In order to communicate with that