>From cf6028851f6c1099d4436a4aa297f022c4f761e8 Mon Sep 17 00:00:00 2001
From: Tim Chase <recutils@tim.thechases.com>
Date: Fri, 16 Oct 2020 15:34:12 -0500
Subject: [PATCH 3/3] Add OUTER JOIN information to recutils.texi manual source

---
 doc/recutils.texi | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/doc/recutils.texi b/doc/recutils.texi
index 65f36cb..c7cde4f 100644
--- a/doc/recutils.texi
+++ b/doc/recutils.texi
@@ -3772,6 +3772,10 @@ Dob: 3 January 1966
 Email: bert@@example.com
 Abode: 42AbbeterWay
 
+Name: Giles Wabash
+Dob: 1 April 1977
+Email: gwabash@@example.edu
+
 Name: Charles Spencer
 Dob: 4 July 1997
 Email: charlie@@example.com
@@ -3860,6 +3864,8 @@ Mandy Nebel
 Bertram Nebel
 42AbbeterWay
 
+Giles Wabash
+
 Charles Spencer
 2SerpeRise
 
@@ -3903,9 +3909,44 @@ Abode_Id: ChezGrampa
 The @code{-t} flag we have seen before.  It tells @command{recsel} that we want
 to extract records of type @code{Person}.
 @cindex join
-The @code{-j} flag is new.  It says that we want to perform a @dfn{join}.
+The @code{-j} flag is new.  It says that we want to perform an @dfn{inner join}.
 Specifically we want to join the @code{Person} records according to their
 @code{Abode} field.
+Any @code{Person} records lacking a matching @code{Abode}
+will not return a result.
+However, if instead you use the @code{-J},
+@command{recsel} will perform an @dfn{outer join},
+returning all @code{Person} entries
+augmented with any @code{Abode} information.
+
+@example
+$ recsel -t Person -j Abode acquaintances.rec
+Name: Charles Spencer
+Dob: 4 July 1997
+Email: charlie@@example.com
+Abode_Address: 2 Serpe Rise, Little Worning, SURREY
+Abode_Telephone: 09876 5432109
+Abode_Id: 2SerpeRise
+
+Name: Giles Wabash
+Dob: 1 April 1977
+Email: gwabash@@example.edu
+
+Name: Dirk Spencer
+Dob: 29 June 1945
+Email: dirk@@example.com
+Mobile: 0555 342123
+Abode_Address: 2 Serpe Rise, Little Worning, SURREY
+Abode_Telephone: 09876 5432109
+Abode_Id: 2SerpeRise
+
+Name: Ernest Wright
+Dob: 26 April 1978
+Abode_Address: 1 Wanter Rise, Greater Inncombe, BUCKS
+Abode_Id: ChezGrampa
+@end example
+
+Note that "Giles Wabash" does not have any @code{Abode} information.
 
 In the above example, @command{recsel} displays several field names which
 do not appear anywhere in the input @eg{} @code{Abode_Address}.
-- 
2.25.1