2014-05-21 22:06:00

5 files changed, 265 insertions, 11 deletions

diff --git a/doc/context/manuals/allkind/mkiv-publications-graph.bib b/doc/context/manuals/allkind/mkiv-publications-graph.bib
new file mode 100644
index 000000000..2e781179c
--- /dev/null
+++ b/doc/context/manuals/allkind/mkiv-publications-graph.bib
@@ -0,0 +1,53 @@
+% A few examples from the MetaPost graph manual that Alan was updating
+% at the time we wrote the new bib code. Watch how uppercase is used here
+% as well as curly braces instead of double quote characters,
+
+@INCOLLECTION{Bentley1990,
+  author = {Bentley, Jon L. and Kernighan, Brian W.},
+  year = {1990},
+  title = {Grap—A language for Typesetting Graphs},
+  booktitle = {Unix Research System Papers},
+  publisher = {{AT\&T} Bell Laboratories},
+  volume = {{II}},
+  pages = {109–146},
+  address = {Murray Hill, New Jersey},
+  edition = {Tenth},
+}
+
+@BOOK{Cleveland1985,
+  author = {Cleveland, William S.},
+  year = {1985, revised 1994},
+  title = {The Elements of Graphing Data},
+  publisher = {Hobart Press},
+  address = {Summit, New Jersey},
+}
+
+@BOOK{Cleveland1993,
+  author = {Cleveland, William S.},
+  year = {1993},
+  title = {Visualizing Data},
+  publisher = {Hobart Press},
+  address = {Summit, New Jersey},
+}
+
+@ARTICLE{Cleveland1993a,
+  author = {Cleveland, William S.},
+  year = {1993},
+  title = {A Model for Studying Display Methods of StatisticalGraphics (with
+	discussion)},
+  journal = {Journal of Computational and Statistical Graphics},
+  volume = {2},
+  pages = {323–343},
+  number = {4},
+  doi = {10.1080/10618600.1993.10474616},
+  eprint = {http://www.tandfonline.com/doi/pdf/10.1080/10618600.1993.10474616},
+  url = {http://www.tandfonline.com/doi/abs/10.1080/10618600.1993.10474616},
+}
+
+@BOOK{Tufte1983,
+  author = {Tufte, Edward R.},
+  year = {1983},
+  title = {Visual Display of Quantitative Information},
+  publisher = {Graphics Press},
+  address = {Box 430, Cheshire, Connecticut 06410},
+}
diff --git a/doc/context/manuals/allkind/mkiv-publications.bib b/doc/context/manuals/allkind/mkiv-publications.bib
index e94f43202..9e9984bfc 100644
--- a/doc/context/manuals/allkind/mkiv-publications.bib
+++ b/doc/context/manuals/allkind/mkiv-publications.bib
@@ -1,3 +1,5 @@
+% A few silly but simple examples.
+
 @book{demo-001,
     author = "Hans Hagen",
     title  = "\BIBTEX, the \CONTEXT\ way",
@@ -18,7 +20,7 @@
 
 @book{demo-004,
     author  = "Luigi Scarso",
-    title   = "Designing high speed trains",
+    title   = "Designing high speed trains properly!",
     year    = "2021",
     comment = "still to be published",
 }
diff --git a/doc/context/manuals/allkind/mkiv-publications.pdf b/doc/context/manuals/allkind/mkiv-publications.pdf
new file mode 100644
index 000000000..2aadba29d
--- /dev/null
+++ b/doc/context/manuals/allkind/mkiv-publications.pdf
diff --git a/doc/context/manuals/allkind/mkiv-publications.tex b/doc/context/manuals/allkind/mkiv-publications.tex
index 0a81467fc..c5bdab14a 100644
--- a/doc/context/manuals/allkind/mkiv-publications.tex
+++ b/doc/context/manuals/allkind/mkiv-publications.tex
@@ -1,6 +1,9 @@
 % language=uk
 
-% \setupbtxrendering[continue=yes]
+
+\setupbtxlistvariant [interaction=start]
+\setupbtxcitevariant [interaction=start]
+
 % \btxfield{manipulator_a->manipulator_b->fieldname}
 
 % engine=luajittex
@@ -8,16 +11,7 @@
 % criterium: all + sorttype=cite     => citex before rest
 % criterium: all + sorttype=database => database order
 % criterium: used
-%
 % numbering: label, short, indexinlist, indexused
-%
-% maybeyear
-%
-% \cite[data][whatever]
-
-% \showframe
-
-% \usemodule[lua-checkheads]
 
 \usemodule[abr-02]
 \usemodule[set-11]
@@ -1282,6 +1276,208 @@ suffix, you can do this:
 
 \stopchapter
 
+\startchapter[title=Searching]
+
+Finding the right key in a database can be a pain. On the other hand, asking for
+a wildcard also makes no sense. Nevertheless we provide a mechanism for matching
+a query. For this we load a small bibliographic database:
+
+\startbuffer
+\usebtxdataset[graph][mkiv-publications-graph.bib]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We could switch to this base using:
+
+\starttyping
+\setbtxdataset[graph]
+\stoptyping
+
+but instead we will use a prefix. For instance, if we have this in our source:
+
+\startbuffer
+searching give a few hits, so we get: \cite [ graph :: match ( author:cleveland and
+year:1993 ) ].
+\stopbuffer
+
+\typebuffer
+
+We will get: \quotation {\inlinebuffer}. Of course this assumes that we also
+typeset a list of referred to references, so let's do that:
+
+\startbuffer
+\definebtxrendering[graph][dataset=graph]
+\placebtxrendering[graph][criterium=chapter]
+\stopbuffer
+
+\typebuffer
+
+We get:
+
+\blank \getbuffer \blank
+
+Let's look in more detail at the \type {\cite} command. In order to distinguish
+efficiently between a normal reference and a more clever one, we use the \type
+{match} keyword:
+
+\startbuffer
+dataset::match(query)
+dataset :: match ( query )
+\stopbuffer
+
+The handler is rather tolerant for spaces:
+
+\startbuffer
+dataset :: match ( query )
+\stopbuffer
+
+Which is handy if you have long queries that wrap around in the source code. Of
+course the \type {dataset::} prefix is optional in which case the current dataset
+is taken.
+
+A query eventually becomes a \LUA\ expression so you can use helpers to achieve
+your goal. As a convenience there are some shortcuts to access fields. The
+following examples demonstrate this:
+
+\starttyping
+match(author:hagen)
+match(author:hagen and author:hoekwater and year:1990-2010)
+match(author:"Bogusław Jackowski")
+match(author:"Bogusław Jackowski" and (tonumber(field:year) or 0) > 2000)
+\stoptyping
+
+You can use quotes when spaces are involved. Of course you can use other
+characters that the basic alphabet. Ranges (of numbers) are recognized. String
+lookups are partial and case insensitive. \footnote {At the time of this
+writing, may 2014, this mechanism is still somewhat experimental.}
+
+\startbuffer
+Wildcards: \cite [graph::match(author:cleve)].
+\stopbuffer
+
+\typebuffer
+
+We get three entries: \quotation {\inlinebuffer}.
+
+% To be checked: are indeed three entries found?
+
+% Match : \cite [match(author:cleveland and year:1993)]      \par
+
+\stopchapter
+
+\startchapter[title=Combining]
+
+It is possible to refer to two sources in one go. In that case the list will have one
+entry for two bibliographic entries.
+
+\startbuffer
+Let's save numbers and refer to Bentley and Tufte with one: \cite [graph ::
+Bentley1990 + Tufte1983]!
+\stopbuffer
+
+\typebuffer
+
+Indeed we get one number only: \quotation {\inlinebuffer}.
+
+\startbuffer
+\setupbtxrendering[graph][continue=yes,separator={; }]
+\placebtxrendering[graph][criterium=chapter]
+\stopbuffer
+
+We produce the (local) list with:
+
+\typebuffer
+
+which shows the two entries pasted together:
+
+\setupbtxrendering[separator=]
+
+\blank \getbuffer \blank
+
+As demonstration we also specified the separator although that one is already
+set up by default.
+
+You can combine citations with additional text before and|/|or after it. This can
+be done per citation. This feature is of course not that useful, as one can
+put text before and after a citation anyway.
+
+\startbuffer
+foo bar \citation [before=<<,after=>>] [graph::Cleveland1993] foo bar
+\stopbuffer
+
+\typebuffer
+
+Gives:
+
+\blank \getbuffer \blank
+
+\stopchapter
+
+\startchapter[title=Summary]
+
+\start
+\setbtxdataset[graph]
+
+There are a lot of combinations possible and not all of them make sense.
+Nevertheless we show most of them here. (There will be more.)
+
+\startbuffer[samples]
+Cleveland : \cite [Cleveland1993,Cleveland1985,Cleveland1993a] \par
+Tufte     : \cite [Tufte1983]                                  \par
+Bentley   : \cite [Bentley1990]                                \par
+All       : \cite [Tufte1983,Cleveland1993,Bentley1990,Cleveland1985,
+                     Cleveland1993a] \par
+\stopbuffer
+
+\starttexdefinition BibSampleSet #1#2
+    \subsubsubject{alternative=#1 / compress=#2}
+    \startpacked
+        \setupbtxcitevariant[#1][compress=#2]
+        \setupbtxcitevariant[alternative=#1]
+        \getbuffer[samples]
+    \stoppacked
+\stoptexdefinition
+
+\BibSampleSet{author}     {no}
+\BibSampleSet{authoryear} {no}
+\BibSampleSet{authoryear} {yes}
+\BibSampleSet{authoryears}{no}
+\BibSampleSet{authoryears}{yes}
+\BibSampleSet{authornum}  {no}
+\BibSampleSet{authornum}  {yes}
+\BibSampleSet{year}       {no}
+\BibSampleSet{year}       {yes}
+\BibSampleSet{short}      {no}
+\BibSampleSet{serial}     {no}
+\BibSampleSet{serial}     {yes}
+\BibSampleSet{tag}        {no}
+\BibSampleSet{key}        {no}
+\BibSampleSet{doi}        {no}
+\BibSampleSet{url}        {no}
+\BibSampleSet{type}       {no}
+\BibSampleSet{category}   {no}
+\BibSampleSet{page}       {no}
+\BibSampleSet{num}        {no}
+\BibSampleSet{num}        {yes}
+
+\startbuffer
+\setupbtxrendering[graph][continue=yes]
+\placebtxrendering[graph][criterium=chapter]
+\stopbuffer
+
+We produce a local list with:
+
+\typebuffer
+
+and get a list with (new) entries:
+
+\blank \getbuffer \blank
+
+\stop
+
+\stopchapter
+
 \startchapter[title=Notes]
 
 The move from external \BIBTEX\ processing to internal processing has the
diff --git a/doc/context/manuals/allkind/publications-en.xml b/doc/context/manuals/allkind/publications-en.xml
index ea577ccf4..002b425bb 100644
--- a/doc/context/manuals/allkind/publications-en.xml
+++ b/doc/context/manuals/allkind/publications-en.xml
@@ -139,6 +139,9 @@
                 <cd:constant type="cd:name"/>
             </cd:keywords>
             <cd:assignments n="2">
+                <cd:parameter name="separator">
+                    <cd:constant type="cd:text"/>
+                </cd:parameter>
                 <cd:parameter name="namesep">
                     <cd:constant type="cd:text"/>
                 </cd:parameter>