11 files changed, 282 insertions, 165 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index dc5fa539cd1..af22f0628d1 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,9 @@
+2012-11-21  Dani Moncayo  <dmoncayo@gmail.com>
+
+        * display.texi (Auto Scrolling): Fix some inaccuracies, plus
+        clarifications (Bug#12865).
+        (Horizontal Scrolling): Clarifications.
+
 2012-11-18  Dani Moncayo  <dmoncayo@gmail.com>
 
         * mark.texi (Disabled Transient Mark): Doc fixes (Bug#12746).
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index b6ab4913f9c..876c46bdf1a 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -213,59 +213,62 @@ entire current defun onto the screen if possible.
 @node Auto Scrolling
 @section Automatic Scrolling
 
+@cindex automatic scrolling
   Emacs performs @dfn{automatic scrolling} when point moves out of the
-visible portion of the text.
+visible portion of the text.  Normally, automatic scrolling centers
+point vertically in the window, but there are several ways to alter
+this behavior.
 
 @vindex scroll-conservatively
-  Normally, this centers point vertically within the window.  However,
-if you set @code{scroll-conservatively} to a small number @var{n},
-then if you move point just a little off the screen (less than @var{n}
-lines), Emacs scrolls the text just far enough to bring point back on
-screen.  If doing so fails to make point visible, Emacs centers point
-in the window.  By default, @code{scroll-conservatively} is@tie{}0.
-If you set @code{scroll-conservatively} to a large number (larger than
-100), Emacs will never center point as result of scrolling, even if
-point moves far away from the text previously displayed in the window.
-With such a large value, Emacs will always scroll text just enough for
-bringing point into view, so point will end up at the top or bottom of
-the window, depending on the scroll direction.
+  If you set @code{scroll-conservatively} to a small number @var{n},
+then moving point just a little off the screen (no more than @var{n}
+lines) causes Emacs to scroll just enough to bring point back on
+screen; if doing so fails to make point visible, Emacs scrolls just
+far enough to center point in the window.  If you set
+@code{scroll-conservatively} to a large number (larger than 100),
+automatic scrolling never centers point, no matter how far point
+moves; Emacs always scrolls text just enough to bring point into view,
+either at the top or bottom of the window depending on the scroll
+direction.  By default, @code{scroll-conservatively} is@tie{}0, which
+means to always center point in the window.
 
 @vindex scroll-step
-  An alternative way of controlling how Emacs scrolls text is by
-customizing the variable @code{scroll-step}.  Its value determines how
-many lines to scroll the window when point moves off the screen.  If
-moving by that number of lines fails to bring point back into view,
-point is centered instead.  The default value is zero, which causes
-point to always be centered after scrolling.
-
-  Since both @code{scroll-conservatively} and @code{scroll-step}
-control automatic scrolling in contradicting ways, you should set only
-one of them.  If you customize both, the value of
-@code{scroll-conservatively} takes precedence.
+  Another way to control automatic scrolling is to customize the
+variable @code{scroll-step}.  Its value determines the number of lines
+by which to automatically scroll, when point moves off the screen.  If
+scrolling by that number of lines fails to bring point back into view,
+point is centered instead.  The default value is zero, which (by
+default) causes point to always be centered after scrolling.
 
 @cindex aggressive scrolling
 @vindex scroll-up-aggressively
 @vindex scroll-down-aggressively
-  When the window does scroll by a distance longer than
-@code{scroll-step}, you can control how aggressively it scrolls by
-setting the variables @code{scroll-up-aggressively} and
-@code{scroll-down-aggressively}.  The value of
-@code{scroll-up-aggressively} should be either @code{nil}, or a
-fraction @var{f} between 0 and 1.  A fraction specifies where on the
-screen to put point when scrolling upward, i.e.@: forward.  When point
-goes off the window end, the new start position is chosen to put point
-@var{f} parts of the window height from the bottom margin.  Thus,
-larger @var{f} means more aggressive scrolling: more new text is
-brought into view.  The default value, @code{nil}, is equivalent to
-0.5.
-
-  Likewise, @code{scroll-down-aggressively} is used for scrolling
-down, i.e.@: backward.  The value specifies how far point should be
-placed from the top margin of the window; thus, as with
-@code{scroll-up-aggressively}, a larger value is more aggressive.
-
-  These two variables are ignored if either @code{scroll-step} or
-@code{scroll-conservatively} are set to a non-zero value.
+  A third way to control automatic scrolling is to customize the
+variables @code{scroll-up-aggressively} and
+@code{scroll-down-aggressively}, which directly specify the vertical
+position of point after scrolling.  The value of
+@code{scroll-up-aggressively} should be either @code{nil} (the
+default), or a floating point number @var{f} between 0 and 1.  The
+latter means that when point goes below the bottom window edge (i.e.@:
+scrolling forward), Emacs scrolls the window so that point is @var{f}
+parts of the window height from the bottom window edge.  Thus, larger
+@var{f} means more aggressive scrolling: more new text is brought into
+view.  The default value, @code{nil}, is equivalent to 0.5.
+
+  Likewise, @code{scroll-down-aggressively} is used when point goes
+above the bottom window edge (i.e.@: scrolling backward).  The value
+specifies how far point should be from the top margin of the window
+after scrolling.  Thus, as with @code{scroll-up-aggressively}, a
+larger value is more aggressive.
+
+  Note that the variables @code{scroll-conservatively},
+@code{scroll-step}, and @code{scroll-up-aggressively} /
+@code{scroll-down-aggressively} control automatic scrolling in
+contradictory ways.  Therefore, you should pick no more than one of
+these methods to customize automatic scrolling.  In case you customize
+multiple variables, the order of priority is:
+@code{scroll-conservatively}, then @code{scroll-step}, and finally
+@code{scroll-up-aggressively} / @code{scroll-down-aggressively}.
 
 @vindex scroll-margin
   The variable @code{scroll-margin} restricts how close point can come
@@ -295,10 +298,10 @@ the cursor is left at the edge instead.)
 
 @vindex hscroll-margin
   The variable @code{hscroll-margin} controls how close point can get
-to the window's edges before automatic scrolling occurs.  It is
-measured in columns.  For example, if the value is 5, then moving
-point within 5 columns of an edge causes horizontal scrolling away
-from that edge.
+to the window's left and right edges before automatic scrolling
+occurs.  It is measured in columns.  For example, if the value is 5,
+then moving point within 5 columns of an edge causes horizontal
+scrolling away from that edge.
 
 @vindex hscroll-step
   The variable @code{hscroll-step} determines how many columns to
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a5295adc368..99e21bac469 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,25 @@
+2012-11-21  Glenn Morris  <rgm@gnu.org>
+
+        * display.texi (Attribute Functions):
+        Update for set-face-* name changes.
+        Add new "inherit" argument for face-bold-p etc.
+        Move description of this argument to a common section, like "frame".
+
+        * debugging.texi (Profiling): New section.
+        (Debugging): Mention profiling in the introduction.
+        * tips.texi (Compilation Tips): Move profiling to separate section.
+        * elisp.texi: Add Profiling to detailed menu.
+
+2012-11-21  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Display Action Functions): Fix recently added
+        example.  Suggested by Michael Heerdegen.
+
+2012-11-21  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Minor cleanup for times as lists of four integers.
+        * os.texi (Time Parsing): Time values can now be four integers.
+
 2012-11-18  Glenn Morris  <rgm@gnu.org>
 
         * loading.texi (How Programs Do Loading): Add eager macro expansion.
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 11532b19781..3439a8ae152 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -32,6 +32,9 @@ program.
 @item
 You can use the ERT package to write regression tests for the program.
 @xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}.
