From ec03f4121cec6cf885bf40d9dfb53b8368251e99 Mon Sep 17 00:00:00 2001
From: Simon Riggs <simon@2ndQuadrant.com>
Date: Mon, 5 Sep 2016 09:47:49 +0100
Subject: [PATCH] Document LSN acronym in WAL Internals

We previously didn't mention what an LSN actually was.

Simon Riggs and Michael Paquier
---
 doc/src/sgml/acronyms.sgml | 10 ++++++++++
 doc/src/sgml/wal.sgml      | 16 ++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index 38f111ef9d9..bf2273fa8a0 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -380,6 +380,16 @@
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term><acronym>LSN</acronym></term>
+    <listitem>
+     <para>
+      Log Sequence Number, see <link linkend="datatype-pg-lsn"><type>pg_lsn</></link>
+      and <link linkend="wal-internals">WAL Internals</link>.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><acronym>MSVC</acronym></term>
     <listitem>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index 503ea8a2a7e..9ae65477218 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -724,6 +724,10 @@
  <sect1 id="wal-internals">
   <title>WAL Internals</title>
 
+  <indexterm zone="wal-internals">
+   <primary>LSN</primary>
+  </indexterm>
+
   <para>
    <acronym>WAL</acronym> is automatically enabled; no action is
    required from the administrator except ensuring that the
@@ -732,6 +736,18 @@
    linkend="wal-configuration">).
   </para>
 
+  <para>
+   <acronym>WAL</acronym> records are appended to the <acronym>WAL</acronym>
+   logs as each new record is written. The insert position is described by
+   a Log Sequence Number (<acronym>LSN</acronym>) that is a byte offset into
+   the logs, increasing monotonically with each new record.
+   <acronym>LSN</acronym> values are returned as the datatype
+   <link linkend="datatype-pg-lsn"><type>pg_lsn</></link>. Values can be
+   compared to calculate the volume of <acronym>WAL</acronym> data that
+   separates them, so they are used to measure the progress of replication
+   and recovery.
+  </para>
+
   <para>
    <acronym>WAL</acronym> logs are stored in the directory
    <filename>pg_xlog</filename> under the data directory, as a set of
-- 
2.39.5