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

diff --git a/.gitignore b/.gitignore
index b675b2c76217290f0893a808a69ff298768fb3f5..a9b5819b7fc15f2e40c957005fc8ff53599385a9 100644 (file)
--- 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 67fc64143b0320efdffe3715eb9d8cf2fbd153f5..303b2d05d342fa1e8ce73e01c4a257ebb1620458 100644 (file)
--- 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 898cdd6f07071cb46ef2726555564713687bf8bd..9f0031af1303d3568eb01f49465e6f1649e505d0 100644 (file)
--- 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 (file)
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}