[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/sweeprolog 4f96499382 011/166: DOC: expand README.org
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/sweeprolog 4f96499382 011/166: DOC: expand README.org |
Date: |
Fri, 30 Sep 2022 04:59:21 -0400 (EDT) |
branch: elpa/sweeprolog
commit 4f96499382044aea72fa9efbeec81d2786ce99da
Author: Eshel Yaron <me@eshelyaron.com>
Commit: Eshel Yaron <me@eshelyaron.com>
DOC: expand README.org
---
README.org | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 65 insertions(+)
diff --git a/README.org b/README.org
index 1783a40a76..ec4f351ead 100644
--- a/README.org
+++ b/README.org
@@ -21,8 +21,42 @@ embedded SWI-Prolog runtime inside of Emacs.
#+toc: headlines 8 insert TOC here, with eight headline levels
+* Overview
+:PROPERTIES:
+:CUSTOM_ID: overview
+:END:
+
+=sweep= is an embedding of SWI-Prolog in Emacs. It uses the C
+interfaces of both SWI-Prolog and Emacs Lisp to create a dynamically
+loaded Emacs module that contains the SWI-Prolog runtime. As such,
+=sweep= has parts written in C, in Prolog and in Emacs Lisp.
+
+The different parts of =sweep= are structured as follows:
+
+#+CINDEX: sweep-module
+- =sweep.c= defines a dynamic Emacs module which is referred to from
+ Elisp as =sweep-module=. This module is linked against the SWI-Prolog
+ runtime library (=libswipl=) and exposes a subset of the SWI-Prolog C
+ interface to Emacs in the form of Elisp functions (see [[Querying
+ Prolog]]). Notably, =sweep-module= is responsible for translating Elisp
+ objects to Prolog terms and vice versa.
+
+#+CINDEX: sweep.el
+- =sweep.el= defines an Elisp library (named simply =sweep=), which builds
+ on top of =sweep-module= to provide user-facing commands and
+ functionality. It is also responsible for loading and compiling the
+ dynamically loaded =sweep-module=.
+
+#+CINDEX: sweep.pl
+- =sweep.pl= defines a Prolog module (named, unsurprisingly, =sweep=)
+ which is by default arranged by =sweep.el= to be loaded when the
+ embedded Prolog runtime is initialized. It contains predicates that
+ =sweep.el= invoke through =sweep-module= to facilitate its different
+ commands (see [[Finding Prolog code]]).
+
* Installation
:PROPERTIES:
+:CUSTOM_ID: installation
:END:
1. Clone the =sweep= repository:
@@ -51,6 +85,9 @@ embedded SWI-Prolog runtime inside of Emacs.
SWI-Prolog runtime may need to be built as well.
* Querying Prolog
+:PROPERTIES:
+:CUSTOM_ID: querying-prolog
+:END:
=sweep= provides the Elisp function =sweep-open-query= for initiating
Prolog queries. To examine the results of the query, the function
@@ -79,6 +116,9 @@ different permutations of the list =(1 2 3 4 5)=:
#+end_src
* Finding Prolog code
+:PROPERTIES:
+:CUSTOM_ID: finding-prolog-code
+:END:
#+FINDEX: sweep-find-module
=sweep= provides the command {{{kbd(M-x sweep-find-module)}}} for
@@ -92,21 +132,46 @@ Along with {{{kbd(M-x sweep-find-module)}}}, =sweep=
provides the
command {{{kbd(M-x sweep-find-predicate)}}} jumping to the definition a
loaded or auto-loadable Prolog predicate.
+* Known issues
+:PROPERTIES:
+:CUSTOM_ID: known-issues
+:END:
+
+** Collision between Emacs' and SWI-Prolog's use of GMP
+:PROPERTIES:
+:CUSTOM_ID: gmp-collision
+:END:
+
+Currently, =sweep= builds the SWI-Prolog runtime without GMP support
+(using the =cmake= flag =-DUSE_GMP=OFF=). Initializing SWI-Prolog inside
+Emacs with GMP support /enabled/ for SWI-Prolog causes Emacs to crash
+during garbage collection, because SWI-Prolog =mp_free= routine is
+mistakenly invoked to cleanup Elisp big integers.
+
+Aside from the obvious problem of not being able to utilize SWI-Prolog
+support for unbounded integer arithmetic, this issue also prevents us
+from using an existing =libswipl= since it is most likely to have been
+built with GMP enabled.
+
* Indices
:PROPERTIES:
+:CUSTOM_ID: indices
:END:
** Function index
:PROPERTIES:
:INDEX: fn
+:CUSTOM_ID: findex
:END:
** Variable index
:PROPERTIES:
:INDEX: vr
+:CUSTOM_ID: vindex
:END:
** Concept index
:PROPERTIES:
:INDEX: cp
+:CUSTOM_ID: cindex
:END:
- [nongnu] elpa/sweeprolog 5b9e2d7d7c 126/166: ADDED: sweep_op_info/2: new_predicate, (continued)
- [nongnu] elpa/sweeprolog 5b9e2d7d7c 126/166: ADDED: sweep_op_info/2: new_predicate, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 5eb4ede8f8 113/166: ADDED: (sweep-prefix-operators): New function, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 2abad939fe 108/166: DOC: Following file specifications: new section, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 6dd6433920 165/166: ENHANCED: fontify quasi-quotation content according to its type, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 48e8fb7c65 155/166: ENHANCED: (sweep--colour-term-to-face): return multiple regions, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 1c87ca72e3 163/166: DOC: document new variable highlighting in the manual, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog a8d186092f 157/166: ENHANCED: More indicative error on failure to locate sweep-module, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 97856b5c85 159/166: DOC: add installation instructions from NonGNU ELPA, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 348294a57f 002/166: Add swipl-devel submodule, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog b2838d5477 004/166: Cleanup, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 4f96499382 011/166: DOC: expand README.org,
ELPA Syncer <=
- [nongnu] elpa/sweeprolog 5c4aef50f2 041/166: Run `ninja install` as root in CI, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog a6e37f306b 069/166: ENHANCED: fontify mutlifile predicate calls in a dedicated face, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 4299c39d62 070/166: ENHANCED: indentation edge cases handling, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 1a19f7b3be 074/166: DOC: document font-lock and xref integration for sweep-mode, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 1c6d2e96a8 078/166: ENHANCED: allow user to specify location of swipl binary, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 5a8f70149f 099/166: FIXED: (sweep-load-buffer): error after prompting for a buffer, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog 7327016d15 095/166: FIXED: sweep_predicates_collection/2: include preds defined in user, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog a70a730f48 087/166: PORT: don't use the 2nd arg to looking-at, added only in Emacs 29, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog d1a2913f75 115/166: ENHANCED: Update semantic highlighting on idle timer in sweep-mode, ELPA Syncer, 2022/09/30
- [nongnu] elpa/sweeprolog b168465391 098/166: FIXED: sweep_load_buffer/3: load files in the context of "user", ELPA Syncer, 2022/09/30