diff --git a/NEWS b/NEWS
index 8c17751..5e09773 100644
--- a/NEWS
+++ b/NEWS
@@ -47,7 +47,9 @@ Unreleased, experimental changes
     The code now defends against CRLFs in leap-seconds.list.
     (Thanks to Brian Inglis and Chris Woodbury.)
 
-  Changes to commentary
+  Changes to documentation and commentary
+
+    theory.html discusses leap seconds.  (Thanks to Steve Summit.)
 
     Nashville's newspapers dueled about the time of day in the 1950s.
     (Thanks to John Seigenthaler.)
diff --git a/theory.html b/theory.html
index 1e7df4a..0926aea 100644
--- a/theory.html
+++ b/theory.html
@@ -21,6 +21,7 @@
 	  database</a></li>
       <li><a href="#functions">Time and date functions</a></li>
       <li><a href="#stability">Interface stability</a></li>
+      <li><a href="#leapsec">Leap seconds</a></li>
       <li><a href="#calendar">Calendrical issues</a></li>
       <li><a href="#planets">Time and time zones on other planets</a></li>
     </ul>
@@ -98,8 +99,9 @@ A <code><abbr>tz</abbr></code> timezone corresponds to a ruleset that can
 have more than two changes per year, these changes need not merely
 flip back and forth between two alternatives, and the rules themselves
 can change at times.
-Whether and when a timezone changes its
-clock, and even the timezone's notional base offset from UTC, are variable.
+Whether and when a timezone changes its clock,
+and even the timezone's notional base offset from <abbr>UTC</abbr>,
+are variable.
 It does not always make sense to talk about a timezone's
 "base offset", which is not necessarily a single number.
 </p>
@@ -1072,7 +1074,8 @@ an older <code>zic</code>.
     where <code>time_t</code> is signed.
   </li>
   <li>
-    These functions can account for leap seconds, thanks to Bradley White.
+    These functions can account for leap seconds;
+    see <a href="#leapsec">Leap seconds</a> below.
   </li>
 </ul>
 
@@ -1248,6 +1251,69 @@ between now and the future time.
 </p>
 </section>
 
+<section>
+  <h2 id="leapsec">Leap seconds</h2>
+<p>
+The <code><abbr>tz</abbr></code> code and data can account for leap seconds,
+thanks to code contributed by Bradley White.
+However, the leap second support of this package is rarely used directly
+because POSIX requires leap seconds to be ignored and many
+software packages would mishandle leap seconds if they were present.
+Instead, leap seconds are more commonly handled by occasionally adjusting
+the operating system kernel clock as described in
+<a href="tz-link.html#precision">Precision timekeeping</a>,
+and this package by default installs a <samp>leapseconds</samp> file
+commonly used by
+<a href="http://www.ntp.org"><abbr title="Network Time Protocol">NTP</abbr></a>
+software that adjusts the kernel clock.
+However, kernel-clock twiddling approximates UTC only roughly,
+and systems needing more-precise UTC can use this package's leap
+second support directly.
+</p>
+
+<p>
+The directly-supported mechanism assumes that <code>time_t</code>
+counts of seconds since the POSIX epoch normally include leap seconds,
+as opposed to POSIX <code>time_t</code> counts which ignore leap seconds.
+This modified timescale is converted to <abbr>UTC</abbr>
+at the same point that time zone and DST adjustments are applied &ndash;
+namely, at calls to <code>localtime</code> and analogous functions &ndash;
+and the process is driven by leap second information
+stored in alternate versions of the <abbr>TZif</abbr> files.
+Because a leap second adjustment may be needed even
+if no time zone correction is desired,
+calls to <code>gmtime</code>-like functions
+also need to consult a <abbr>TZif</abbr> file,
+conventionally named <samp><abbr>GMT</abbr></samp>,
+to see whether leap second corrections are needed.
+To convert an application's <code>time_t</code> timestamps to or from
+POSIX <code>time_t</code> timestamps (for use when, say,
+embedding or interpreting timestamps in portable
+<a href="https://en.wikipedia.org/wiki/Tar_(computing)"><code>tar</code></a>
+files),
+the application can call the utility functions
+<code>time2posix</code> and <code>posix2time</code>
+included with this package.
+</p>
+
+<p>
+If the POSIX-compatible <abbr>TZif</abbr> file set is installed
+in a directory whose basename is <samp>zoneinfo</samp>, the
+leap-second-aware file set is by default installed in a separate
+directory <samp>zoneinfo-leaps</samp>.
+Although each process can have its own time zone by setting
+its <code>TZ</code> environment variable, there is no support for some
+processes being leap-second aware while other processes are
+POSIX-compatible; the leap-second choice is system-wide.
+So if you configure your kernel to count leap seconds, you should also
+discard <samp>zoneinfo</samp> and rename <samp>zoneinfo-leaps</samp>
+to <samp>zoneinfo</samp>.
+Alternatively, you can install just one set of <abbr>TZif</abbr> files
+in the first place; see the <code>REDO</code> variable in this package's
+<a href="https://en.wikipedia.org/wiki/Makefile">makefile</a>.
+</p>
+</section>
+
 <section>
   <h2 id="calendar">Calendrical issues</h2>
 <p>