From: Eshel Yaron <me@eshelyaron.com>
Date: Fri, 7 Oct 2022 07:03:17 +0000 (+0300)
Subject: DOC: added short documentation for sweep as a SWI-Prolog package
X-Git-Tag: V8.5.18-sweep-0.6.0~8
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=bc58eb4442502e94ce70d6cb3d37980733e441f0;p=dict.git

DOC: added short documentation for sweep as a SWI-Prolog package
---

diff --git a/.gitignore b/.gitignore
index b675b2c..a9b5819 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,5 @@
 /sweep.texi
 /sweep.o
 /TODO.org
+/auto/
+/sweep.tex
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 67fc641..303b2d0 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -13,10 +13,16 @@ find_path(
 
 if(EMACS_INCLUDE_DIR)
 
-swipl_plugin(
+  swipl_plugin(
     sweep-module
     C_SOURCES sweep.c
     C_INCLUDE_DIR ${EMACS_INCLUDE_DIR}
     PL_LIBS sweep.pl)
 
+  pkg_doc(
+    sweep
+    SECTION
+    SOURCES sweep.doc)
+
+
 endif(EMACS_INCLUDE_DIR)
diff --git a/README.org b/README.org
index 898cdd6..9f0031a 100644
--- a/README.org
+++ b/README.org
@@ -68,10 +68,9 @@ The different parts of =sweep= are structured as follows:
 :CUSTOM_ID: installation
 :END:
 
-The dynamic Emacs module =sweep-module= and the Prolog helper library
-=sweep.pl= are included in the latest SWI-Prolog distribution.  For
-instructions on how to build and install SWI-Prolog, see
-[[https://www.swi-prolog.org/build/]].
+The dynamic Emacs module =sweep-module= is included in the SWI-Prolog
+distribution from version 8.5.18.  For instructions on how to build
+and install SWI-Prolog, see [[https://www.swi-prolog.org/build/]].
 
 The =sweeprolog= Elisp package is available on NonGNU ELPA, to install
 =sweeprolog= simply type =M-x package-install RET sweeprolog RET=.
diff --git a/sweep.doc b/sweep.doc
new file mode 100644
index 0000000..a4c29c1
--- /dev/null
+++ b/sweep.doc
@@ -0,0 +1,89 @@
+\documentclass[11pt]{article}
+\usepackage{times}
+\usepackage{pl}
+\usepackage{html}
+\sloppy
+\makeindex
+
+\onefile
+\htmloutput{.}					% Output directory
+\htmlmainfile{sweep}				% Main document file
+\bodycolor{white}				% Page colour
+
+\begin{document}
+
+\title{sweep: SWI-Prolog Embedded in Emacs}
+\author{Eshel Yaron\email{me@eshelyaron.com}}
+
+\maketitle
+
+\begin{abstract}
+  \texttt{sweep} is an embedding of SWI-Prolog in GNU Emacs.  It
+  provides an interface for executing Prolog queries and consuming
+  their results from Emacs Lisp.  \texttt{sweep} further builds on top
+  of this interface and on top of the standard Emacs facilities to
+  provide advanced features for developing SWI-Prolog programs in
+  Emacs.
+\end{abstract}
+
+\pagebreak
+\tableofcontents
+
+\section{Installation}
+\label{sec:sweep-installation}
+
+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}.
+
+An alternative to installing from ELPA is to get the Elisp library
+from the \texttt{sweep} Git repository:
+
+\begin{enumerate}
+\item Clone the \texttt{sweep} repository:
+  \begin{code}
+    git clone https://git.sr.ht/~eshel/sweep
+  \end{code}
+
+  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}
+
+\section{Getting started}
+\label{sec:sweep-installation}
+After installing the \texttt{sweeprolog} Elisp library, load it into
+Emacs:
+
+\begin{code}
+  (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}
+
+\printindex
+
+\end{document}