+
+@item
+You can profile the program to get hints about how to make it more efficient.
 @end itemize
 
   Other useful tools for debugging input and output problems are the
@@ -43,6 +46,7 @@ function (@pxref{Terminal Output}).
 * Edebug::              A source-level Emacs Lisp debugger.
 * Syntax Errors::       How to find syntax errors.
 * Test Coverage::       Ensuring you have tested all branches in your code.
+* Profiling::           Measuring the resources that your code uses.
 @end menu
 
 @node Debugger
@@ -809,3 +813,63 @@ never return.  If it ever does return, you get a run-time error.
   Edebug also has a coverage testing feature (@pxref{Coverage
 Testing}).  These features partly duplicate each other, and it would
 be cleaner to combine them.
+
+
+@node Profiling
+@section Profiling
+@cindex profiling
+@cindex measuring resource usage
+@cindex memory usage
+
+If your program is working correctly, but you want to make it run more
+quickly or efficiently, the first thing to do is @dfn{profile} your
+code so that you know how it is using resources.  If you find that one
+particular function is responsible for a significant portion of the
+runtime, you can start looking for ways to optimize that piece.
+
+Emacs has built-in support for this.  To begin profiling, type
+@kbd{M-x profiler-start}.  You can choose to profile by processor
+usage, memory usage, or both.  After doing some work, type
+@kbd{M-x profiler-report} to display a summary buffer for each
+resource that you chose to profile.  The names of the report buffers
+include the times at which the reports were generated, so you can
+generate another report later on without erasing previous results.
+When you have finished profiling, type @kbd{M-x profiler-stop} (there
+is a small overhead associated with profiling).
+
+The profiler report buffer shows, on each line, a function that was
+called, followed by how much resource (processor or memory) it used in
+absolute and percentage times since profiling started.  If a given
+line has a @samp{+} symbol at the left-hand side, you can expand that
+line by typing @key{RET}, in order to see the function(s) called by
+the higher-level function.  Pressing @key{RET} again will collapse
+back to the original state.
+
+Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function.
+Press @kbd{d} to view a function's documentation.
+You can save a profile to a file using @kbd{C-x C-w}.
+You can compare two profiles using @kbd{=}.
+
+@c FIXME reversed calltree?
+
+@cindex @file{elp.el}
+@cindex timing programs
+The @file{elp} library offers an alternative approach.  See the file
+@file{elp.el} for instructions.
+
+@cindex @file{benchmark.el}
+@cindex benchmarking
+You can check the speed of individual Emacs Lisp forms using the
+@file{benchmark} library.  See the functions @code{benchmark-run} and
+@code{benchmark-run-compiled} in @file{benchmark.el}.
+
+@c Not worth putting in the printed manual.
+@ifnottex
+@cindex --enable-profiling option of configure
+For low-level profiling of Emacs itself, you can build it using the
+@option{--enable-profiling} option of @command{configure}.  When Emacs
+exits, it generates a file @file{gmon.out} that you can examine using
+the @command{gprof} utility.  This feature is mainly useful for
+debugging Emacs.  It actually stops the Lisp-level @kbd{M-x
+profiler-@dots{}} commands described above from working.
+@end ifnottex
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 475a9550f99..5148c6ec22e 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2425,12 +2425,12 @@ This sets the @code{:stipple} attribute of @var{face} to
 This sets the @code{:font} attribute of @var{face} to @var{font}.
 @end deffn
 
