From 7e8cc54e6527f4ddc9b56bf3c5c0c42d972950b6 Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Mon, 21 Aug 2023 19:56:06 +0200
Subject: [PATCH] Refine "Getting Started" section of the manual

* README.org (Getting Started): Refine.
* sweep.doc (Installation, Getting Started): Update.
---
 README.org | 21 ++++++++++----------
 sweep.doc  | 56 ++++++++++++++++++------------------------------------
 2 files changed, 29 insertions(+), 48 deletions(-)

diff --git a/README.org b/README.org
index 2daaa77..171ea48 100644
--- a/README.org
+++ b/README.org
@@ -166,16 +166,17 @@ the variable ~sweeprolog-swipl-path~ to point to it:
   (setq sweeprolog-swipl-path "/path/to/swipl")
 #+end_src
 
-All set!  =sweeprolog= automatically loads =sweep-module= and initializes
-the embedded SWI-Prolog runtime.  For a description of the different
-features of Sweep, see the following sections of this manual.
-
-_Important note for Linux users_: prior to version 29, Emacs would load
-dynamic modules in a way that is not fully compatible with the way the
-SWI-Prolog native library, =libswipl=, loads its own native extensions.
-This may lead to Sweep failing after loading =sweep-module=.  To work
-around this issue, users running Emacs 28 or earlier on Linux can
-start Emacs with =libswipl= loaded upfront via =LD_PRELOAD=, for example:
+All set!  You can now use Sweep for Prolog development ([[#editing-prolog-code][Editing Prolog code]]) and
+for integrating Prolog into your Emacs Lisp code ([[#querying-prolog][Querying Prolog]]).  In the next
+section ([[#discovering-sweep][Discovering Sweep]]) you'll find some useful tips for learning to work
+with Sweep.
+
+_Important note for Linux users_: prior to version 29, Emacs would load dynamic
+modules in a way that is not fully compatible with the way the SWI-Prolog native
+library, =libswipl=, loads its own native extensions.  This may lead to Sweep
+failing after loading =sweep-module= ([[#high-level-architecture][High-level Architecture]]).  To work around
+this issue, users running Emacs 28 or earlier on Linux can start Emacs with
+=libswipl= loaded upfront via =LD_PRELOAD=, for example:
 
 #+begin_src sh
   LD_PRELOAD=/usr/local/lib/libswipl.so emacs
diff --git a/sweep.doc b/sweep.doc
index c5ea002..0893137 100644
--- a/sweep.doc
+++ b/sweep.doc
@@ -31,31 +31,24 @@
 
 \section{Installation}
 \label{sec:sweep-installation}
+Installing Sweep requires:
 
-The \texttt{sweeprolog} Elisp package is available on NonGNU ELPA, to
-install \texttt{sweeprolog} simply open Emacs and type \texttt{M-x
-  package-install RET sweeprolog RET}.
+\begin{itemize}
+\item Emacs 27 or later, and
+\item SWI-Prolog 8.5.18 or later.
+\end{itemize}
 
-An alternative to installing from ELPA is to get the Elisp library
-from the \texttt{sweep} Git repository:
+Sweep is available from NonGNU ELPA, to install it simply type in
+Emacs \texttt{M-x package-install RET sweeprolog RET}.
 
-\begin{enumerate}
-\item Clone the \texttt{sweep} repository:
-  \begin{code}
-    git clone https://git.sr.ht/~eshel/sweep
-  \end{code}
+Note that in Emacs prior to version 28, you need to explicitly enable
+NonGNU ELPA by adding something like the following to your Emacs
+configuration:
 
-  Or:
-
-  \begin{code}
-    git clone https://github.com/SWI-Prolog/packages-sweep sweep
-  \end{code}
-
-\item Add \texttt{sweep} to Emacs' \texttt{load-path}:
-  \begin{code}
-    (add-to-list 'load-path "/path/to/sweep")
-  \end{code}
-\end{enumerate}
+\begin{code}
+  (with-eval-after-load 'package
+    (add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")))
+\end{code}
 
 \section{Getting started}
 \label{sec:sweep-getting-started}
@@ -66,23 +59,10 @@ Emacs:
   (require 'sweeprolog)
 \end{code}
 
-All set!  \texttt{sweeprolog} automatically loads
-\texttt{sweep-module} and initializes the embedded SWI-Prolog runtime.
-For a full description of the different features of \texttt{sweep},
-see \href{https://eshelyaron.com/sweep.html}{the \texttt{sweep}
-  manual}.
-
-\textit{Important note for Linux users}: prior to version 29, Emacs
-would load dynamic modules in a way that is not fully compatible with
-the way the SWI-Prolog native library, \texttt{libswipl}, loads its
-own native extensions.  This may lead to \texttt{sweep} failing after
-loading \texttt{sweep-module}.  To work around this issue, users
-running Emacs 28 or earlier on Linux can start Emacs with
-\texttt{libswipl} loaded upfront via \texttt{LD_PRELOAD}, for example:
-
-\begin{code}
-  LD_PRELOAD=/usr/local/lib/libswipl.so emacs
-\end{code}
+All set!  You can now use Sweep for Prolog development and for
+integrating Prolog into your Emacs Lisp code.  For a full description
+of the different features of \texttt{sweep}, see
+\href{https://eshelyaron.com/sweep.html}{the Sweep manual}.
 
 \printindex
 
-- 
2.39.5