wikidata: Add rudimentary SPARQL support, split library in two parts,readme

update README, improve examples.

2 bugs exist:
1) the low-level api proc. does not honor language.
2) SPARQL LIMIT is not honored by the server.

1 files changed, 65 insertions, 5 deletions

diff --git a/README b/README
index 80988ff..3296938 100644
--- a/README
+++ b/README
@@ -9,26 +9,84 @@ It is inspired by guile-sparql, python-wikidata_guessing and python-Wikidata.
 It currently has the following dependencies besides guile:
 
 * guile-json
-* guix (only the 2 procedures in (guix import json) for alist functionality.
+* guix 0.15 or later
+ * (guix import json) 2 procedures in for alist functionality and
+   (guix import utils) and (guix http-client) for fetching from
+   servers with error reporting.
+   
+(NOTE: We should really factor out a lot of the generic code in guix in
+external libraries to keep libraries like this one light-weight.)
 
 ## Use as module
 
 It is exported as "wikidata". It can be imported with:
 
 ```
-(use-modules (wikidata))
+(use-modules (wikidata apis)) ; for search and claims APIs
 ```
+And:
+```
+(use-modules (wikidata sparql)) ; for support for SPARQL queries
+```
+
+The first enables you to get all the information in any Q-article in
+Wikidata. 
+
+The second one is very powerfull and enables you e.g. to construct a
+query to get a list of all free software (Q341) in Wikidata. This
+could then e.g. be automatically correlated with package data in guix
+adding a field with the Q-id to the relevant package.
 
 ## Example usage
 
+### Show
+
+To search for paris and get the first 15 results with sv labels
+and descriptions, do:
+
+```
+(search "paris" #:limit 15 #:language 'sv)
+```
+
+#### Notes:
+
+Fallback language is 'en and output is currently limited to Qid,
+label, description (Use the medium level procedures to get other
+data). No more than 50 (500 for bots) results are allowed. 
+
+There is a bug in the API so only english results are returned at the
+time of this writing (dec 2018).
+
+#### Example output:
+
+First 15:       Label & Description
+Q90:    Paris: capital and largest city of Fr...
+Q167646:        Paris: son of Priam, king of Troy
+Q830149:        Paris: county seat of Lamar County, T...
+Q3181341:       Paris: county seat of Bourbon County,...
+Q162121:        Paris: genus of plants
+Q576584:        Paris: city in Illinois
+Q1018504:       Paris: city in Tennessee, United Stat...
+Q984459:        Paris: city in Idaho
+Q79917: Paris: city in Arkansas
+Q160946:        Paris, Texas: 1984 film by Wim Wenders
+Q934294:        Paris: town in Maine, USA
+Q18331346:      Paris: family name
+Q960025:        Paris: city in Missouri
+Q1158980:       Paris: male given name
+Q366081:        Paris Bordone: Italian artist
+
+
+### Medium level-example: extract-search
+
 To search on wikidata and get back an alist with the 10 first results
 with each element being an alist of label, desc, qid, do this:
 
 ```
-(extract-result "Guix")
+(extract-search "Guix")
 ```
 
-Example output:
+#### Example output:
 
 scheme@(guile-user) [2]> (load "wikidata.scm")
 scheme@(guile-user) [2]> ,use(wikidata)
@@ -54,4 +112,6 @@ Longyu") ("id" . "Q8172534")) (("label" . "Guixia Zhao")
  ("id" . "Q56528602")) (("label" . "Guixue Wang") ("description" . #f)
  ("id" . "Q45902385")))
 
-
+You could then map over this list and get the label and description or
+author(s) from Wikidata via queries to the wbgetentity API. See the
+source for procedures.