-@defun set-face-bold-p face bold-p &optional frame
+@defun set-face-bold face bold-p &optional frame
 This sets the @code{:weight} attribute of @var{face} to @var{normal}
 if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
 @end defun
 
-@defun set-face-italic-p face italic-p &optional frame
+@defun set-face-italic face italic-p &optional frame
 This sets the @code{:slant} attribute of @var{face} to @var{normal} if
 @var{italic-p} is @code{nil}, and to @var{italic} otherwise.
 @end defun
@@ -2440,7 +2440,7 @@ This sets the @code{:underline} attribute of @var{face} to
 @var{underline}.
 @end defun
 
-@defun set-face-inverse-video-p face inverse-video-p &optional frame
+@defun set-face-inverse-video face inverse-video-p &optional frame
 This sets the @code{:inverse-video} attribute of @var{face} to
 @var{inverse-video-p}.
 @end defun
@@ -2453,59 +2453,48 @@ This swaps the foreground and background colors of face @var{face}.
 don't specify @var{frame}, they refer to the selected frame; @code{t}
 refers to the default data for new frames.  They return the symbol
 @code{unspecified} if the face doesn't define any value for that
-attribute.
+attribute.  If @var{inherit} is @code{nil}, only an attribute directly
+defined by the face is returned.  If @var{inherit} is non-@code{nil},
+any faces specified by its @code{:inherit} attribute are considered as
+well, and if @var{inherit} is a face or a list of faces, then they are
+also considered, until a specified attribute is found.  To ensure that
+the return value is always specified, use a value of @code{default} for
+@var{inherit}.
+
+@defun face-font face &optional frame
+This function returns the name of the font of face @var{face}.
+@end defun
 
 @defun face-foreground face &optional frame inherit
 @defunx face-background face &optional frame inherit
 These functions return the foreground color (or background color,
 respectively) of face @var{face}, as a string.
-
-If @var{inherit} is @code{nil}, only a color directly defined by the face is
-returned.  If @var{inherit} is non-@code{nil}, any faces specified by its
-@code{:inherit} attribute are considered as well, and if @var{inherit}
-is a face or a list of faces, then they are also considered, until a
-specified color is found.  To ensure that the return value is always
-specified, use a value of @code{default} for @var{inherit}.
 @end defun
 
 @defun face-stipple face &optional frame inherit
 This function returns the name of the background stipple pattern of face
 @var{face}, or @code{nil} if it doesn't have one.
-
-If @var{inherit} is @code{nil}, only a stipple directly defined by the
-face is returned.  If @var{inherit} is non-@code{nil}, any faces
-specified by its @code{:inherit} attribute are considered as well, and
-if @var{inherit} is a face or a list of faces, then they are also
-considered, until a specified stipple is found.  To ensure that the
-return value is always specified, use a value of @code{default} for
-@var{inherit}.
-@end defun
-
-@defun face-font face &optional frame
-This function returns the name of the font of face @var{face}.
 @end defun
 
-@defun face-bold-p face &optional frame
+@defun face-bold-p face &optional frame inherit
 This function returns a non-@code{nil} value if the @code{:weight}
 attribute of @var{face} is bolder than normal (i.e., one of
 @code{semi-bold}, @code{bold}, @code{extra-bold}, or
 @code{ultra-bold}).  Otherwise, it returns @code{nil}.
 @end defun
 
-@defun face-italic-p face &optional frame
+@defun face-italic-p face &optional frame inherit
 This function returns a non-@code{nil} value if the @code{:slant}
 attribute of @var{face} is @code{italic} or @code{oblique}, and
 @code{nil} otherwise.
 @end defun
 
-@c Note the weasel words.  A face that inherits from an underlined
-@c face but does not specify :underline will return nil.
-@defun face-underline-p face &optional frame
+@defun face-underline-p face &optional frame inherit
 This function returns non-@code{nil} if face @var{face} specifies
 a non-@code{nil} @code{:underline} attribute.
 @end defun
 
