From a2dd171343c5715e4d424092d61061712ac8c55f Mon Sep 17 00:00:00 2001
From: Kenny Levinsen <kl@kl.wtf>
Date: Wed, 1 Apr 2020 18:40:53 +0200
Subject: [PATCH] man: Clarify initial/default sessions

---
 man/greetd-1.scd | 15 ++++++++++-----
 man/greetd-5.scd | 32 +++++++++++++++++++++++++++++---
 2 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/man/greetd-1.scd b/man/greetd-1.scd
index 12276bf..26ee6cb 100644
--- a/man/greetd-1.scd
+++ b/man/greetd-1.scd
@@ -2,7 +2,7 @@ greetd(1)
 
 # NAME
 
-greetd - A greeter daemon / login manager daemon
+greetd - A login manager daemon
 
 # SYNOPSIS
 
@@ -29,9 +29,14 @@ greeter process like agreety(1) to handle that aspect.
 
 greetd operates on *sessions*. A greeter creates a session, attempts to
 authenticate a user in it, and finally, uses it start an arbitrary
-application. When greetd is launched, as no session is pending start yet,
-greetd starts the configured *greeter*, which is simply a pre-configured
-auto-login session.
+application.
+
+There are two types of preconfigured sessions: The default session, also known
+as the *greeter*, and the optional initial session, serving the purpose of
+"auto-login". The initial session, if configured, is started once when greetd
+launches. The default session is started on launch if an initial session is
+not configured, and started again whenever no session is running, such as when
+the user logs out.
 
 An IPC socket is exposed to this greeter, as reported by *GREETD_SOCK*. The
 greeter can use this to create, authenticate and finally start a session. For
@@ -42,7 +47,7 @@ greetd will start the new session. Once this session terminates, the process
 starts over.
 
 greetd makes no assumptions about any sessions, including the greeter. They
-can be text-based, running in the active console, or full on graphical
+can be text-based, running in the active console, or full-on graphical
 environments.
 
 # CONFIGURATION
diff --git a/man/greetd-5.scd b/man/greetd-5.scd
index 6bfce31..4a0c9c6 100644
--- a/man/greetd-5.scd
+++ b/man/greetd-5.scd
@@ -10,6 +10,16 @@ greetd uses a simple TOML configuration file to define its behavior.
 
 # CONFIGURATION
 
+The configuration is divided into *sections*. Sections are delimited like so:
+
+```
+[section_name]
+config_key = value
+```
+
+Configuration keys can be integer literals, or quote-delimited strings. The
+configuration sections are described below.
+
 ## terminal
 
 This section contains terminal configuration.
@@ -29,7 +39,7 @@ This section contains terminal configuration.
 
 ## default_session
 
-This section describes the default session, also referred to as the "greeter".
+This section describes the default session, also referred to as the *greeter*.
 
 *command* = command-line
 	The command-line to run to start the default session, e.g. "agreety -c sway".
@@ -55,9 +65,11 @@ This optional section describes the initial session, commonly referred to as
 *user* = user
 	The user to use for running the initial session.
 
-# EXAMPLE
+# EXAMPLES
 
-```toml
+## Regular setup with agreety and sway
+
+```
 [terminal]
 vt = 1
 
@@ -65,6 +77,20 @@ vt = 1
 command = "agreety -c sway"
 ```
 
+## Auto-login
+
+```
+[terminal]
+vt = 1
+
+[default_session]
+command = "agreety -c sway"
+
+[initial_session]
+command = "sway"
+user = "john"
+```
+
 # AUTHORS
 
 Maintained by Kenny Levinsen <contact@kl.wtf>. For more information about