-@defun face-inverse-video-p face &optional frame
+@defun face-inverse-video-p face &optional frame inherit
 This function returns non-@code{nil} if face @var{face} specifies
 a non-@code{nil} @code{:inverse-video} attribute.
 @end defun
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index a70558bf09f..cb00b5e9889 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -617,6 +617,7 @@ Debugging Lisp Programs
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
+* Profiling::               Measuring the resources that your code uses.
 
 The Lisp Debugger
 
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 2f06e207fc4..7552aaccc53 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1373,8 +1373,8 @@ on others, years as early as 1901 do work.
 @node Time Parsing
 @section Parsing and Formatting Times
 
-  These functions convert time values (lists of two or three integers)
-to text in a string, and vice versa.
+  These functions convert time values to text in a string, and vice versa.
+Time values are lists of two to four integers (@pxref{Time of Day}).
 
 @defun date-to-time string
 This function parses the time-string @var{string} and returns the
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4336baa128f..bba416d5614 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -460,18 +460,8 @@ Lisp programs.
 
 @itemize @bullet
 @item
-@cindex profiling
-@cindex timing programs
-@cindex @file{elp.el}
-Profile your program with the @file{elp} library.  See the file
-@file{elp.el} for instructions.
-
-@item
-@cindex @file{benchmark.el}
-@cindex benchmarking
-Check the speed of individual Emacs Lisp forms using the
-@file{benchmark} library.  See the functions @code{benchmark-run} and
-@code{benchmark-run-compiled} in @file{benchmark.el}.
+Profile your program, to find out where the time is being spent.
+@xref{Profiling}.
 
 @item
 Use iteration rather than recursion whenever possible.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index b8581b1cc62..e515b24db93 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2038,7 +2038,8 @@ Evaluating the form above will cause @code{display-buffer} to proceed as
 follows: If `*foo*' already appears on a visible or iconified frame, it
 will reuse its window.  Otherwise, it will try to pop up a new window
 or, if that is impossible, a new frame.  If all these steps fail, it
-will try to use some existing window.
+will proceed using whatever @code{display-buffer-base-action} and
+@code{display-buffer-fallback-action} prescribe.
 
    Furthermore, @code{display-buffer} will try to adjust a reused window
 (provided `*foo*' was put by @code{display-buffer} there before) or a
diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 39931f3a779..6be52213a4a 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,7 +1,19 @@
+2012-11-22  Paul Eggert  <eggert@cs.ucla.edu>
+
+        * calc.texi: Fix TeX issues with capitals followed by ".", "?", "!".
+        (Date Forms): Correct off-by-one error in explanation of
+        Julian day numbers.  Give Gregorian equivalent of its origin.
+
+2012-11-22  Jay Belanger  <jay.p.belanger@gmail.com>
+
+        * doc/misc/calc.texi (Date Forms): Mention the customizable
+        Gregorian-Julian switch.
+        (Customizing Calc): Mention the variable `calc-gregorian-switch'.
+
 2012-11-17  Paul Eggert  <eggert@cs.ucla.edu>
 
-        Calc now uses the Gregorian calendar for all dates,
-        and uses January 1, 1 AD as its day number 1.
+        Calc now uses the Gregorian calendar for all dates (Bug#12633).
+        It also uses January 1, 1 AD as its day number 1.
         * calc.texi (Date Forms): Document this.
 
 2012-11-16  Glenn Morris  <rgm@gnu.org>
diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index 6daceb4d41a..0ce1efbff58 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -1186,7 +1186,7 @@ since the large integer arithmetic was there anyway it seemed only
 fair to give the user direct access to it, which in turn made it
 practical to support fractions as well as floats. All these features
 inspired me to look around for other data types that might be worth
-having. 
+having.
 
 Around this time, my friend Rick Koshi showed me his nifty new HP-28
 calculator.  It allowed the user to manipulate formulas as well as
@@ -4461,7 +4461,7 @@ date by one or several months.  @xref{Date Arithmetic}, for more.
 Friday the 13th?  @xref{Types Answer 5, 5}. (@bullet{})
 
 (@bullet{}) @strong{Exercise 6.}  How many leap years will there be
-between now and the year 10001 A.D.?  @xref{Types Answer 6, 6}. (@bullet{})
+between now and the year 10001 AD@?  @xref{Types Answer 6, 6}. (@bullet{})
 
 @cindex Slope and angle of a line
 @cindex Angle and slope of a line
@@ -5693,7 +5693,7 @@ on the stack, we want to be able to type @kbd{*} and get the result
 rearranged.  (This one is rather tricky; the solution at the end of
 this chapter uses 6 rewrite rules.  Hint:  The @samp{constant(x)}
 condition tests whether @samp{x} is a number.)  @xref{Rewrites Answer
-6, 6}. (@bullet{}) 
+6, 6}. (@bullet{})
 
 Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}.
 What happens?  (Be sure to remove this rule afterward, or you might get
@@ -8697,7 +8697,7 @@ Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}.
 @smallexample
 @group
      ___
-1:  V 2 
+1:  V 2
     .
 
   a r a*(b+c) := a*b + a*c
@@ -8897,7 +8897,7 @@ Note that this rule does not mention @samp{O} at all, so it will
 apply to any product-of-sum it encounters---this rule may surprise
 you if you put it into @code{EvalRules}!
 
-In the second rule, the sum of two O's is changed to the smaller O.
+In the second rule, the sum of two O's is changed to the smaller O@.
 The optional constant coefficients are there mostly so that
 @samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled
 as well as @samp{O(x^2) + O(x^3)}.
@@ -10987,10 +10987,10 @@ Input is flexible; date forms can be entered in any of the usual
 notations for dates and times.  @xref{Date Formats}.
 
 Date forms are stored internally as numbers, specifically the number
-of days since midnight on the morning of January 1 of the year 1 AD.
+of days since midnight on the morning of December 31 of the year 1 BC@.
 If the internal number is an integer, the form represents a date only;
 if the internal number is a fraction or float, the form represents
-a date and time.  For example, @samp{<6:00am Wed Jan 9, 1991>}
+a date and time.  For example, @samp{<6:00am Thu Jan 10, 1991>}
 is represented by the number 726842.25.  The standard precision of
 12 decimal digits is enough to ensure that a (reasonable) date and
 time can be stored without roundoff error.
@@ -11010,55 +11010,70 @@ You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u}
 of a date form.  @xref{Packing and Unpacking}.
 
 Date forms can go arbitrarily far into the future or past.  Negative
-year numbers represent years BC.  There is no ``year 0''; the day
+year numbers represent years BC@.  There is no ``year 0''; the day
 before @samp{<Mon Jan 1, +1>} is @samp{<Sun Dec 31, -1>}.  These are
 days 1 and 0 respectively in Calc's internal numbering scheme.  The
 Gregorian calendar is used for all dates, including dates before the
-Gregorian calendar was invented.  Thus Calc's use of the day number
-@mathit{-10000} to represent August 15, 28 BC should be taken with a
-grain of salt.
+Gregorian calendar was invented (although that can be configured; see
+below).  Thus Calc's use of the day number @mathit{-10000} to
+represent August 15, 28 BC should be taken with a grain of salt.
 
 @cindex Julian calendar
 @cindex Gregorian calendar
 Some historical background:  The Julian calendar was created by
 Julius Caesar in the year 46 BC as an attempt to fix the confusion
 caused by the irregular Roman calendar that was used before that time.
-The Julian calendar introduced an extra day in
-all years divisible by four.  After some initial confusion, the
-calendar was adopted around the year we call 8 AD, although the years were
-numbered differently and did not necessarily begin on January 1.  Some centuries
-later it became apparent that the Julian year of 365.25 days was
-itself not quite right.  In 1582 Pope Gregory XIII introduced the
-Gregorian calendar, which added the new rule that years divisible
-by 100, but not by 400, were not to be considered leap years
-despite being divisible by four.  Many countries delayed adoption
-of the Gregorian calendar because of religious differences, and
-used differing year numbers and start-of-year for other reasons;
-for example, in early 1752 England changed the start of its year from
-March 25 to January 1, and in September it switched to the Gregorian
-calendar: in England, the day after December 31, 1750 was January 1,
-1750 and the day after March 24, 1750 was March 25, 1751, but the day
-after December 31, 1751 was January 1, 1752 and the day after
-September 2, 1752 was September 14, 1752.  To take another example,
-Russia switched both year numbering and start-of-year in 1700, but did
-not adopt the Gregorian calendar until 1918.  Calc's reckoning
-therefore matches English practice starting in 1752 and Russian
-practice starting in 1918, but disagrees with earlier dates in both
-countries.
-
-Today's timekeepers introduce an occasional ``leap second'' as
-well, but Calc does not take these minor effects into account.
-(If it did, it would have to report a non-integer number of days
-between, say, @samp{<12:00am Mon Jan 1, 1900>} and
+The Julian calendar introduced an extra day in all years divisible by
+four.  After some initial confusion, the calendar was adopted around
+the year we call 8 AD@.  Some centuries later it became
+apparent that the Julian year of 365.25 days was itself not quite
+right.  In 1582 Pope Gregory XIII introduced the Gregorian calendar,
+which added the new rule that years divisible by 100, but not by 400,
+were not to be considered leap years despite being divisible by four.
+Many countries delayed adoption of the Gregorian calendar
+because of religious differences.  For example, Great Britain and the
+British colonies switched to the Gregorian calendar in September
+1752, when the Julian calendar was eleven days behind the
+Gregorian calendar.  That year in Britain, the day after September 2
+was September 14.  To take another example, Russia did not adopt the
+Gregorian calendar until 1918, and that year in Russia the day after
+January 31 was February 14.  Calc's reckoning therefore matches English
+practice starting in 1752 and Russian practice starting in 1918, but
+disagrees with earlier dates in both countries.
+
+When the Julian calendar was introduced, it had January 1 as the first
+day of the year.  By the Middle Ages, many European countries
+had changed the beginning of a new year to a different date, often to
+a religious festival.  Almost all countries reverted to using January 1
+as the beginning of the year by the time they adopted the Gregorian
+calendar.
+
+Some calendars attempt to mimic the historical situation by using the
+Gregorian calendar for recent dates and the Julian calendar for older
+dates. The @code{cal} program in most Unix implementations does this,
+for example. While January 1 wasn't always the beginning of a calendar
+year, these hybrid calendars still use January 1 as the beginning of
+the year even for older dates.   The customizable variable
+@code{calc-gregorian-switch} (@pxref{Customizing Calc}) can be set to
+have Calc's date forms switch from the Julian to Gregorian calendar at
+any specified date.
+
+Today's timekeepers introduce an occasional ``leap second''.
+These do not occur regularly and Calc does not take these minor
+effects into account.  (If it did, it would have to report a
+non-integer number of days between, say,
+@samp{<12:00am Mon Jan 1, 1900>} and
 @samp{<12:00am Sat Jan 1, 2000>}.)
 
 @cindex Julian day counting
 Another day counting system in common use is, confusingly, also called
-``Julian.''  The Julian day number is the numbers of days since
-12:00 noon (GMT) on Jan 1, 4713 BC, which in Calc's scheme (in GMT)
-is @mathit{-1721423.5} (recall that Calc starts at midnight instead
-of noon).  Thus to convert a Calc date code obtained by unpacking a
-date form into a Julian day number, simply add 1721423.5 after
+``Julian.''  Julian days go from noon to noon.  The Julian day number
+is the numbers of days since 12:00 noon (GMT) on November 24, 4714 BC
+in the Gregorian calendar (i.e., January 1, 4713 BC in the Julian
+calendar).  In Calc's scheme (in GMT) the Julian day origin is
+@mathit{-1721422.5}, because Calc starts at midnight instead of noon.
+Thus to convert a Calc date code obtained by unpacking a
+date form into a Julian day number, simply add 1721422.5 after
 compensating for the time zone difference.  The built-in @kbd{t J}
 command performs this conversion for you.
 
@@ -11090,7 +11105,7 @@ the Julian cycle as an astronomical dating system; this idea was taken
 up by other astronomers.  (At the time, noon was the start of the
 astronomical day.  Herschel originally suggested counting the days
 since Jan 1, 4713 BC at noon Alexandria time; this was later amended to
-noon GMT.)  Julian day numbering is largely used in astronomy.
+noon GMT@.)  Julian day numbering is largely used in astronomy.
 
 @cindex Unix time format
 The Unix operating system measures time as an integer number of
@@ -12638,7 +12653,7 @@ are simplified with their unit definitions in mind.
 A common technique is to set the simplification mode down to the lowest
 amount of simplification you will allow to be applied automatically, then
 use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to
-perform higher types of simplifications on demand.  
+perform higher types of simplifications on demand.
 @node Declarations, Display Modes, Simplification Modes, Mode Settings
 @section Declarations
 
@@ -12989,7 +13004,7 @@ The @code{dneg} function checks for negative reals.  The @code{dnonneg}
 function checks for nonnegative reals, i.e., reals greater than or
 equal to zero.  Note that Calc's algebraic simplifications, which are
 effectively applied to all conditions in rewrite rules, can simplify
-an expression like @expr{x > 0} to 1 or 0 using @code{dpos}.  
+an expression like @expr{x > 0} to 1 or 0 using @code{dpos}.
 So the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg}
 are rarely necessary.
 
@@ -13424,7 +13439,7 @@ the time part.  The punctuation characters (including spaces) must
 match exactly; letter fields must correspond to suitable text in
 the input.  If this doesn't work, Calc checks if the input is a
 simple number; if so, the number is interpreted as a number of days
-since Jan 1, 1 AD.  Otherwise, Calc tries a much more relaxed and
+since Jan 1, 1 AD@.  Otherwise, Calc tries a much more relaxed and
 flexible algorithm which is described in the next section.
 
 Weekday names are ignored during reading.
@@ -14653,7 +14668,7 @@ Subscripts use double square brackets: @samp{a[[i]]}.
 The @kbd{d W} (@code{calc-maple-language}) command selects the
 conventions of Maple.
 
-Maple's language is much like C.  Underscores are allowed in symbol
+Maple's language is much like C@.  Underscores are allowed in symbol
 names; square brackets are used for subscripts; explicit @samp{*}s for
 multiplications are required.  Use either @samp{^} or @samp{**} to
 denote powers.
@@ -16714,7 +16729,7 @@ number (i.e., pervasively).
 If the simplification mode is set below basic simplification, it is raised
 for the purposes of this command.  Thus, @kbd{c c} applies the basic
 simplifications even if their automatic application is disabled.
-@xref{Simplification Modes}. 
+@xref{Simplification Modes}.
 
 @cindex Roundoff errors, correcting
 A numeric prefix argument to @kbd{c c} sets the floating-point precision
@@ -16791,7 +16806,7 @@ additional argument from the top of the stack.
 @pindex calc-date
 @tindex date
 The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a
-date form into a number, measured in days since Jan 1, 1 AD.  The
+date form into a number, measured in days since Jan 1, 1 AD@.  The
 result will be an integer if @var{date} is a pure date form, or a
 fraction or float if @var{date} is a date/time form.  Or, if its
 argument is a number, it converts this number into a date form.
@@ -16829,7 +16844,7 @@ The last two arguments default to zero if omitted.
 @cindex Julian day counts, conversions
 The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts
 a date form into a Julian day count, which is the number of days
-since noon (GMT) on Jan 1, 4713 BC.  A pure date is converted to an
+since noon (GMT) on Jan 1, 4713 BC@.  A pure date is converted to an
 integer Julian count representing noon of that day.  A date/time form
 is converted to an exact floating-point Julian count, adjusted to
 interpret the date form in the current time zone but the Julian
@@ -18975,7 +18990,7 @@ modulo operation as numbers 39 and below.)  If @var{m} is a power of
 ten, however, the numbers should be completely unbiased.
 
 The Gaussian random numbers generated by @samp{random(0.0)} use the
-``polar'' method described in Knuth section 3.4.1C.  This method
+``polar'' method described in Knuth section 3.4.1C@.  This method
 generates a pair of Gaussian random numbers at a time, so only every
 other call to @samp{random(0.0)} will require significant calculations.
 
@@ -22175,7 +22190,7 @@ Use @kbd{a v} if you want the variables to ignore their stored values.
 If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies
 using Calc's algebraic simplifications; @pxref{Simplifying Formulas}.
 If you give a numeric prefix of 3 or more, it uses Extended
-Simplification mode (@kbd{a e}). 
+Simplification mode (@kbd{a e}).
 
 If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3},
 it simplifies in the corresponding mode but only works on the top-level
@@ -22248,7 +22263,7 @@ If inequalities with opposite direction (e.g., @samp{<} and @samp{>})
 are mapped, the direction of the second inequality is reversed to
 match the first:  Using @kbd{a M +} on @samp{a < b} and @samp{a > 2}
 reverses the latter to get @samp{2 < a}, which then allows the
-combination @samp{a + 2 < b + a}, which the algebraic simplifications 
+combination @samp{a + 2 < b + a}, which the algebraic simplifications
 can reduce to @samp{2 < b}.
 
 Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate
@@ -22395,7 +22410,7 @@ common special case of regular arithmetic commands like @kbd{+} and
 @kbd{Q} [@code{sqrt}], the arguments are simply popped from the stack
 and collected into a suitable function call, which is then simplified
 (the arguments being simplified first as part of the process, as
-described above). 
+described above).
 
 Even the basic set of simplifications are too numerous to describe
 completely here, but this section will describe the ones that apply to the
@@ -22701,7 +22716,7 @@ the algebraic simplification mode, which is the default simplification
 mode.  If you have switched to a different simplification mode, you can
 switch back with the @kbd{m A} command. Even in other simplification
 modes, the @kbd{a s} command will use these algebraic simplifications to
-simplify the formula. 
+simplify the formula.
 
 There is a variable, @code{AlgSimpRules}, in which you can put rewrites
 to be applied. Its use is analogous to @code{EvalRules},
@@ -22738,7 +22753,7 @@ This allows easier comparison of products; for example, the basic
 simplifications will not change @expr{x y + y x} to @expr{2 x y},
 but the algebraic simplifications; it first rewrites the sum to
 @expr{x y + x y} which can then be recognized as a sum of identical
-terms. 
+terms.
 
 The canonical ordering used to sort terms of products has the
 property that real-valued numbers, interval forms and infinities
@@ -22781,10 +22796,10 @@ factor in the numerator and denominator, it is canceled out;
 for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}.
 
 Non-constant common factors are not found even by algebraic
-simplifications.  To cancel the factor @expr{a} in 
+simplifications.  To cancel the factor @expr{a} in
 @expr{(a x + a) / a^2} you could first use @kbd{j M} on the product
 @expr{a x} to Merge the numerator to @expr{a (1+x)}, which can then be
-simplified successfully. 
+simplified successfully.
 
 @tex
 \bigskip
@@ -22937,7 +22952,7 @@ as is @expr{x^2 >= 0} if @expr{x} is known to be real.
 @tindex esimplify
 Calc is capable of performing some simplifications which may sometimes
 be desired but which are not ``safe'' in all cases.  The @kbd{a e}
-(@code{calc-simplify-extended}) [@code{esimplify}] command 
+(@code{calc-simplify-extended}) [@code{esimplify}] command
 applies the algebraic simplifications as well as these extended, or
 ``unsafe'', simplifications.  Use this only if you know the values in
 your formula lie in the restricted ranges for which these
@@ -23581,10 +23596,10 @@ forever!)
 @vindex IntegSimpRules
 Another set of rules, stored in @code{IntegSimpRules}, are applied
 every time the integrator uses algebraic simplifications to simplify an
-intermediate result.  For example, putting the rule 
+intermediate result.  For example, putting the rule
 @samp{twice(x) := 2 x} into  @code{IntegSimpRules} would tell Calc to
 convert the @code{twice} function into a form it knows whenever
-integration is attempted. 
+integration is attempted.
 
 One more way to influence the integrator is to define a function with
 the @kbd{Z F} command (@pxref{Algebraic Definitions}).  Calc's
@@ -26749,7 +26764,7 @@ meta-variable @expr{v}.  As usual, if this meta-variable has already
 been matched to something else the two values must be equal; if the
 meta-variable is new then it is bound to the result of the expression.
 This variable can then appear in later conditions, and on the righthand
-side of the rule. 
+side of the rule.
 In fact, @expr{v} may be any pattern in which case the result of
 evaluating @expr{x} is matched to that pattern, binding any
 meta-variables that appear in that pattern.  Note that @code{let}
@@ -27503,7 +27518,7 @@ but only when algebraic simplifications are used to simplify the
 formula.  The variable @code{AlgSimpRules} holds rules for this purpose.
 The @kbd{a s} command will apply @code{EvalRules} and
 @code{AlgSimpRules} to the formula, as well as all of its built-in
-simplifications. 
+simplifications.
 
 Most of the special limitations for @code{EvalRules} don't apply to
 @code{AlgSimpRules}.  Calc simply does an @kbd{a r AlgSimpRules}
@@ -27511,7 +27526,7 @@ command with an infinite repeat count as the first step of algebraic
 simplifications. It then applies its own built-in simplifications
 throughout the formula, and then repeats these two steps (along with
 applying the default simplifications) until no further changes are
-possible. 
+possible.
 
 @cindex @code{ExtSimpRules} variable
 @cindex @code{UnitSimpRules} variable
@@ -28946,9 +28961,9 @@ to select the lefthand side, execute your commands, then type
 All current modes apply when an @samp{=>} operator is computed,
 including the current simplification mode.  Recall that the
 formula @samp{arcsin(sin(x))} will not be handled by Calc's algebraic
-simplifications, but Calc's unsafe simplifications will reduce it to 
+simplifications, but Calc's unsafe simplifications will reduce it to
 @samp{x}.   If you enter @samp{arcsin(sin(x)) =>} normally, the result
-will be @samp{arcsin(sin(x)) => arcsin(sin(x))}.  If you change to 
+will be @samp{arcsin(sin(x)) => arcsin(sin(x))}.  If you change to
 Extended Simplification mode, the result will be
 @samp{arcsin(sin(x)) => x}.  However, just pressing @kbd{a e}
 once will have no effect on @samp{arcsin(sin(x)) => arcsin(sin(x))},
@@ -29566,7 +29581,7 @@ plot on any text-only printer.
 @kindex g O
 @pindex calc-graph-output
 The @kbd{g O} (@code{calc-graph-output}) command sets the name of the
-output file used by GNUPLOT.  For some devices, notably @code{x11} and
+output file used by GNUPLOT@.  For some devices, notably @code{x11} and
 @code{windows}, there is no output file and this information is not
 used.  Many other ``devices'' are really file formats like
 @code{postscript}; in these cases the output in the desired format
@@ -29638,7 +29653,7 @@ window in the upper-left corner of the screen.  This command has no
 effect if the current device is @code{windows}.
 
 The buffer called @samp{*Gnuplot Trail*} holds a transcript of the
-session with GNUPLOT.  This shows the commands Calc has ``typed'' to
+session with GNUPLOT@.  This shows the commands Calc has ``typed'' to
 GNUPLOT and the responses it has received.  Calc tries to notice when an
 error message has appeared here and display the buffer for you when
 this happens.  You can check this buffer yourself if you suspect
@@ -33249,7 +33264,7 @@ in the range @samp{[0 ..@: 60)}.
 
 Date forms are stored as @samp{(date @var{n})}, where @var{n} is
 a real number that counts days since midnight on the morning of
-January 1, 1 AD.  If @var{n} is an integer, this is a pure date
+January 1, 1 AD@.  If @var{n} is an integer, this is a pure date
 form.  If @var{n} is a fraction or float, this is a date/time form.
 
 Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a
@@ -33757,7 +33772,7 @@ objects into a definite, consistent order.  The @code{beforep}
 function is used by the @kbd{V S} vector-sorting command, and also
 by Calc's algebraic simplifications to put the terms of a product into
 canonical order: This allows @samp{x y + y x} to be simplified easily to
-@samp{2 x y}. 
+@samp{2 x y}.
 @end defun
 
 @defun equal x y
@@ -35590,6 +35605,20 @@ number of undo steps that will be preserved; if
 be preserved.  The default value of @code{calc-undo-length} is @expr{100}.
 @end defvar
 
+@defvar calc-gregorian-switch
+See @ref{Date Forms}.@*
+The variable @code{calc-gregorian-switch} is either a list of integers
+@code{(@var{YEAR} @var{MONTH} @var{DAY})} or @code{nil}.
+If it is @code{nil}, then Calc's date forms always represent Gregorian dates.
+Otherwise, @code{calc-gregorian-switch} represents the date that the
+calendar switches from Julian dates to Gregorian dates;
+@code{(@var{YEAR} @var{MONTH} @var{DAY})} will be the first Gregorian
+date.  The customization buffer will offer several standard dates to
+choose from, or the user can enter their own date.
+
+The default value of @code{calc-gregorian-switch} is @code{nil}.
+@end defvar
+
 @node Reporting Bugs, Summary, Customizing Calc, Top
 @appendix Reporting Bugs