summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/context/document/general/manuals/mreadme.pdfbin85996 -> 0 bytes
-rw-r--r--doc/context/document/general/manuals/tiptrick.pdfbin30607 -> 0 bytes
-rw-r--r--doc/context/documents/general/manuals/mreadme.pdfbin0 -> 40916 bytes
-rw-r--r--doc/context/documents/general/manuals/swiglib-mkiv.pdfbin0 -> 169227 bytes
-rw-r--r--doc/context/documents/general/manuals/tiptrick.pdfbin0 -> 47399 bytes
-rw-r--r--doc/context/documents/general/manuals/tools-mkiv.pdfbin0 -> 374143 bytes
-rw-r--r--doc/context/documents/general/manuals/units-mkiv.pdfbin0 -> 163981 bytes
-rw-r--r--doc/context/documents/general/manuals/xtables-mkiv.pdfbin0 -> 128566 bytes
-rw-r--r--doc/context/manuals/allkind/mcommon.tex199
-rw-r--r--doc/context/manuals/allkind/mkiv-publications-graph.bib53
-rw-r--r--doc/context/manuals/allkind/mkiv-publications.bib44
-rw-r--r--doc/context/manuals/allkind/mkiv-publications.pdfbin203988 -> 0 bytes
-rw-r--r--doc/context/manuals/allkind/mkiv-publications.tex2836
-rw-r--r--doc/context/manuals/allkind/mreadme.tex361
-rw-r--r--doc/context/manuals/allkind/publications-en.xml387
-rw-r--r--doc/context/sources/general/manuals/mcommon.tex210
-rw-r--r--doc/context/sources/general/manuals/readme/mreadme.tex372
-rw-r--r--doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex335
-rw-r--r--doc/context/sources/general/manuals/tiptrick/tiptrick.tex117
-rw-r--r--doc/context/sources/general/manuals/tiptrick/tiptrick.xml53
-rw-r--r--doc/context/sources/general/manuals/tools/tools-mkiv.tex501
-rw-r--r--doc/context/sources/general/manuals/units/units-mkiv.tex538
-rw-r--r--doc/context/sources/general/manuals/workflows/workflows-mkiv.tex351
-rw-r--r--doc/context/sources/general/manuals/xtables/xtables-mkiv.tex1041
24 files changed, 3518 insertions, 3880 deletions
diff --git a/doc/context/document/general/manuals/mreadme.pdf b/doc/context/document/general/manuals/mreadme.pdf
deleted file mode 100644
index 338008015..000000000
--- a/doc/context/document/general/manuals/mreadme.pdf
+++ /dev/null
Binary files differ
diff --git a/doc/context/document/general/manuals/tiptrick.pdf b/doc/context/document/general/manuals/tiptrick.pdf
deleted file mode 100644
index 3ced360e1..000000000
--- a/doc/context/document/general/manuals/tiptrick.pdf
+++ /dev/null
Binary files differ
diff --git a/doc/context/documents/general/manuals/mreadme.pdf b/doc/context/documents/general/manuals/mreadme.pdf
new file mode 100644
index 000000000..59cc2a621
--- /dev/null
+++ b/doc/context/documents/general/manuals/mreadme.pdf
Binary files differ
diff --git a/doc/context/documents/general/manuals/swiglib-mkiv.pdf b/doc/context/documents/general/manuals/swiglib-mkiv.pdf
new file mode 100644
index 000000000..54d36aeb2
--- /dev/null
+++ b/doc/context/documents/general/manuals/swiglib-mkiv.pdf
Binary files differ
diff --git a/doc/context/documents/general/manuals/tiptrick.pdf b/doc/context/documents/general/manuals/tiptrick.pdf
new file mode 100644
index 000000000..edfa6f0ad
--- /dev/null
+++ b/doc/context/documents/general/manuals/tiptrick.pdf
Binary files differ
diff --git a/doc/context/documents/general/manuals/tools-mkiv.pdf b/doc/context/documents/general/manuals/tools-mkiv.pdf
new file mode 100644
index 000000000..cd2c062eb
--- /dev/null
+++ b/doc/context/documents/general/manuals/tools-mkiv.pdf
Binary files differ
diff --git a/doc/context/documents/general/manuals/units-mkiv.pdf b/doc/context/documents/general/manuals/units-mkiv.pdf
new file mode 100644
index 000000000..50e09def5
--- /dev/null
+++ b/doc/context/documents/general/manuals/units-mkiv.pdf
Binary files differ
diff --git a/doc/context/documents/general/manuals/xtables-mkiv.pdf b/doc/context/documents/general/manuals/xtables-mkiv.pdf
new file mode 100644
index 000000000..0544696d4
--- /dev/null
+++ b/doc/context/documents/general/manuals/xtables-mkiv.pdf
Binary files differ
diff --git a/doc/context/manuals/allkind/mcommon.tex b/doc/context/manuals/allkind/mcommon.tex
deleted file mode 100644
index f0c22cff4..000000000
--- a/doc/context/manuals/allkind/mcommon.tex
+++ /dev/null
@@ -1,199 +0,0 @@
-% content=tex
-%
-% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa
-
-\startenvironment mcommon
-
-% modules
-
-\usemodule[abr-02]
-
-% layout
-
-\startmode[screen]
- \setuppapersize[S6][S6]
- \setupinteraction[state=start]
- \setupinteractionscreen[options=max]
-\stopmode
-
-\setuplayout
- [footer=0cm,
- width=middle,
- height=middle]
-
-% fonts
-
-\startmode[atpragma]
-
- \startMPenvironment[global]
- \usetypescriptfile[type-buy]
- \usetypescript[lucida][texnansi]
- \setupbodyfont[lucida,10pt]
- \stopMPenvironment
-
- \setupbodyfont[11pt]
-
-\stopmode
-
-\startnotmode[atpragma]
-
- \startMPenvironment[global]
- \usetypescript[palatino][ec]
- \setupbodyfont[palatino,10pt]
- \stopMPenvironment
-
- \setupbodyfont[11pt]
-
-\stopnotmode
-
-\definefont [BigFont] [SansBold at 60pt]
-\definefont [MedFont] [SansBold at 30pt]
-
-% colors
-
-\setupcolors
- [state=start]
-
-\definecolor [NopColor] [r=.6,g=.4,b=.5]
-\definecolor [AltColor] [r=.4,g=.6,b=.5]
-\definecolor [TheColor] [r=.4,g=.5,b=.6]
-\definecolor [TmpColor] [r=.6,g=.5,b=.4]
-
-\definecolor [red] [NopColor]
-\definecolor [green] [AltColor]
-\definecolor [blue] [TheColor]
-\definecolor [yellow][TmpColor]
-
-% spacing
-
-\setupwhitespace
- [big]
-
-\setuptolerance
- [verytolerant,stretch]
-
-% verbatim
-
-\setuptype
- [color=AltColor]
-
-\setuptyping
- [color=AltColor]
-
-% structure
-
-\setupitemize
- [each]
- [color=TheColor]
-
-\definedescription
- [switch]
- [headstyle=type,
- headcolor=TheColor,
- location=serried,
- width=broad]
-
-\defineenumeration
- [topic]
- [location=serried,
- width=broad,
- headstyle=,
- headcolor=TheColor,
- text=,
- left={[},
- right={]}]
-
-\setuphead
- [section]
- [style=\ss\bfb,
- color=TheColor]
-
-\setuplist
- [section]
- [alternative=c,
- color=TheColor,
- textcolor=black,
- pagecolor=black]
-
-% whatever
-
-\setupsystem
- [random=medium]
-
-\setupfloats
- [ntop=100]
-
-\setupinteraction
- [style=,
- color=NopColor,
- contrastcolor=NopColor]
-
-% tables and frames
-
-\setuptabulate
- [rulethickness=.5pt,
- rulecolor=AltColor]
-
-\setuptables
- [rulethickness=.5pt,
- rulecolor=AltColor]
-
-\setupframedtexts
- [rulethickness=.5pt,
- framecolor=TheColor,
- width=\textwidth]
-
-% quick reference things
-
-\usemodule[set-11] \loadsetups
-
-\setupframedtexts
- [setuptext]
- [rulethickness=.5pt,
- framecolor=AltColor]
-
-% basic titlepage and colofon, a bit old fashioned approach, but let's not
-% modernize everything now
-
-\def\TitlePage#1#2#3#4#5% number/name angle title author screen
- {\doifnumberelse{#1}
- {\ifcase#1
- \defineoverlay
- [logo]
- [\useMPgraphic{titlepage}{width=\overlaywidth,height=\overlayheight}]
- \else
- \startMPrun
- logo_type := #1 ; mpgraph := #1 ; input mp-cont ;
- \stopMPrun
- \defineoverlay
- [logo]
- [{\externalfigure
- [\MPrunfile{#1}]
- [width=\overlaywidth,height=\overlayheight]}]
- \fi}
- {\defineoverlay
- [logo]
- [\useMPgraphic{#1}{width=\overlaywidth,height=\overlayheight}]}
- \setupbackgrounds
- [page]
- [background=logo]
- \definecolor[Gray][s=#5]
- \startstandardmakeup
- \dontcomplain
- \BigFont \setupinterlinespace \vfill \setupalign[left] \let\\=\par
- \ifcase#2\relax
- \noindent\color[Gray]{#3}\par
- \else
- \noindent\rotate[rotation=#2]{\color[Gray]{#3}}\par
- \fi
- \stopstandardmakeup
- \setupbackgrounds
- [page]
- [background=]}
-
-\def\ColofonPage
- {\startstandardmakeup
- \vfill \setups [pragma-colofon]
- \stopstandardmakeup}
-
-\stopenvironment
diff --git a/doc/context/manuals/allkind/mkiv-publications-graph.bib b/doc/context/manuals/allkind/mkiv-publications-graph.bib
deleted file mode 100644
index 2e781179c..000000000
--- a/doc/context/manuals/allkind/mkiv-publications-graph.bib
+++ /dev/null
@@ -1,53 +0,0 @@
-% 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
deleted file mode 100644
index 9fb36e99a..000000000
--- a/doc/context/manuals/allkind/mkiv-publications.bib
+++ /dev/null
@@ -1,44 +0,0 @@
-% A few silly but simple examples.
-
-@book{demo-001,
- author = "Hans Hagen",
- title = "\BIBTEX, the \CONTEXT\ way",
- year = "2013",
-}
-
-@book{demo-002,
- crossref = "demo-001"
- year = "2014",
-}
-
-@book{demo-003,
- author = "Hans Hagen and Ton Otten",
- title = "Typesetting education documents",
- year = "1996",
- comment = "a non-existing document",
-}
-
-@book{demo-004,
- author = "Luigi Scarso",
- title = "Designing high speed trains properly!",
- year = "2021",
- comment = "still to be published",
-}
-
-@book{demo-005,
- author = "author",
- title = "title",
- year = "year",
- serial = "serial",
- doi = "doi",
- url = "url",
- pages = "pages",
- language = "en",
-}
-
-@book{demo-006,
- author = "Hans Hagen and Kees van Marle and Ton Otten",
- title = "Why do we always have lack of time?",
- year = "2014",
- comment = "yet another non-existing document",
-}
diff --git a/doc/context/manuals/allkind/mkiv-publications.pdf b/doc/context/manuals/allkind/mkiv-publications.pdf
deleted file mode 100644
index ed8d0456c..000000000
--- a/doc/context/manuals/allkind/mkiv-publications.pdf
+++ /dev/null
Binary files differ
diff --git a/doc/context/manuals/allkind/mkiv-publications.tex b/doc/context/manuals/allkind/mkiv-publications.tex
deleted file mode 100644
index 933cabaa1..000000000
--- a/doc/context/manuals/allkind/mkiv-publications.tex
+++ /dev/null
@@ -1,2836 +0,0 @@
-% language=en % uk - Is behaviour really better than behavior, defence than defense?
-
-% NOTE: I have purposely not reformated the source text linebreaks in order to facilitate
-% comparaison of my editing using diff & co.
-
-% \usebtxdataset[alan-1.bib]
-% \setupbtxrendering[standard][repeat=yes,continue=yes,method=global]
-%
-% \starttext
-%
-% \startbodymatter
-% \startchapter[title=First chapter]
-% cite: \cite[Hagen]
-% \blank
-% \placelistofpublications[standard][criterium=chapter]
-% \stopchapter
-% \startchapter[title=Second chapter]
-% cite: \cite[Scarso]
-% \blank
-% cite: \cite[Hagen]
-% \blank
-% \placelistofpublications[standard][criterium=chapter]
-% \stopchapter
-% \stopbodymatter
-%
-% \startbackmatter
-% \startchapter[title=Bibliography,number=no]
-% \placelistofpublications[standard][criterium=all]
-% \stopchapter
-% \stopbackmatter
-%
-% \stoptext
-
-% \usebtxdataset
-% [example]
-% [t:/manuals/publications-mkiv/mkiv-publications.bib]
-%
-% \definebtxrendering
-% [example]
-% [dataset=example]
-%
-% \starttext
-% \showbtxdatasetfields[example]
-% some text
-% %\placebtxrendering[example][method=dataset]
-% \placebtxrendering[example][method=dataset,sorttype={{detail:author,detail:editor},{entry:year,9998},entry:journal,entry:title,entry:pages}]
-% %\placebtxrendering[example][method=dataset,sorttype={entry:title,{entry:year,3000},{detail:author,detail:editor}}]
-% \stoptext
-
-% do etallimit etaldisplay
-
-\enablemode[export]
-
-% criterium: all + sorttype=cite => citex before rest
-% criterium: all + sorttype=dataset => dataset order
-% criterium: used
-% numbering: label, short, indexinlist, indexused
-
-% \enabletrackers[publications*]
-
-% \enabletrackers[publications.cite.match]
-
-\dontcomplain
-
-\setupbtxlistvariant [interaction=start]
-\setupbtxcitevariant [interaction=start]
-
-\usemodule[abr-02]
-\usemodule[set-11]
-
-\startmode[export]
-
- \setupbackend
- [export=yes,
- xhtml=yes,
- css=export-example.css]
-
- \setupexport
- [hyphen=yes,
- width=60em]
-
-\stopmode
-
-\startdocument
- [title={\BIBTEX},
- subtitle={The \CONTEXT\ way},
- author={Hans Hagen and Alan Braslau}]
-
-% We need some (\expandafter,\unexpanded,...?) \TEX\ magic here (or above?):
-\setupinteraction
- [title={\getvariable{document}{title}},
- subtitle={\getvariable{document}{subtitle}},
- author={\getvariable{document}{author}}]
-
-\loadsetups[publications-en.xml] \enablemode[interface:setup:defaults]
-
-% \input publ-tmp.mkiv
-
-\setupbodyfont
- [dejavu,10pt]
-
-\setuphead
- [chapter]
- [header=high,
- style=\bfc,
- color=darkmagenta]
-
-\setuplayout
- [topspace=2cm,
- bottomspace=1cm,
- header=0cm,
- width=middle,
- height=middle]
-
-\setupwhitespace
- [big]
-
-\setuptyping
- [color=darkmagenta]
-
-\setuptyping
- [keeptogether=yes]
-
-\setuptype
- [color=darkmagenta]%darkcyan]
-% How to get: option=TEX ?
-
-\setupfootertexts
- [pagenumber]
-
-\setupMPgraphics
- [mpy=\jobname.mpy]
-
-\setupinteraction
- [state=start,
- color=darkcyan,
- contrastcolor=darkyellow]
-
-\setupalign
- [verytolerant]
-
-% The details of the following are a question of style
-% to be used for notes or asides (but more important than footnotes)
-\setupframedtexts
- [width=\textwidth,
- background=color,backgroundcolor=lightgray,
- % (may lead to some confusion with \showsetups?)
- offset=0.5cm,
- %before={\blank[small]},
- %after={\blank[small]},
- frame=off,
- ]
-\automigrateinserts % needed to handle footnotes within a box...
-% BUT, footnotes within framedtext still disappear! ?
-
-\setupnote [footnote] [next={ }] % Why should this be necessary?
-
-% Since this is a manual about bibliographies, let us use citations...
-\startbuffer [bibliography]
-@Book{Ierusalimschy2006,
- author ={Ierusalimschy, R.},
- title ={Programming in Lua},
- year ={2006},
- publisher={Lua.org},
- isbn ={8590379817},
- url ={http://www.lua.org/pil/contents.html},
-}
-@Book{APA2010,
- title ={Publication Manual of the American Psychological Association},
- year ={2010},
- edition ={Sixth},
- address ={Washington, DC},
- publisher={American Psychological Association},
- note ={291 pages},
- url ={http://www.apa.org/books/},
-}
-\stopbuffer
-\usebtxdataset [standard] [bibliography.buffer]
-
-\startMPpage
-
- StartPage ;
-
- % input "mkiv-publications.mpy" ;
-
- picture pic ; pic := image (
- path pth ; pth := ((0,0) for i=1 step 2 until 20 : -- (i,1) -- (i+1,0) endfor) ;
- for i=0 upto 9 : draw pth shifted (0,2*i) ; endfor ;
- ) ;
-
- picture btx ; btx := textext("\ssbf\WORDS{\getvariable{document}{title}}") ;
- picture ctx ; ctx := textext("\ssbf\WORDS{\getvariable{document}{subtitle}}") ;
- picture dtx ; dtx := textext("\ssbf \getvariable{document}{author}") ;
- % why do you use outline fonts here? (and why does it not work for me?)
- %picture btx ; btx := image(graphictext("\ssbf BIBTEX") withfillcolor white) ;
- %picture ctx ; ctx := image(graphictext("\ssbf THE CONTEXT WAY") withfillcolor white) ;
-
- pic := pic shifted - llcorner pic ;
- btx := btx shifted - llcorner btx ;
- ctx := ctx shifted - llcorner ctx ;
- dtx := dtx shifted - llcorner dtx ;
-
- pic := pic xysized (PaperWidth,PaperHeight) ;
- btx := btx xsized (2PaperWidth/3) shifted (.25PaperWidth,.225PaperHeight) ;
- ctx := ctx xsized (2PaperWidth/3) shifted (.25PaperWidth,.150PaperHeight) ;
- dtx := dtx xsized (2PaperWidth/3) shifted (.25PaperWidth,.075PaperHeight) ;
-
- fill Page withcolor \MPcolor{darkcyan} ;
-
- draw pic withcolor \MPcolor{darkmagenta} ;
- draw btx withcolor \MPcolor{lightgray} ;
- draw ctx withcolor \MPcolor{lightgray} ;
- draw dtx withcolor \MPcolor{lightgray} ;
-
- % draw boundingbox btx ;
- % draw boundingbox ctx ;
- % draw boundingbox dtx ;
-
- StopPage ;
-
-\stopMPpage
-
-\startfrontmatter
-
-\starttitle[title=Contents]
- \setuplist[chapter][before=,after=]
- \placelist[chapter][color=black]
-\stoptitle
-
-\startchapter[title=Introduction]
-
-This manual describes how \MKIV\ handles bibliographies. Support in \CONTEXT\
-started in \MKII\ for \BIBTEX, using a module written by Taco Hoekwater. Later his
-code was adapted to \MKIV, but because users demanded more, I decided that
-reimplementing made more sense than patching. In particular, through the use of
-\LUA, the \BIBTEX\ data files can be easily directly parsed, thus liberating
-\CONTEXT\ from the dependency on an external \BIBTEX\ executable. The CritEd
-project (by Thomas Schmitz, Alan Braslau, Luigi Scarso and myself) was a good
-reason to undertake this rewrite. As part that project users were invited to come
-up with ideas about extensions. Not all of them are (yet) honored, but the
-rewrite makes more functionality possible.
-
-This manual is dedicated to Taco Hoekwater who in a previous century implemented
-the first \BIBTEX\ module and saw it morph into a \TEX||\LUA\ hybrid in this
-century. The fact that there was support for bibliographies made it possible for
-users to use \CONTEXT\ in an academic environment, dominated by bibliographic
-databases encoded in the \BIBTEX\ format.
-
-The subsystem described here is one of the most complex and messy of all \CONTEXT\
-subsystems. This has to do with the fact that it combines (multiple) lists and
-(multiple) forward and backward references, all kind of rendering of the citation
-as well as the entry in the list, rather complex interactivity, multiple
-databases, datasets and renderings and of course combinations of this. The
-implementation uses a mix of \TEX\ and \LUA\ code with so called setups as
-rendering specifications. At the cost of complexity (and some runtime penalty) this
-provides a lot of freedom and flexibility.
-
-\startlines
-Hans Hagen
-PRAGMA ADE
-Hasselt NL
-\stoplines
-
-\stopchapter
-
-\stopfrontmatter
-
-\startbodymatter
-
-\startchapter[title=The database]
-
-The bibliography subsystem uses a database or a set of databases to construct
-a list of citations to be used in a scholarly work. However, it will be seen
-later that the database system can be used (and abused) to many ends having
-little or nothing to do with citations and bibliographies. Nevertheless, we
-will remain focused on the use of bibliography databases.
-
-\startsection[title=\BIBTEX]
-
-The \BIBTEX\ format is rather popular in the \TEX\ community and even with its
-shortcomings it will stay around for a while. Many publication websites can
-export and many tools are available to work with this database format. It is
-rather simple and looks a bit like \LUA\ tables.%
-\startfootnote
-Indeed, it is said that the \BIBTEX\ format was one of the inspirations for the
-constructor syntax in \LUA. \cite[extras={ Chapter 12.}][standard::Ierusalimschy2006]
-\stopfootnote
-
-Unfortunately the content can be
-polluted with non|-|standardized \TEX\ commands which complicates pre- or
-postprocessing outside \TEX. In that sense a \BIBTEX\ database is often not coded
-neutrally. Some limitations, like the use of commands to encode accented
-characters root in the \ASCII\ world and can be bypassed by using \UTF\ instead
-(as handled somewhat in \LATEX\ through extensions such as \type {bibtex8}).
-
-The normal way to deal with a bibliography is to refer to entries using a unique
-tag or key. When a list of entries is typeset, this reference can be used for
-linking purposes. The typeset list can be processed and sorted using the \type
-{bibtex} program that converts the database into something more \TEX\ friendly (a
-\type {.bbl} file). I never used the program myself (nor bibliographies) so I
-will not go into too much detail here, if only because all I say can be wrong.
-
-In \CONTEXT\ we no longer use the (external) \type {bibtex} program at all: we
-simply parse the
-database files and deal with the necessary manipulations directly in \CONTEXT.
-One or more such databases can be used and combined with additional entries
-defined within the document. We can have several such datasets active at the same
-time.
-
-A \BIBTEX\ file entry looks like this:
-
-\starttyping
-@Article{sometag,
- author = "An Author and Another One",
- title = "A hopefully meaningful title",
- journal = maps,
- volume = "25",
- number = "2",
- pages = "5--9",
- month = mar,
- year = "2013",
- ISSN = "1234-5678",
-}
-\stoptyping
-
-Entries are of the form: \type{@category{…}}%
-\startfootnote
-Anything outside of a valid \type{@category{…}} construction is ignored and is
-taken to be a comment. Within an entry, there are to be no comments but one can
-prefix field names, for example, to have them ignored.
-
-\quotation{There is a special entry type named \type {@comment{…}}. The main use of
-such an entry type is to comment a large part of the bibliography easily,
-since anything outside an entry is already a comment, and commenting out
-one entry may be achieved by just removing its initial~\type {@}.} — This is perhaps
-of some use, although not very elegant! As one can input multiple bibliography data
-files, as will be seen below, it is much better practice to split datafiles for
-optional loading.
-
-Furthermore, many \BIBTEX\ data management tools such as \type {jabref} (see below) will
-ignore and then throw-away all such handily-crafted comments and data entries turned
-into comments. So one must beware!
-\stopfootnote
-The field names are all cast to lowercase so capitalization is irrelevant;
-%\startfootnote
-%But, whereas \BIBTEX\ is indifferent to the capitalization of the category names,
-%we are a bit more picky here in order to gain performance in the loading of huge data
-%files. This may be relaxed in the future.
-%\stopfootnote
-Spacing is not important and should be used advantageously for readability. The
-leading tag (\type {sometag}) cannot contain spaces and must be followed by a comma.%
-\startfootnote
-The tag is, in fact, optional, as will be seen later.
-\stopfootnote
-
-Normally a value is given between quotes (or curly brackets) but single words are
-also OK (as there is no real benefit in not using quotes or curly brackets, we advise to always use
-them). The order of the fields in an entry is inconsequential and there can be many more fields than those shown above. Instead of string values one can also use
-predefined shortcuts. The title for example might quite often contain \TEX\ macros.
-Some fields, like \type {pages} have funny characters such as the endash
-(typically entered as \type {--}) so we have a mixture of data and typesetting
-directives. If you are covering non||english references, you often need
-characters that are not in the \ASCII\ subset (but \CONTEXT\ is quite happy with
-\UTF). If your database file uses old|-|fashioned \TEX\ accent combinations then these
-will be internally converted automatically to \UTF. Commands (macros) found in a database file are
-converted to an indirect call, which is quite robust.
-
-\startframedtext
-{\sl A note on strings:} the \type {author} (and \type {editor}) fields are parsed
-separating multiple authors identified by the conjunction \quote{and}. Each name
-is assumed to be in the form: Firstname(s) Lastname (where Lastname may include an
-optional \quote{von}: lower-case word(s) such as \quotation{von}, \quotation{de},
-\quotation{de la}, etc.) {\em unless} specifically in the form: Lastname(s),
-Firstname(s) or Lastnames(s), Suffix(es), Firstname(s) (separated explicitly using
-comma(s)).
-
-Other string values such as \type {title} are kept literally (except for an
-internal automatic conversion to \UTF\ of certain \TEX\ strings such as accent
-combinations, endash, quotations, etc.). Note that the bibliography rendering
-style (see below) might specify a capitalization (using the \CONTEXT\ command
-\type {\Words}, for example). Capitalized Names and acronyms are respected,
-removing a need for the \BIBTEX\ practice of \quote{protecting} such words or
-letters with surrounding curly brackets (which are simply stripped off).%
-\startfootnote
-Since \CONTEXT\ uses \UTF, it suffers neither from all of the complicated
-sorting issues that plague \BIBTEX/\LATEX.
-\stopfootnote
-{\red (WHERE DID THE FOOTNOTE GO?)}
-As some styles might not specify the capitalization of words in the title whereas
-other styles might, it is recommended that strings be written in lower case
-except where upper case is explicitly required so as to be compatible with all
-such capitalization styles.%
-\startfootnote
-Some bibliographic database sources can be quite sloppy and return strings
-(titles and even authors) in all capitals, for example. We have made the
-design choice {\em not} to follow the \BIBTEX\ practice/feature of managing
-strings as we did not want to require the protection through enclosing curly
-brackets that would have been a necessary consequence. Thus, some cleaning
-of these database files might be needed.
-\stopfootnote
-{\red (WHERE DID THE FOOTNOTE GO?)}
-
-String values can be enclosed indifferently between matching curly brackets:
-\type {{}} or pairs of quotation marks: \type{""}. Multiple string values can
-be concatenated using the operator \type {#}.%
-\startfootnote
-The \BIBTEX\ string concatenation operator \type {\#} is not to be confused
-with the \LUA\ operator \type {..}, nor with the \METAPOST\ operator \type {\&}!
-\stopfootnote
-{\red (WHERE DID THIS FOOTNOTE GO?)}
-\stopframedtext
-
-Everything outside of a valid entry is ignored and treated as a comment.
-
-The \BIBTEX\ files are loaded in memory as \LUA\ table but can be converted to
-\XML\ so that we can access them in a more flexible way, but that is a subject
-for specialists. % to be discussed later?
-
-\stopsection
-
-\startsection[title=\MKII\ definitions]
-
-In the old \MKII\ setup we have two kinds of entries: the ones that come from the
-\BIBTEX\ run and additional user supplied ones. We no longer rely on \BIBTEX\ output but we
-do still support the user supplied definitions. These were in fact prepared in a
-way that suits the processing of \BIBTEX\ generated entries. The next variant
-reflects the \CONTEXT\ recoding of the old \BIBTEX\ output.
-
-\starttyping
-\startpublication[k=Hagen:Second,t=article,a={Hans Hagen},y=2013,s=HH01]
- \artauthor[]{Hans}[H.]{}{Hagen}
- \arttitle{Who knows more?}
- \journal{MyJournal}
- \pubyear{2013}
- \month{8}
- \volume{1}
- \issue{3}
- \issn{1234-5678}
- \pages{123--126}
-\stoppublication
-\stoptyping
-
-The split \type {\artauthor} fields are collapsed into a single \type {author}
-field as we handle the splitting later when it gets parsed in \LUA. The \type
-{\artauthor} syntax is only kept around for backward compatibility with the
-previous use of \BIBTEX.
-
-In the new setup we support these variants:
-
-\starttyping
-\startpublication[k=Hagen:Third,t=article]
- \author{Hans Hagen}
- \title{Who knows who?}
- ...
-\stoppublication
-\stoptyping
-
-as well as
-
-\starttyping
-\startpublication[tag=Hagen:Third,category=article]
- \author{Hans Hagen}
- \title{Who knows who?}
- ...
-\stoppublication
-\stoptyping
-
-and
-
-\starttyping
-\startpublication
- \tag{Hagen:Third}
- \category{article}
- \author{Hans Hagen}
- \title{Who knows who?}
- ...
-\stoppublication
-\stoptyping
-
-\stopsection
-
-\startsection[title=\LUA\ tables]
-
-Because internally the entries are \LUA\ tables, we also support the loading of \LUA\
-based definitions:
-
-\starttyping
-return {
- ["Hagen:First"] = {
- author = "Hans Hagen",
- category = "article",
- issn = "1234-5678",
- issue = "3",
- journal = "MyJournal",
- month = "8",
- pages = "123--126",
- tag = "Hagen:First",
- title = "Who knows nothing?",
- volume = "1",
- year = "2013",
- },
-}
-\stoptyping
-
-\stopsection
-
-\startsection[title=\XML]
-
-The following \XML\ input is rather
-close in structure, and is also accepted as input.
-
-\starttyping
-<?xml version="2.0" standalone="yes" ?>
-<bibtex>
- <entry tag="Hagen:First" category="article">
- <field name="author">Hans Hagen</field>
- <field name="category">article</field>
- <field name="issn">1234-5678</field>
- <field name="issue">3</field>
- <field name="journal">MyJournal</field>
- <field name="month">8</field>
- <field name="pages">123--126</field>
- <field name="tag">Hagen:First</field>
- <field name="title">Who knows nothing?</field>
- <field name="volume">1</field>
- <field name="year">2013</field>
- </entry>
-</bibtex>
-\stoptyping
-
-\stopsection
-
-\startsection[title=Other formats]
-
-Many various bibliographic data file formats are available, such as:
-\starttabulate [|lT|p|]
-\NC savedrecs.txt \NC Institute of Scientific Information (ISI) tagged format
- (e.g. Thomson Reuters™ Web of Science™), \NC \NR
-\NC filename.enw \NC Thomson Reuters™ Endnote™ export format
- (there is also an Endnote \type {.xml} export), \NC \NR
-\NC filename.ris \NC Research Information Systems, Incorporated, now
- Thomson Reuters™ Reference Manager™, and \NC \NR
-\NC pubmed_result.txt \NC The National Library of Medicine® (NLM®)
- MEDLINE®/PubMed® data format \NC \NR
-\stoptabulate
-just to name a few. Filters can be easily written in \LUA\ to also read these
-and other bibliography data formats. However, the user has a choice of
-bibliography database management programs that can easily convert these
-to the \BIBTEX\ format. Notable, open source examples are
-\goto {jabref} [url(http://jabref.sourceforge.net)] and
-\goto {zotero} [url(http://www.zotero.org)].
-Indeed, it is not the vocation of the present \CONTEXT\ bibliography subsystem
-to fully manage the bibliography data sources, only to be able to use such data
-in the production of documents.
-
-\stopsubsection
-
-\stopsection
-
-\startsection[title=Dataset coverage]
-
-You can load much more data than you actually need. Only entries that are referred to
-explicitly (through the \type {\cite} and \type {\nocite} commands) will be shown
-in lists. We will cover these details later.
-
-\stopsection
-
-\stopchapter
-
-\startchapter[title=Commands in entries]
-
-One unfortunate aspect commonly found in \BIBTEX\ files is that they may
-contain \TEX\ commands. Even worse is that there is no standard on what these
-commands can be and what they mean, at least not formally, as \BIBTEX\ is a
-program intended to be used with many variants of \TEX\ style: plain, \LATEX, and
-others. This means that we need to define our use of these typesetting commands.%
-\startfootnote
-In particular, one might need to redefine those that are too \LATEX-centric.
-\stopfootnote
-However, in most cases, they are just abbreviations or font switches and these
-are often well known. Therefore, \CONTEXT\ will try to resolve them before reporting
-an issue. The log file will announce the commands that have been seen in the
-loaded databases. For instance, loading \type {tugboat.bib}%
-\startfootnote
-\type {tugboat.bib} is distributed with \TeX{}Live.
-\stopfootnote
-gives a long list of
-commands of which we show a small set of the five most frequently encountered ones here:
-\startbuffer[tugboat]
-%\definebtxdataset[tugboat]
-\usebtxdataset[tugboat][tugboat.bib]
-\stopbuffer
-\getbuffer[tugboat]
-
-\starttyping
-publications > start used btx commands
-
-publications > tugboat tt 134 known
-publications > tugboat Dash 136 unknown
-publications > tugboat acro 137 known
-publications > tugboat LaTeX 209 known
-publications > tugboat TeX 856 known
-
-publications > stop used btx commands
-\stoptyping
-% publications > stop used btx commands
-%-> "publications > stop used dataset commands"?
-
-Some are flagged as known and others as unknown.
-You can define unknown commands, or overload existing definitions in the
-standard way ({\it e.g.} \type {\def\Dash{—}}) or, alternatively, in the
-following way:
-
-\startTEX
-\definebtxcommand\TUB {TUGboat}
-\definebtxcommand\MP {METAPOST}
-\definebtxcommand\sltt{\tt}
-\definebtxcommand\<#1>{\type{#1}}
-\stopTEX
-\definebtxcommand\MP {METAPOST} % to be used silently below
-
-Custom commands created using \type {\definebtxcommand} have the advantage of
-using a separate name space thus allowing isolation from other \CONTEXT\ commands.
-Unknown commands do not stall processing, but their names are then typeset in a
-mono|-|spaced font so they probably stand out for proofreading. You can
-access the commands with \type {\btxcommand {...}}, as in:
-
-\startbuffer
-commands like \btxcommand{MySpecialCommand} are handled in an indirect way
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-As this is an undefined command we get: \quotation {\inlinebuffer}.
-
-\blank
-
-Finally, the \BIBTEX\ entry \type{@String{}} is preprocessed as expected.%
-\startfootnote
-Notice that \type {tugboat.bib} also contains:
-
-\type {@Preamble{"\input tugboat.def"}}
-
-\type {@Preamble{"\input path.sty"}}
-
-These are silently ignored as many such commands are most likely not to be
-compatible with \CONTEXT, indeed, these ones are not!
-\stopfootnote
-
-\starttyping
-@String{j-TUGboat = "TUGboat"}
-\stoptyping
-
-\stopchapter
-
-\startchapter[title=Datasets]
-
-Normally in a document you will use only one bibliographic database, whether or
-not distributed over multiple files. Nevertheless we support multiple databases as well
-which is why we talk of datasets instead. The use of multiple datasets allows the
-isolation of different bibliographies (a single bibliography can nevertheless be
-isolated by structure element: section, chapter, part, etc. as we shall see later).
-
-A dataset is initiated with the \type
-{\definebtxdataset} command.
-
-\startTEX
-\definebtxdataset[standard]
-\stopTEX
-
-Although currently a new dataset will be implicitly defined%
-\startfootnote
-\type {standard} is the predefined default database name.
-\stopfootnote
-it is best do this explicitly because in the future we may provide more options.
-And like other commands in \CONTEXT, the dataset options can be setup using the
-command \type{\setupbtxdataset}.
-
-A dataset is loaded with the \type {\usebtxdataset} command.
-Here are some examples:
-
-\startTEX
-\usebtxdataset[standard][tugboat.bib]
-\usebtxdataset[standard][mtx-bibtex-output.xml]
-\usebtxdataset[standard][test-001-btx-standard.lua]
-\usebtxdataset[standard][named.buffer]
-\stopTEX
-
-These three suffixes are understood by the loader. Here the dataset has the name
-\type {standard} and the three database files are merged, where later entries having the
-same tag overload previous ones.%
-\startfootnote
-\red
-Question: should entries having the same tag overload previous entries, or should
-they rather be treated as if they had no tag? Are warnings produced in the log file?
-
-Second question: are the suffixes important (or is the data format itself recognized)?
-\stopfootnote
-\startfootnote
-The fourth example shows that a \type {named} buffer can also be employed to add dataset
-entries. This may be useful for small additions or examples, but it is generally a good
-idea (for convenience of management of data) to place them in files separate from the
-document source code.
-\stopfootnote
-Definitions in the document source (coded in \TEX\
-speak) are also added, and they are saved for successive runs. This means that if
-you load and define entries, they will be known at a next run beforehand, so that
-references to them are independent of when loading and definitions take place.
-This is convenient to eventually break-up the dataset loading calls to relevant
-sections of the document structure.
-
-\showsetup{setupbtxdataset}
-
-\showsetup{definebtxdataset}
-
-\showsetup{usebtxdataset}
-
-\startplacetable[reference=tab:test.bib,
- title=The example database file {\type {test.bib}},
- location=right]
- \small\small
- \startframed[align=text]%height=.4\textheight]
- %\typefile[file][range={5,33},before=,after=]{test.bib} % range??
- \executesystemcommand{head -n 33 test.bib | tail -n 29 > testhead.bib} % ugh!
- \typefile[file][before=,after=]{testhead.bib}
- \stopframed
-\stopplacetable
-
-In this document we use some example databases, so let's load one of them now:
-
-\startbuffer
-\definebtxdataset[example]
-
-\usebtxdataset[example][test.bib]
-\stopbuffer
-
-\typebuffer[option=TEX] \getbuffer
-
-The beginning of the file \type {test.bib} is shown in \in {table} [tab:test.bib].
-
-(This bibliography database test file contains one entry of each type or category,
-with the key set to the entry type name.)
-
-You can set the current active dataset with
-
-\startbuffer
-\setbtxdataset[example]
-\stopbuffer
-
-\typebuffer[option=TEX] \getbuffer
-
-but most publication|-|related commands accept optional arguments that denote the
-dataset and references to entries can be prefixed with a dataset identifier.. More
-about that later.
-
-You can ask for an overview of entries present in a dataset with:
-
-\startbuffer
-\showbtxdatasetfields[example]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-which gives:
-
-\getbuffer
-
-\page [yes]
-
-The \quote{required} field names are colored in green and when one such field
-is missing from the dataset entry this is indicated in red. Required means that
-if this field is missing, one is probably not using the correct entry type or category.
-Some fields might be mutually exclusive for some categories. For example, a
-\type {@book} would not normally have both an \type {author} and an \type {editor}
-or both a \type {volume} and a \type {number}. {\red Such cases are indicated in orange.}
-Fields that normally would be ignored are colored in {\red xxxx}. The notions of
-required, optional and ignored fields depends in fact on the bibliography rendering
-style. Some, for example, might not use the \type {title} field whereas others
-certainly will. More on this later.
-
-Sometimes you might want to check a database, listing all of its entries. One way of doing that is the following:
-
-\startbuffer
-\showbtxdatasetcompleteness[example]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-The completeness check colors the field names as indicated above. In addition,
-in blue we show what gets inherited. The listing can be rather long.
-
-\getbuffer
-
-\startsection[title=Dataset fields]
-
-Filling a dataset defines a certain number of entries, each having a type or category
-and containing a number of fields. These fields (and entry types) can be anything going
-far beyond the standard (predefined) ones used in \BIBTEX\ bibliography databases.
-How these fields (and categories) will be used depends on the rendering style, discussed
-later.
-
-You can see all (currently known) categories and fields with:%
-\startfootnote
-\red
-The required fields should get red {\ast}...
-\stopfootnote
-
-\starttyping
-\showbtxfields[rotation=...]
-\stoptyping
-
-The result is shown \in {table} [tab:fields].
-
-Just as a database can be much larger than needed for a document, the same is true
-for the fields that make up an entry; not all entry fields will be necessarily used.
-This idea will be developed in the next section describing the rendering of bibliography
-lists.
-
-\startplacetable[title={\type{\showbtxfields[rotation=90]}},reference=tab:fields]
- \showbtxfields[rotation=90]
-\stopplacetable
-
-\stopsection
-
-\stopchapter
-
-\startchapter[title=Renderings]
-
-A list of publications can be rendered at any place in the document, and multiple
-renderings can appear under certain limitations (according to scope).
-
-If you want to see what publications are in the database, the easiest way is to
-ask for a complete list:%
-\startfootnote
-\red
-\type {sorttype=dataset} gives a \LUA\ error.
-\stopfootnote
-
-\startbuffer
-\definebtxrendering
- [example]
- [dataset=example,
- %sorttype=dataset,
- method=dataset]
-
-\placelistofpublications % \placebtxrendering
- [example]
- [criterium=all]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-This gives:%
-\startfootnote
-\red
-There are several issues here with respect to numbering:
-As the default \type{alternative} is \type {apa}, to be coherent by default
-\type {numbering} should be \type {off} and the citation style should be
-\type {authoryears}. Furthermore, numbering should be local to a dataset
-unless one explicitly asks for global numbering. This is not the case as one
-can see here!
-
-There is also a problem with the year suffixes. The present rendering
-(numbered) should not get suffixes which only makes sense when using
-\type {authoryear} variants.
-\stopfootnote
-\startfootnote
-\red
-Why \type {\blank} before and after when, by default, the list is not packed?
-(Defaults could be: \type {before=\blank,after=\blank,inbetween=\blank})
-We should make this coherent with enumerations (and what about handling options
-such as \type {joinedup}, \type {packed}?)
-\stopfootnote
-
-\blank \getbuffer \blank
-
-Let's try another example (taken from the \goto {TUG bibliography archive}
-[url(http://ftp.math.utah.edu/pub/tex/bib/index.html)]):
-
-\startbuffer
-\definebtxdataset[template]
-\usebtxdataset[template][template.bib]
-
-\definebtxrendering
- [template]
- [dataset=template,
- %?repeat=no,
- %?continue=no,
- method=dataset]
-
-\placelistofpublications
- [template]
- [criterium=all]
-\stopbuffer
-
-\typebuffer[option=TEX]
-\blank % Grr!
-\getbuffer
-
-Notice that the example above contains a reference to an unknown entry
-(\type {Chen:SPE-19-9-897}) as well as an unknown command (\type {\path}).
-
-\blank
-
-The default rendering style is that described in \cite[title][standard::APA2010].
-\cite[standard::APA2010] Often there is a prescribed style to render bibliographic
-descriptions that can be programmed as a standard alternative, for example
-(the default) \type {alternative=apa}. Other styles commonly used in the physical
-sciences and in the biological sciences might be \type{aps} and \type{vancouver}.
-More style schemes will be added in the future.
-The rendering style usually also implies a particular bibliography list sorting
-scheme as well as the use of a citation style. Indeed, the rendering of bibliography
-lists and references to it are intimately coupled. This question will be explained
-a bit later.
-
-The rendering itself is somewhat complex to set up because we have not only many
-different standards but also many fields that can be set up. This means that
-there are several commands involved. A rendering is setup and defined with:
-
-\showsetup[setupbtxrendering]
-
-\showsetup[definebtxrendering]
-
-And a list of such descriptions is generated with:%
-\startfootnote
-\red
-This \type {\showsetup} is missing options?
-\stopfootnote
-
-\showsetup[placebtxrendering]
-
-For example, the APA style specifies that the bibliography list be sorted by
-author and then by year, then by title. The list is not numbered (and references
-are made by author and year). This can be achieved as follows:%
-\startfootnote
-\red
-The year suffixes are incorrect; I cannot figure out in what order they
-are generated here!
-\stopfootnote
-
-\startbuffer
-\definebtxrendering
- [altexample]
- [dataset=example,
- sorttype=authoryear,
- numbering=no,
- method=dataset]
-
-\placebtxrendering
- [altexample]
- [criterium=all]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-\blank \getbuffer \blank
-
-So a dataset can by used with multiple renderings. The most obvious use of
-this feature is the placement of bibliography lists localized by structure
-elements: parts, chapters in a book, sections, etc. through the option
-\type {criterium=chapter}, for example.
-
-Only the default rendering definition (\type {alternative=apa}) is loaded
-automatically. Other schemes are made available either by defining them
-(as described in the following section) or by loading a predefined set of
-definitions:
-
-\startbuffer
-\loadbtxdefinitionfile[aps]
-
-\definebtxrendering
- [anotherexample]
- [dataset=example,
- method=dataset,
- alternative=aps]
-
-% aps is presently broken :(
-%\placebtxrendering
-% [anotherexample]
-% [criterium=all]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-\blank \getbuffer \blank
-
-The standard rendering alternatives have a small number of global options
-(such as \type {numbering=yes}) that can be used to modify the output.
-New and custom renderings can be written, to be described in detail in a
-later chapter.
-
-The dataset contains entries and each entry is assigned to a category.
-It must be stressed that these \quote{categories} can be of any sort,
-the meaning of which resides in the rendering style that is chosen. The
-entries contain fields, and these too can be of any sort; their use also
-depends on the rendering style and the category in which they belong.
-\BIBTEX\ has conventionally defined a number of standard categories, each
-making use of a number of fields considered either required, optional or
-ignored. However, different traditional \BIBTEX\ rendering styles can make
-inconsistant use of the standard categories and fields. To make matters
-worse, different \type {.bib} database handling programs might use (and
-impose) differing \quote{standards} as well.%
-\startfootnote
-For example, \type {jabref}, in addition to discarding all comments contained
-in the database file, will convert all unrecognized, preciously named categories
-to \type {@Other}!
-\stopfootnote
-This situation arises from the complexity of handling bibliographic data of
-all sorts.
-
-\startsection[title=Language]
-
-Bibliography lists (and citations in the text, see below) are rendered
-in the language of the document (\type {\mainlanguage}). However, a
-bibliography entry can contain a \type {language=} field and this will
-be used (if present) in the rendering and hyphenation of the \type {title},
-for example.
-
-\type{\setupbtxdataset[language=]} ...
-
-\stopsection
-
-\stopchapter
-
-\startchapter[title=Citations]
-
-The rendering of bibliographic lists was described in the previous chapter.
-The APA Style Guide as well as good practice demand that {\em all}
-bibliographical references be cited at least once in the text%
-\startfootnote
-Other publishing styles, textbooks in particular, might also include lists
-of general references for \quote{further reading}.
-\stopfootnote
-(and, of course, all citations must have a corresponding bibliographical reference).
-
-The examples of bibliography listing of the previous chapter were all fairly easy
-since the entire bibliographical dataset was rendered. In practice, the same dataset
-could be used over many documents and it might contain many more references than
-are used in any one document. That is, the data source might be more complete than
-the final rendered bibliography list or lists. The mechanism of citation allows you
-to select references from the dataset(s) to build the list rendering as well as to
-place a rendering of the reference in the text of the document to the corresponding
-list rendering. These renderings can be of many forms.
-
-A citation is normally pretty short as its main purpose is to refer uniquely to a more
-detailed description. But, there are several ways to refer, which is why the citation
-subsystem is configurable and extensible. Just look at the following commands:
-
-\startbuffer
-\cite[num][example::article]
-\cite[year][example::article]
-\cite[title][example::article]
-\cite[author][example::article]
-\cite[authoryear][example::article]
-\stopbuffer
-
-\typebuffer[option=TEX]
-\startlines \getbuffer \stoplines
-
-\startbuffer
-\cite[num][example::article,book]
-\cite[year][example::article,book]
-\cite[title][example::article,book]
-\cite[author][example::article,book]
-\cite[authoryear][example::article,book]
-\stopbuffer
-
-\typebuffer[option=TEX]
-\startlines \getbuffer \stoplines
-
-\startbuffer
-\cite[num][example::book,article]
-\cite[year][example::book,article]
-\cite[title][example::book,article]
-\cite[author][example::book,article]
-\cite[authoryear][example::book,article]
-\stopbuffer
-
-\typebuffer[option=TEX]
-\startlines \getbuffer \stoplines
-
-The citation rendering and the bibliographic list rendering are thus intimately
-coupled reciprocally and cannot be dissociated. The coupling could be through the
-reference number for example, but unnumbered reference lists also contain interacting
-hyperlinks. A failure to take into account this interdependence can lead to fundamental
-misunderstandings in use.%
-\startfootnote
-Both the citation and the list must be rendered. For example, omitting or
-commenting-out the list rendering during the writing stage of a document will cause
-the citations to fail to render properly.
-\stopfootnote
-
-\showsetup[cite]
-
-The first argument is optional and if omitted, the default citation rendering
-(\type {alternative=num}) will be selected.%
-\startfootnote
-The cite variant \type {num} refers to a counter that is usually sequential
-in the order in which citations are called in the running text, with the rendered
-bibliography list sorted in the same order. It is not to be confused with
-\type {number} which corresponds to the bibliographic data field that is also
-available (see below).
-\stopfootnote
-For example, to follow the APA specifications, one would change this default:
-
-\startbuffer
-\setupbtxcitevariant [alternative=authoryear]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-Another common citation setup will enable interaction (disabled by default):
-
-\startbuffer
-\setupbtxcitevariant [interaction=start]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-\showsetup[setupbtxcitevariant]
-
-\startplacetable [reference=tab:citevariants,
- title=Predefined \type {\cite} variants.]
-\startluacode
-local variants = publications.tracers.citevariants
-
-context.starttabulate { "|l|p|" }
- context.NC() context.bold("variant")
- context.NC() context.bold("rendering")
- context.NC() context.NR() context.FL()
- for i=1,#variants do
- local variant = variants[i]
- context.NC() context.type(variant)
- context.NC() context.citation( { variant }, { "example::article" })
- context.NC() context.NR()
- end
-context.stoptabulate()
-\stopluacode
-
-{\red Why are the variants listed here hard-coded in lua when the list is
-in fact dynamic? New variants can be defined, either based on known variants
-or else flushing a field with the same name name (if found).}
-
-Answer:
-
-\startluacode
-context.starttabulate { "|l|p|" }
- context.NC() context.bold("key")
- context.NC() context.bold("rendering")
- context.NC() context.NR() context.FL()
- for variant in table.sortedhash(publications.tracers.citevariants) do
- context.NC() context.type(variant)
- context.NC() context.citation( { variant }, { "example::demo-005" })
- context.NC() context.NR()
- end
-context.stoptabulate()
-\stopluacode
-
-But, specific variants can have them overloaded:
-
-\startTEX
-% \showinstancevalues[setupbtxcitevariant][author]
-% \showinstancevalues[setupbtxcitevariant][authornum]
-\stopTEX
-
-\startluacode
- for variant in table.sortedhash(publications.tracers.citevariants) do
- context.showinstancevalues( { "btxcitevariant" }, { variant })
- end
-\stopluacode
-
-\stopplacetable
-
-A certain number of citation variants (or alternatives) have been predefined
-(see \in{table} [tab:citevariants]).
-The most commonly used are \type {num} and \type {authoryear} introduced above.
-The first is typically used in conjunction with a numbered bibliography list,
-usually sorted in the citation order in the text; The second is typically used
-in conjunction with a bibliography list sorted by author and year of publication.
-Other variants may be quite useful, even when used in conjunction with the above
-standard schemes. One such example would be \type {\cite[title][key]} that can be
-used to include the title of the work in the running text, another one is
-\type {\cite[year][key]} that can be used to include the publication date or
-\type {\cite[author][key]} that can be used to extract the authors' names. The
-rendering of the variants can be somewhat adjusted through
-\type {\setupbtxcitevariant}, for example modifying (or suppressing) parenthesis
-or activating or deactivating interaction hyperlinks.
-Here we sort by author and color the citation:%
-\startfootnote
-Note that the hyperlinks activated through \type {interaction=start} are colored
-according to their own scheme.
-\stopfootnote
-\startfootnote
-\red
-The sorting does not appear to work here!
-\stopfootnote
-
-\startbuffer
-\setupbtxcitevariant[num] [sorttype=author,color=darkyellow]
-\setupbtxcitevariant[authoryear] [sorttype=author,color=darkyellow]
-
-\citation[num] [example::article,book]
-\citation[authoryear] [example::article,book]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-\startlines \getbuffer \stoplines
-
-\setupbtxcitevariant[num] [color=]
-\setupbtxcitevariant[authoryear][color=]
-
-New cite variants can also be defined, either based on an existing variant or
-referring to a bibliography field of the same name (if found). For example,
-\startbuffer
-\definebtxcitevariant
- [refnum]
- [num]
- [left={Ref.\nbsp},
- right=]
-\cite[refnum][example::book]
-\stopbuffer
-
-\typebuffer [option=TEX]
-
-will yield%
-\startfootnote
-\red
-Why does this not work?? There is something that I do not understand!
-\stopfootnote
-\inlinebuffer.
-
-\showsetup[definebtxcitevariant]
-
-The details behind these cite variants will be described later.
-
-The \type {\citation} command is synonymous to \type {\cite}.%
-\startfootnote
-Note that the \MKII\ module based on \type {bibtex} allowed the use of curly
-brackets enclosing the key (for reasons of backward compatibility with traditional
-\LATEX\ practice). As a consequence, this made it a bit picky about spaces between
-its arguments, the first of which is optional. We have chosen to remove this
-restriction through the use of standard \CONTEXT\ syntax using square brackets,
-reserving curly brackets to be used to enclose text that is to be typeset.
-\stopfootnote
-
-Unless you use \type {criterium=all} {\red (with \type {method=dataset}?)} only publications that are explicitly cited will end up
-in the lists. You can force a citation into a list using \type {\usecitation}, for
-example:%
-\startfootnote
-\red
-How does this differ from \type {\cite[none][example::patent]}?
-\stopfootnote
-
-\startTEX
-\usecitation[example::patent]
-\stopTEX
-
-This command has two synonyms: \type {\nocite} and \type {\nocitation} so you can
-choose whatever fits you best.
-
-\showsetup[usecitation]
-
-\showsetup[nocite]
-
-\showsetup[nocitation]
-
-\startsection[title=Additional text]
-
-Sometimes one would like to include additional text a bibliography list entry,
-for example a specific commentary or page number reference.
-
-left, right, extra, before, after
-
-\startbuffer
-\citation[reference=example::article,lefttext={This is an article:}][foo=bar]
-
-\citation[reference=example::book,righttext={(p. xx)}][foo=bar]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-\getbuffer
-
-\startframed [align=text,framecolor=red,foreground=color,foregroundcolor=red]
-This does not work correctly here as \type {example} is typeset as \type {method=dataset}.
-There is also a question of syntax, since it will not work without including here
-\type {[foo=bar]}. Also, which rendering does this affect (example and/or altexample)?
-
-\blank
-
-Note that the following does work:
-
-\startbuffer
-\citation[reference=tugboat::Hagen:TB32-1-9,
- lefttext={ConTeXt's evolution and milestones in its history: }]
- [foo=bar]
-
-\definebtxrendering[tugboat][dataset=tugboat]
-\placebtxrendering [tugboat][criterium=section]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-\getbuffer
-
-\stopframed
-
-Note that the injection of left and/or right text only makes sense
-when referring to a single list entry.
-
-\stopsection
-
-\startsection[title=Combining citations]
-
-\startbuffer
-\cite[example::article,book,booklet]
-\stopbuffer
-
-A single citation might refer to several sources, obtained through the use of a
-comma separated list of keys, for example: \getbuffer
-
-\typebuffer[option=TEX]
-
-Notice that the comma separated list of three (or more) consecutive numbers gets
-collapsed or compressed into a range of numbers.
-
-Some bibliography styles admit the combination of several bibliographical sources
-into a single list item having a unique reference number.%
-\startfootnote
-The combination of multiple bibliographic entries into as single bibliography list
-item is more compact and this practice is often encountered in short \quote{letter}
-type journal articles.
-\stopfootnote
-To achieve this, one combines keys using the addition operator symbol (+),
-best illustrated though an example:
-
-\startbuffer
-\METAFUN\ began as an expression of love for \METAPOST. \citation
-[tugboat::Berdnikov:TB21-2-129+Hobby:TB21-2-131]
-
-\definebtxrendering[tugboat][dataset=tugboat]
-\placebtxrendering [tugboat][criterium=section]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-\getbuffer
-
-\startframed [align=text,framecolor=red,foreground=color,foregroundcolor=red]
-There are several issues here:
-\startitemize[joinedup,packed]
-\startitem What is with the color darkyellow? \stopitem
-\startitem The separator (;) should suppress the period (.). \stopitem
-\startitem Numbering? \stopitem
-\startitem Automatic handling of tradition \TEX\ quotations (``''). \stopitem
-\startitem The second entry should not appear (see below). \stopitem
-\stopitemize
-\stopframed
-
-Combined entries are joined using a separator that can be specified, as in:
-
-\startbuffer
-\setupbtxrendering[tugboat][separator={ {\emdash} }]
-\stopbuffer
-
-\typebuffer[option=TEX]
-
-or suppressed (using \type {separator=,}); By default \type {separator={; }}.
-
-Beware that dataset entries that are combined cannot also appear apart
-(nor does this really make any logical sense). The following:
-\startbuffer
-\cite[tugboat::Berdnikov:TB21-2-129]
-\cite[tugboat::Berdnikov:TB21-2-129,Hobby:TB21-2-131]
-\cite[tugboat::Hobby:TB21-2-131]
-\stopbuffer
-\typebuffer[option=TEX]
-will yield.%
-\startfootnote
-\red
-I would expect the system to handle this better. All instances of any key that
-appears in a combined reference should refer to this combined reference. Here,
-all three \type{\cite} should give a single (same) number.
-\stopfootnote
-\getbuffer
-This is another instance showing that citations and the rendered bibliography
-list interact and cannot be separated; There are indeed many others.
-
-
-% test:
-
-%\savebtxdataset [tugboat] [tugboat-export.bib] [criterium=section]
-
-\stopsection
-
-\startsection[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 gives 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
-
-\stopsection
-
-\startsection[title=Placing a single citation]
-
-Sometimes, one would like to place a single citation somewhere in the text
-without necessarily adding it to a bibliography list. Take, for example,%
-\startfootnote
-The default rendering style is given by \placecitation[APA2010]
-
-{\red How is this to be controlled?}
-\stopfootnote
-\startbuffer
-\placecitation[tugboat::Mahajan:TB31-1-88]
-\stopbuffer
-\getbuffer
-obtained by using
-\typebuffer[option=TEX]
-
-\stopsection
-
-\stopchapter
-
-\startchapter[title=Custom renderings]
-
-The rendering of citations and bibliography lists is highly configurable and
-custom rendering schemes can be added. The details can get quite complicated
-so we will begin with a description of how citation variations can be used in
-the running text, followed by a description on how to control the rending of
-the associated bibliography list.
-
-\startsection[title=Custom citation renderings]
-
-\startframed [align=text,framecolor=red,foreground=color,foregroundcolor=red]
-This section needs to be developed…
-\stopframed
-
-Because we are dealing with database input and because we generally need to
-manipulate entries, much of the work is delegated to \LUA. This makes it easier
-to maintain and extend the code. Of course \TEX\ still does the rendering. The
-typographic details are controlled by parameters but not all are used in all
-variants. As with most \CONTEXT\ commands, it starts out with a general setup
-command \type {\setupbtxcitevariant}.
-On top of that we can define instances that inherit either from a given parent or
-from the topmost setup using \type {\definebtxcitevariant}.
-
-But, specific variants can have them overloaded:
-
-% \showinstancevalues[setupbtxcitevariant][author]
-% \showinstancevalues[setupbtxcitevariant][authornum]
-
-\startcolumns[n=2]
-\startluacode
- local variants = publications.tracers.citevariants
-
- for i=1,#variants do
- context.showinstancevalues( { "btxcitevariant" }, { variants[i] })
- end
-\stopluacode
-\stopcolumns
-
-A citation variant is defined in several steps and if you really want to know
-the dirty details, you should look into the source code. Here
-we stick to the concept.
-
-\starttyping
-\startsetups btx:cite:author
- \btxcitevariant{author}
-\stopsetups
-\stoptyping
-
-You can overload such setups if needed, but that only makes sense when you cannot
-configure the rendering with parameters. The \type {\btxcitevariant} command is
-one of the build in accessors and it calls out to \LUA\ where more complex
-manipulation takes place if needed. If no manipulation is known, the field with
-the same name (if found) will be flushed. A command like \type {\btxcitevariant}
-assumes that a dataset and specific tag has been set. This is normally done in
-the wrapper macros, like \type {\cite}. For special purposes you can use these
-commands
-
-\starttyping
-\setbtxdataset[example]
-\setbtxentry[hh2013]
-\stoptyping
-
-But don't expect too much support for such low level rendering control.
-
-\stopsection
-
-\startsection[title=Custom list renderings]
-
-\startframed [align=text,framecolor=red,foreground=color,foregroundcolor=red]
-This entire section is complicated and a bit confusing between renderings
-and lists; It needs to be rewritten.
-\stopframed
-
-A dataset can have all kind or categories of entries:
-\startalignment[flushleft,verytolerant,nothyphenated]
-\startluacode
- local categories = publications.tracers.categories
-
- for i=1,#categories do
- if i > 1 then
- context(", ")
- end
- context.type(categories[i]) -- needs to be cast to a string...
- end
-\stopluacode
-\stopalignment
-each having its own rendering variant. To keep things simple we have their settings
-separated. However, these settings are shared for all rendering alternatives.%
-\startfootnote
-In practice this is seldom a problem in a publication as only one rendering
-alternative will be active. If this be not sufficient, you can always group local
-settings in a setup and hook that into the specific rendering.
-\stopfootnote
-
-\showsetup[setupbtxlistvariant]
-\showsetup[definebtxlistvariant]
-
-Examples of list variants are:%
-\startfootnote
-\red
-I do not understand the use of \type {\setupbtxlistvariant}!
-\stopfootnote
-
-\startluacode
- local variants = publications.tracers.listvariants
-
- for i=1,#variants do
- context.showinstancevalues( { "btxlistvariant" }, { variants[i] })
- end
-\stopluacode
-
-\startluacode
- for variant in table.sortedhash(publications.tracers.listvariants) do
- context.showinstancevalues( { "btxlistvariant" }, { variant })
- end
-\stopluacode
-
-The exact rendering of list entries is determined by the \type {alternative} key
-and defaults to \type {apa} which uses definitions from \type
-{publ-imp-apa.mkiv}. If you look at that file you will see that each category has
-its own setup. You may also notice that additional tests are needed to make sure
-that empty fields don't trigger separators and such.
-
-% \showsetup{setuplists}
-
-There are a couple of accessors and helpers to get the job done. When you want to
-fetch a field from the current entry you use \type {\btxfield}. In most cases
-you want to make sure this field has a value, for instance because you don't want
-fences or punctuation that belongs to a field.
-
-\starttyping
-\btxdoif {title} {
- \bold{\btxfield{title}},
-}
-\stoptyping
-
-There are three test macros:
-
-\starttyping
-\btxdoifelse{fieldname}{action when found}{action when not found}
-\btxdoif {fieldname}{action when found}
-\btxdoifnot {fieldname} {action when not found}
-\stoptyping
-
-An extra conditional is available for testing interactivity:
-
-\starttyping
-\btxdoifelseinteraction{action when true}{action when false}
-\stoptyping
-
-In addition there is also a conditional \type {\btxinteractive} which is
-more efficient, although in practice efficiency is not so important here.
-
-There are three commands to flush data:
-
-\starttabulate[|l|l|]
-\NC \type {\btxfield} \NC fetch a explicit field (e.g. \type {year}) \NC \NR
-\NC \type {\btxdetail} \NC fetch a derived field (e.g. \type {short}) \NC \NR
-\NC \type {\btxflush} \NC fetch a derived or explicit field \NC \NR
-\stoptabulate
-
-Normally you can use \type {\btxfield} or \type {\btxflush} as derived fields
-just like analyzed author fields are flushed in a special way. There is
-experimental support for so called manipulators. You can for instance say this:
-
-\starttyping
-\btxflush{lowercase->title}
-\stoptyping
-
-A sequence of manipulators is applied to fetched field, where a sequence is one
-or more manipulators:
-
-\starttyping
-\btxflush{stripperiod->uppercase->title}
-\stoptyping
-
-Some actions are recognized (built-in) but you can also use actions from other
-namespaces, like in:
-
-\starttyping
-\btxflush{converters.Word -> title}
-\stoptyping
-
-Watch how we can use spaces around the \type {->} which is nicer for wrapped
-around usage. Eventually, we might put some more function in the default
-namespace.
-
-You can improve readability by using setups, for instance:
-
-\starttyping
-\btxdoifelse {author} {
- \btxsetup{btx:apa:author:yes}
-} {
- \btxsetup{btx:apa:author:nop}
-}
-\stoptyping
-
-Keep in mind that normally you don't need to mess with definitions like this
-because standard rendering styles are provided. These styles use a few helpers
-that inject symbols but also take care of leading and trailing spaces:
-
-\starttabulate[|||]
-\NC \type {\btxspace } \NC before \btxspace after \NC \NR
-\NC \type {\btxperiod } \NC before \btxperiod after \NC \NR
-\NC \type {\btxcomma } \NC before \btxcomma after \NC \NR
-\NC \type {\btxlparent } \NC before \btxlparent after \NC \NR
-\NC \type {\btxrparent } \NC before \btxrparent after \NC \NR
-\NC \type {\btxleftparenthesis}
-\NC before \btxleftparenthesis after \NC \NR
-\NC \type {\btxrightparenthesis}
-\NC before \btxrightparenthesis after \NC \NR
-\NC \type {\btxrightparenthesiscomma}
-\NC before \btxrightparenthesiscomma after \NC \NR
-\NC \type {\btxrightparenthesisperiod}
-\NC before \btxrightparenthesisperiod after \NC \NR
-\NC \type {\btxrightparenthesiscomma}
-\NC before \btxrightparenthesiscomma after \NC \NR
-\NC \type {\btxrightparenthesisperiod}
-\NC before \btxrightparenthesisperiod after \NC \NR
-\NC \type {\btxleftbracket}
-\NC before \btxleftbracket after \NC \NR
-\NC \type {\btxrightbracket}
-\NC before \btxrightbracket after \NC \NR
-\NC \type {\btxrightbracketcomma}
-\NC before \btxrightbracketcomma after \NC \NR
-\NC \type {\btxrightbracketperiod}
-\NC before \btxrightbracketperiod after \NC \NR
-\stoptabulate
-
-So, the previous example setup can be rewritten as:
-
-\starttyping
-\btxdoif {title} {
- \bold{\btxfield{title}}
- \btxcomma
-}
-\stoptyping
-
-There is a special command for rendering a (combination) of authors:
-
-\starttyping
-\btxflushauthor{author}
-\btxflushauthor{editor}
-\btxflushauthor[inverted]{editor}
-\stoptyping
-
-Instead of the last one you can also use:
-
-\starttyping
-\btxflushauthorinverted{editor}
-\stoptyping
-
-You can use a (configurable) default or pass directives: Valid directives are
-
-\starttabulate
-\NC \bf conversion \NC \bf rendering \NC \NR
-\HL
-\NC \type{inverted} \NC the Frog jr, Kermit \NC \NR
-\NC \type{invertedshort} \NC the Frog jr, K \NC \NR
-\NC \type{normal} \NC Kermit, the Frog, jr \NC \NR
-\NC \type{normalshort} \NC K, the Frog, jr \NC \NR
-\stoptabulate
-
-The list itself is not a list in the sense of a regular \CONTEXT\ structure related
-list. We do use the list mechanism to keep track of used entries but that is mostly
-because we can then reuse filtering mechanisms. The actual rendering of a reference
-and entry runs on top of so called constructions (other examples of constructions are
-descriptions, enumerations and notes).
-
-\showsetup[setupbtxlist]
-
-You need to be aware what command is used to achieve the desired result. For instance,
-in order to put parentheses around a number reference you say:
-
-\starttyping
-\setupbtxlistvariant
- [num]
- [left=(,
- right=)]
-\stoptyping
-
-If you want automated width calculations, the following does the trick:
-
-\starttyping
-\setupbtxrendering
- [standard]
- [width=auto]
-\stoptyping
-
-but if you want to control it yourself you say something:
-
-\starttyping
-\setupbtxrendering
- [width=none]
-
-\setupbtxlist
- [standard]
- [width=3cm,
- distance=\emwidth,
- color=red,
- headcolor=blue,
- headalign=flushright]
-\stoptyping
-
-In most cases the defaults will work out fine.
-
-Normally the references are numbered using one counter for the whole
-document. If you want each list to have its own number, then you can
-set the \type {continue} parameter:
-
-\starttyping
-\setupbtxrendering[continue=no]
-\stoptyping
-
-In a similar fashion you can influence if references are included only once
-of in each list:
-
-\starttyping
-\setupbtxrendering[repeat=yes]
-\stoptyping
-
-\stopsection
-
-\stopchapter
-
-\startchapter[title=Exporting datasets]
-
-\stopchapter
-
-\startchapter[title=The \LUA\ view]
-
-Because we manage data at the \LUA\ end it is tempting to access it there for
-other purposes. This is fine as long as you keep in mind that aspects of the
-implementation may change over time, although this is unlikely once the modules
-become stable.
-
-The entries are collected in datasets and each set has a unique name. In this
-document we have the set named \type {example}. A dataset table has several
-fields, and probably the one of most interest is the \type {luadata} field. Each
-entry in this table describes a publication:
-
-\startluacode
- context.tocontext(publications.datasets.example.luadata["demo-001"])
-\stopluacode
-
-This is \type {publications.datasets.example.luadata["demo-001"]}. There can be
-a companion entry in the parallel \type {details} table.
-
-\startluacode
- context.tocontext(publications.datasets.example.details["demo-001"])
-\stopluacode
-
-These details are accessed as \type
-{publications.datasets.example.details["demo-001"]} and by using a separate table
-we can overload fields in the original entry without losing the original.
-
-You can loop over the entries using regular \LUA\ code combined with \MKIV\
-helpers:
-
-\startbuffer
-local dataset = publications.datasets.example
-
-context.starttabulate { "|l|l|l|" }
-for tag, entry in table.sortedhash(dataset.luadata) do
- local detail = dataset.details[tag] or { }
- context.NC() context.type(tag)
- context.NC() context(detail.short)
- context.NC() context(entry.title)
- context.NC() context.NR()
-end
-context.stoptabulate()
-\stopbuffer
-
-\typebuffer
-
-This results in:
-
-\ctxluabuffer
-
-You can manipulate a dataset after loading. Of course this assumes that you know
-what kind of content you have and what you need for rendering. As example we
-load a small dataset.
-
-\startbuffer
-\definebtxdataset[drumming]
-\usebtxdataset[drumming][mkiv-publications.lua]
-\stopbuffer
-
-\typebuffer \getbuffer
-
-Because we're going to do some \LUA, we could also have loaded the dataset
-with:
-
-\starttyping
-publications.load("drumming","mkiv-publications.lua","lua")
-\stoptyping
-
-The dataset has three entries:
-
-\typefile{mkiv-publications.lua}
-
-As you can see, we can have a subtitle. We will combine the title and subtitle
-into one:
-
-\startbuffer
-\startluacode
-local luadata = publications.datasets.drumming.luadata
-
-for tag, entry in next, luadata do
- if entry.subtitle then
- if entry.title then
- entry.title = entry.title .. ", " .. entry.subtitle
- else
- entry.title = entry.subtitle
- end
- entry.subtitle = nil
- logs.report("btx",
- "combining title and subtitle of entry tagged %a into %a",
- tag,entry.title)
- end
-end
-\stopluacode
-\stopbuffer
-
-\typebuffer \getbuffer
-
-As a hash comes in a different order each run (something that demands a lot
-of care in multipsass workflows that save data in between), we can use this
-instead:
-
-\starttyping
-\startluacode
-local ordered = publications.datasets.drumming.ordered
-
-for i=1,#ordered do
- local entry = ordered[i]
- if entry.subtitle then
- if entry.title then
- entry.title = entry.title .. ", " .. entry.subtitle
- else
- entry.title = entry.subtitle
- end
- entry.subtitle = nil
- logs.report("btx",
- "combining title and subtitle of entry tagged %a into %a",
- entry.tag,entry.title)
- end
-end
-\stopluacode
-\stoptyping
-
-This loops processes in the order of definition. You can also sort by tag:
-
-\starttyping
-\startluacode
-local luadata = publications.datasets.drumming.luadata
-
-for tag, entry in table.sortedhash(luadata) do
- if entry.subtitle then
- if entry.title then
- entry.title = entry.title .. ", " .. entry.subtitle
- else
- entry.title = entry.subtitle
- end
- entry.subtitle = nil
- logs.report("btx",
- "combining title and subtitle of entry tagged %a into %a",
- entry.tag,entry.title)
- end
-end
-\stopluacode
-\stoptyping
-
-We can now typeset the entries with:
-
-\startbuffer
-\definebtxrendering[drumming][dataset=drumming,method=dataset]
-\placebtxrendering[drumming]
-\stopbuffer
-
-\typebuffer
-
-Because we just want to show the entries, and have no citations that force them
-to be shown, we have to the \type {method} to \type {dataset}. \footnote {Gavin
-Harrison is in my opinion one of the most creative, diverse and interesting
-drummers of our time. It's also fascinating to watch him play and a welcome
-distraction from writing code and manuals.}
-
-\blank \getbuffer \blank
-
-\stopchapter
-
-\startchapter[title=The \XML\ view]
-
-The \type {luadata} table can be converted into an \XML\ representation. This is
-a follow up on earlier experiments with an \XML|-|only approach. I decided in the end
-to stick to a \LUA\ approach and provide some simple \XML\ support in addition.
-
-Once a dataset is accessible as \XML\ tree, you can use the regular \type {\xml...}
-commands. We start with loading a dataset, in this case from just one file.
-
-%\startbuffer
-%\usebtxdataset[tugboat][tugboat.bib]
-%\stopbuffer
-%
-%\typebuffer %\getbuffer
-
-The dataset has to be converted to \XML:
-
-\startbuffer
-\convertbtxdatasettoxml[tugboat]
-\stopbuffer
-
-broken...%\typebuffer \getbuffer
-
-The tree is now accessible by its root reference \type {btx:tugboat}. If we want simple
-field access we can use a few setups:
-
-\startbuffer
-\startxmlsetups btx:initialize
- \xmlsetsetup{#1}{bibtex|entry|field}{btx:*}
- \xmlmain{#1}
-\stopxmlsetups
-
-\startxmlsetups btx:field
- \xmlflushcontext{#1}
-\stopxmlsetups
-
-\xmlsetup{btx:tugboat}{btx:initialize}
-\stopbuffer
-
-\typebuffer \getbuffer
-
-The two setups are predefined in the core already, but you might want to change them. They are
-applied in for instance:
-
-\startbuffer
-\starttabulate[|||]
- \NC \type {tag} \NC \xmlfirst {btx:tugboat}
- {/bibtex/entry[string.find(@tag,'Hagen')]/attribute('tag')}
- \NC \NR
- \NC \type {title} \NC \xmlfirst {btx:tugboat}
- {/bibtex/entry[string.find(@tag,'Hagen')]/field[@name='title']}
- \NC \NR
-\stoptabulate
-\stopbuffer
-
-\typebuffer \getbuffer
-
-\startbuffer
-\startxmlsetups btx:demo
- \xmlcommand
- {#1}
- {/bibtex/entry[string.find(@tag,'Hagen')][1]}{btx:table}
-\stopxmlsetups
-
-\startxmlsetups btx:table
-\starttabulate[|||]
- \NC \type {tag} \NC \xmlatt{#1}{tag} \NC \NR
- \NC \type {title} \NC \xmlfirst{#1}{/field[@name='title']} \NC \NR
-\stoptabulate
-\stopxmlsetups
-
-\xmlsetup{btx:tugboat}{btx:demo}
-\stopbuffer
-
-\typebuffer \getbuffer
-
-Here is another example:
-
-\startbuffer
-\startxmlsetups btx:row
- \NC \xmlatt{#1}{tag}
- \NC \xmlfirst{#1}{/field[@name='title']}
- \NC \NR
-\stopxmlsetups
-
-\startxmlsetups btx:demo
- \xmlfilter {#1} {
- /bibtex
- /entry[@category='article']
- /field[@name='author'
- and (find(text(),'Knuth') or find(text(),'DEK'))]
- /../command(btx:row)
- }
-\stopxmlsetups
-
-\starttabulate[|||]
- \xmlsetup{btx:tugboat}{btx:demo}
-\stoptabulate
-\stopbuffer
-
-\typebuffer \getbuffer
-
-A more extensive example is the following. Of course this assumes that you
-know what \XML\ support mechanisms and macros are available.
-
-\startbuffer
-\startxmlsetups btx:getkeys
- \xmladdsortentry{btx}{#1}{\xmlfilter{#1}{/field[@name='author']/text()}}
- \xmladdsortentry{btx}{#1}{\xmlfilter{#1}{/field[@name='year' ]/text()}}
- \xmladdsortentry{btx}{#1}{\xmlatt{#1}{tag}}
-\stopxmlsetups
-
-\startxmlsetups btx:sorter
- \xmlresetsorter{btx}
- % \xmlfilter{#1}{entry/command(btx:getkeys)}
- \xmlfilter{#1}{
- /bibtex
- /entry[@category='article']
- /field[@name='author' and find(text(),'Knuth')]
- /../command(btx:getkeys)}
- \xmlsortentries{btx}
- \starttabulate[||||]
- \xmlflushsorter{btx}{btx:entry:flush}
- \stoptabulate
-\stopxmlsetups
-
-\startxmlsetups btx:entry:flush
- \NC \xmlfilter{#1}{/field[@name='year' ]/context()}
- \NC \xmlatt{#1}{tag}
- \NC \xmlfilter{#1}{/field[@name='author']/context()}
- \NC \NR
-\stopxmlsetups
-
-\xmlsetup{btx:tugboat}{btx:sorter}
-\stopbuffer
-
-\typebuffer \getbuffer
-
-The original data is stored in a \LUA\ table, hashed by tag. Starting with \LUA\ 5.2
-each run of \LUA\ gets a different ordering of such a hash. In older versions, when you
-looped over a hash, the order was undefined, but the same as long as you used the same
-binary. This had the advantage that successive runs, something we often have in document
-processing gave consistent results. In today's \LUA\ we need to do much more sorting of
-hashes before we loop, especially when we save multi||pass data. It is for this reason
-that the \XML\ tree is sorted by hash key by default. That way lookups (especially
-the first of a set) give consistent outcomes.
-
-\stopchapter
-
-\startchapter[title=Standards]
-
-The rendering of bibliographic entries is often standardized and prescribed by
-the publisher. If you submit an article to a journal, normally it will be
-reformatted (or even re|-|keyed) and the rendering will happen at the publishers
-end. In that case it may not matter how entries were rendered when writing the
-publication, because the publisher will do it his or her way.
-This means that most users probably will stick to the standard \APA\ rules and for
-them we provide some configuration. Because we use setups it is easy to overload
-specifics. If you really want to tweak, best look in the files that deal with it.
-
-Many standards exist and support for other renderings may be added to the core.
-Interested users are invited to develop and to test alternate standard renderings
-according to their needs.
-
-Todo: maybe a list of categories and fields.
-
-\stopchapter
-
-\startchapter[title=Cleaning up]
-
-Although the \BIBTEX\ format is reasonably well defined, in practice there are
-many ways to organize the data. For instance, one can use predefined string
-constants that get used (either or not combined with other strings) later on. A string
-can be enclosed in curly braces or double quotes. The strings can contain \TEX\ commands
-but these are not standardized. The databases often have somewhat complex
-ways to deal with special characters and the use of braces in their definition is also
-not normalized.
-
-The most complex to deal with are the fields that contain names of people. At some point it
-might be needed to split a combination of names into individual ones that then get split into
-title, first name, optional inbetweens, surname(s) and additional: \type {Prof. Dr. Alfred
-B. C. von Kwik Kwak Jr. II and P. Q. Olet} is just one example of this. The convention seems
-to be not to use commas but \type {and} to separate names (often each name will be specified
-as lastname, firstname).
-
-We don't see it as challenge nor as a duty to support all kinds of messy definitions. Of
-course we try to be somewhat tolerant, but you will be sure to get better results if you
-use nicely setup, consistent databases.
-
-Todo: maybe some examples of bad.
-
-\stopchapter
-
-\startchapter[title=Transition]
-
-In the original bibliography support module usage was as follows (example taken
-from the contextgarden wiki):
-
-\starttyping
-% engine=pdftex
-
-\usemodule[bib]
-\usemodule[bibltx]
-
-\setupbibtex
- [database=xampl]
-
-\setuppublications
- [numbering=yes]
-
-\starttext
- As \cite [article-full] already indicated, bibtex is a \LATEX||centric
- program.
-
- \completepublications
-\stoptext
-\stoptyping
-
-For \MKIV\ the modules were partly rewritten and ended up in the core so the two
-{\usemodule} commands were no longer needed. The overhead associated with the
-automatic loading of the bibliography macros can be neglected these days, so
-standardized modules such as \type {bib} are all being moved to the core and do
-not need to be explicitly loaded.
-
-The first \type {\setupbibtex} command in this example is needed to bootstrap
-the process: it tells what database has to be processed by \BIBTEX\ between
-runs. The second \type {\setuppublications} command is optional. Each citation
-(tagged with \type {\cite}) ends up in the list of publications.
-
-In the new approach we no longer use \BIBTEX so we don't need to setup \BIBTEX.
-Instead we define dataset(s). We also no longer set up publications with one
-command, but have split that up in rendering-, list-, and cite|-|variants. The
-basic \type {\cite} command remains. The above example becomes:
-
-\starttyping
-\definebtxdataset
- [document]
-
-\usebtxdataset
- [document]
- [mybibfile.bib]
-
-\definebtxrendering
- [document]
-
-\setupbtxrendering
- [document]
- [numbering=yes]
-
-\starttext
- As \cite [article-full] already indicated, bibtex is a \LATEX||centric
- program.
-
- \completebtxrendering[document]
-\stoptext
-\stoptyping
-
-So, we have a few more commands to set up things. If you intend to use just a
-single dataset and rendering, the above preamble can be simplified to:
-
-\starttyping
-\usebtxdataset
- [mybibfile.bib]
-
-\setupbtxrendering
- [numbering=yes]
-\stoptyping
-
-But keep in mind that compared to the old \MKII\ derived method we have moved
-some of the options to the rendering, list and cite setup variants.
-
-Another difference is now the use of lists. When you define a rendering, you
-also define a list. However, all entries are collected in a common list tagged
-\type {btx}. Although you will normally configure a rendering you can still set
-some properties of lists, but in that case you need to prefix the list
-identifier. In the case of the above example this is \type {btx:document}.
-
-\stopchapter
-
-\startchapter[title=\MLBIBTEX]
-
-Todo: how to plug in \MLBIBTEX\ for sorting and other advanced operations.
-
-\stopchapter
-
-\startchapter[title=Extensions]
-
-As \TEX\ and \LUA\ are both open and accessible in \CONTEXT\ it is possible to
-extend the functionality of the bibliography related code. For instance, you can add
-extra loaders.
-
-\starttyping
-function publications.loaders.myformat(dataset,filename)
- local t = { }
- -- Load data from 'filename' and convert it to a Lua table 't' with
- -- the key as hash entry and fields conforming the luadata table
- -- format.
- loaders.lua(dataset,t)
-end
-\stoptyping
-
-This then permits loading a database (into a dataset) with the command:
-
-\starttyping
-\usebtxdataset[standard][myfile.myformat]
-\stoptyping
-
-The \type {myformat} suffix is recognized automatically. If you want to use another
-suffix, you can do this:
-
-\starttyping
-\usebtxdataset[standard][myformat::myfile.txt]
-\stoptyping
-
-If you want to add information to an entry at runtime you can pass so called user
-variables with the \type {\cite} command. The following example demonstrates
-this. First we define a dataset:
-
-\startbuffer
-\startbuffer [knuth]
-@Book{knuth-texbook,
- title = {The TeXbook},
- author = {Knuth, Donald Ervin},
- isbn = {0-201-13447-0},
- series = {Computers {\&} Typesetting},
- volume = {A},
- year = {1986},
- publisher = {Addison Wesley},
- address = {Reading, MA},
-}
-\stopbuffer
-
-\definebtxdataset[knuth]
-\usebtxdataset [knuth] [knuth.buffer]
-\definebtxrendering[knuth][dataset=knuth]
-\stopbuffer
-
-\typebuffer \getbuffer
-
-\startbuffer[setup]
-\startsetups btx:apa:lefttext
- \currentbtxlefttext
- \btxspace
- \btxdoifelseuservariable {notabene} {
- {\bs \currentbtxuservariable{notabene}}
- } {
- % nothing
- }
- \btxspace
-\stopsetups
-\stopbuffer
-
-\getbuffer[setup]
-
-\startbuffer
-We all know the \TeX book by Don Knuth \citation [reference=knuth::knuth-texbook,
-lefttext={\bf >}] [notabene=Well known to \TEX\ users:].
-\stopbuffer
-
-We use this example where we use \type {\citation} instead of \type {\cite} because
-it is more tolerant with spaces. Because we pass user variables as second argument
-the first argument also has to be a key|/|value set.
-
-\typebuffer
-
-\blank \getbuffer \blank
-
-The list is typeset using:
-
-\startbuffer
-\placelistofpublications [knuth] [criterium=all]
-\stopbuffer
-
-\typebuffer
-
-and looks like this:
-
-\blank \getbuffer
-
-The injection of the user variables is up to you. Here we hooked it into an
-existing setup that we overload:
-
-\typebuffer[setup]
-
-The \type {lefttext} and \type {righttext} variables are also kept with the
-entry but these are checked for automatically. In this case it means that
-when no \type {lefttext} is specified, the \type {notabene} doesn't show up.
-
-\stopchapter
-
-\startchapter[title=Authors]
-
-The most complicated part of the rendering is authors. The way names are made up
-is quite different and depends on culture, history, country and personal taste.
-For instance, in the Netherlands you seldom see junior or senior being used, but
-in the Unites States this is quite common. Then there is the matter of several
-authors cooperating.
-
-\starttexdefinition TestAuthor#1
- \starttabulate[|lT|p|]
- \HL
- \NC \ttx \rlap {\string\citation[alternative=author,authorconversion=...][#1]} \NC \NC \NR
- \HL
- \NC name \NC \citation[alternative=author,authorconversion=name] [#1] \NC \NR
- \NC normal \NC \citation[alternative=author,authorconversion=normal] [#1] \NC \NR
- \NC normalshort \NC \citation[alternative=author,authorconversion=normalshort] [#1] \NC \NR
- \NC inverted \NC \citation[alternative=author,authorconversion=inverted] [#1] \NC \NR
- \NC invertedshort \NC \citation[alternative=author,authorconversion=invertedshort][#1] \NC \NR
- \HL
- \stoptabulate
-\stoptexdefinition
-
-Herw we give some examples of rendering. The authornames are taken from the
-database, analyzed, split and depending on the demand, reconstructed.
-
-\TestAuthor{example::demo-001}
-\TestAuthor{example::demo-003}
-\TestAuthor{example::demo-003,demo-004}
-\TestAuthor{example::demo-006}
-
-As with all other elements of a bibliographic entry you can also finetune the
-author name. It's one of the reasons why this subsystem is so complex deep down.
-It makes no sense to have a parameter for each aspect, so again we use setups.
-You can tweak individual components. Here we show the user friendly variant, in
-\type {publ-imp-author} you can find an optimized version.
-
-\startsetups btx:cite:author:normal
- \fastsetup{btx:cite:author:concat}
- \doifsomething {\btxauthorfield{firstnames}} {
- \btxauthorfield{firstnames}
- \btxcitevariantparameter{firstnamesep}
- }
- \doifsomething {\btxauthorfield{vons}} {
- \btxauthorfield{vons}
- \doifsomething {\btxauthorfield{surnames}} {
- \btxcitevariantparameter{vonsep}
- }
- }
- \doifsomething {\btxauthorfield{surnames}} {
- \btxauthorfield{surnames}
- \doifsomething {\btxauthorfield{juniors}} {
- \btxcitevariantparameter{juniorsep}
- \btxauthorfield{juniors}
- }
- }
- \fastsetup{btx:cite:author:etaltext}
-\stopsetups
-
-The two concat setups are not shown here. They can be configured using
-parameters: \type {namesep}, \type {lastnamesep}, \type {finalnamesep} and \type
-{etaltext}, so there is seldom a need to adapt them directly.
-
-Instead of the generic author field accessors you can use macro names which is more
-efficient.
-
-\starttabulate[|l|l|]
-\NC \type{\currentbtxinitials} \NC \type{\btxauthorfield{initials}} \NC \NR
-\NC \type{\currentbtxfirstnames} \NC \type{\btxauthorfield{firstnames}} \NC \NR
-\NC \type{\currentbtxvons} \NC \type{\btxauthorfield{vons}} \NC \NR
-\NC \type{\currentbtxsurnames} \NC \type{\btxauthorfield{surnames}} \NC \NR
-\NC \type{\currentbtxjuniors} \NC \type{\btxauthorfield{juniors}} \NC \NR
-\stoptabulate
-
-The advantage of the more verbose ones is that you can use manipulators to
-process them. This might come in handy when a database is inconsistent.
-
-The two parameters \type {etallimit} and \type {etaldisplay} control the
-maximum number of authors displayed ({\em these names can change}).
-
-\stopchapter
-
-\startchapter[title=Journals]
-
-An experimental feature is the ability to load a list of mapping from complete
-journal names to abbreviated forms.
-
-\startbuffer
-\btxloadjournallist[journals.txt] % the jabref list
-
-\btxexpandedjournal {Z. Ökol. Nat.schutz} or
-\btxabbreviatedjournal{Z. Ökol. Nat.schutz} or
-\btxabbreviatedjournal{Z. Ökol. Nat. schutz}
-\stopbuffer
-
-\typebuffer \getbuffer
-
-In this case the text file looks like:
-
-\starttyping
-Zeitschrift für Ökologie und Naturschutz = Z. Ökol. Nat.schutz
-....
-\stoptyping
-
-Instead you can have a \LUA\ file that looks like:
-
-\starttyping
-return {
- ["Zeitschrift für Ökologie und Naturschutz"] = "Z. Ökol. Nat.schutz",
- ...
-}
-\stoptyping
-
-or
-
-\starttyping
-return {
- { "Zeitschrift für Ökologie und Naturschutz", "Z. Ökol. Nat.schutz" },
- ...
-}
-\stoptyping
-
-A file can be saved with:
-
-\starttyping
-\btxsavejournallist[journals.lua]
-\stoptyping
-
-and then loaded again in a second run. For small lists it makes not much sense
-to cache the lists but if you have tens thousands of journals it can be
-considered. Normally loading is can be neglected compared to the run. Anyhow,
-such a list looks like this:
-
-\starttyping
-return {
- ["abbreviations"]={
- ["zeitschriftfürökologieundnaturschutz"] = "Z. Ökol. Nat.schutz",
- },
- ["expansions"]={
- ["zökolnatschutz"] = "Zeitschrift für Ökologie und Naturschutz",
- },
-}
-\stoptyping
-
-In the future \type {mtx-bibtex} might be able to generate such lists (once we know
-what users come up with).
-
-You can add additional entries with:
-
-\starttyping
-\btxaddjournal
- [Zeitschrift für Ökologie und Naturschutz]
- [Z. Ökol. Nat.schutz]
-\stoptyping
-
-As usual with such mechanisms, internally spaces, punctuation and case are
-ignored with a lookup.
-
-There are also two manipulators for journals: \type {expandedjournal} and
-\type {abbreviatedjournal}.
-
-\stopchapter
-
-\startchapter[title=Other use]
-
-Because a bibliography is just a kind of database, you can use the publications
-mechanism for other purposes as well. During the re|-|implementation Mojca came
-up with the following definitions:
-
-\startbuffer
-\startbuffer[duane]
-@IMAGE {tug2013,
- title = "TUG 2013",
- url = "http://tug.org/tug2013/",
- url_image = "http://tug.org/tug2013/tug2013-color-300.jpg",
- url_thumb = "http://tug.org/tug2013/t2013-thumb.jpg",
- description = "Official drawing of the TUG 2013 conference",
- author = "Duane Bibby",
- year = 2013,
- copyright = "TUG",
-}
-
-@IMAGE {tug2014,
- title = "TUG 2014",
- url = "http://tug.org/tug2014/",
- url_image = "http://tug.org/art/tug2014-color.jpg",
- url_thumb = "http://tug.org/tug2014/t2014-thumb.jpg",
- description = "Official drawing of the TUG 2014 conference",
- author = "Duane Bibby",
- year = 2014,
- copyright = "TUG",
-}
-\stopbuffer
-\stopbuffer
-
-\typebuffer \getbuffer
-
-For documentation purposes we can have a definition in a buffer so that we can
-show it verbatim but also load it. The following code defines a dataset, loads
-the buffer and sets up a rendering.
-
-\startbuffer
-\definebtxdataset
- [duane]
-
-\usebtxdataset
- [duane]
- [duane.buffer]
-
-\definebtxrendering
- [duane]
- [dataset=duane,
- method=dataset,
- alternative=duane,
- criterium=all]
-
-\setupbtxlist
- [duane]
- [number=no]
-\stopbuffer
-
-\typebuffer \getbuffer
-
-Instead of for instance \type {apa} we use \type {duane} as alternative. Because
-categrories are rendered with a setup we can do the following:
-
-\startbuffer
-\startsetups btx:duane:image
- \tbox \bgroup
- \bTABLE[offset=1ex]
- \bTR
- \bTD[ny=4]
- \dontleavehmode
- \externalfigure[\btxfield{url_thumb}][width=3cm]
- \eTD
- \bTD \btxfield{title} \eTD
- \eTR
- \bTR
- \bTD \btxfield{author} \eTD
- \eTR
- \bTR
- \bTD \btxfield{description} \eTD
- \eTR
- \bTR
- \bTD
- \goto{high res variant}[url(\btxfield{url_image})]
- \eTD
- \eTR
- \eTABLE
- \egroup
-\stopsetups
-
-\placebtxrendering[duane][criterium=all]
-\stopbuffer
-
-\typebuffer \getbuffer
-
-An alternative rendering is:
-
-\startbuffer
-\startsetups btx:duane:image
- \bgroup
- \bTABLE[offset=1ex]
- \bTR
- \bTD[ny=4]
- \dontleavehmode
- \externalfigure[\btxfield{url_thumb}][width=3cm]
- \eTD
- \bTD
- \bold{\btxfield{title}}
- \blank
- \btxfield{description}
- \blank
- \goto{high res variant}[url(\btxfield{url_image})]
- \eTD
- \eTR
- \eTABLE
- \egroup
-\stopsetups
-
-\placebtxrendering[duane]
-\stopbuffer
-
-\typebuffer \getbuffer
-
-We only get the second rendering because we specified \type {criterium} as
-\type {all}. Future version of \CONTEXT\ will probably provide sorting
-options and ways to plug in additional functionality.
-
-\stopchapter
-
-\startchapter[title=Tracing]
-
-There are several tracing options. If you want to see where a citations refers to and
-where a list entry point back to, you can say:
-
-\starttyping
-\enabletrackers[publications.crosslinks]
-\stoptyping
-
-This injects markers in both places. One list entry can point to multiple citations. The
-other tracers a more for debugging and can generate lots of messages.
-
-\starttyping
-publications
-publications.cite
-publications.cite.missing
-publications.cite.references
-\stoptyping
-
-\stopchapter
-
-\startchapter[title=Summary]
-
-% beware: we use a new dataset for this as we want a full list
-
-\start
-\definebtxdataset [summary]
-\usebtxdataset [summary] [graph.bib]
-\setbtxdataset [summary]
-\definebtxrendering [summary] [dataset=summary]
-
-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
- \setupalign[flushleft]
- \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
-\placebtxrendering[summary][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
-advantage that we stay within the same run. In the traditional approach we had
-roughly the following steps:
-
-\startitemize[packed]
-\startitem the first run information is collected and written to file \stopitem
-\startitem after that run the \BIBTEX\ program converts that file to another one \stopitem
-\startitem successive runs use that data for references and producing lists \stopitem
-\stopitemize
-
-In the \MKIV\ approach the bibliographic database is loaded in memory each run
-and processing also happens each run. On paper this looks less efficient but as
-\LUA\ is quite fast, in practice performance is much better.
-
-Probably most demanding is the treatment of authors as we have to analyze names,
-split multiple authors and reassemble firstnames, vons, surnames and juniors.
-When we sort by author sorting vectors have to be made which also has a penalty.
-However, in practice the user will not notice a performance degradation. We did
-some tests with a list of 500.000 authors, sorted them and typeset them as list
-(producing some 5400 dense pages in a small font and with small margins). This is
-typical one of these cases where using \LUAJITTEX\ saves quite time. On my
-machine it took just over 100 seconds to get this done. Unfortunately not all
-operating systems performed equally well: 32 bit versions worked fine, but 64 bit
-\LINUX\ either crashed (stalled) the machine or ran out of memory rather fast,
-while \MACOSX\ and \WINDOWS\ performed fine. In practice you will never run into
-this, unless you produce massive amounts of bibliographic entries. \LUAJIT\ has
-some benefits but also some drawbacks.
-
-\stopchapter
-
-\startchapter[title=APA files]
-
-Here are the possible fields per category for APA: \footnote{Currently we show
-\type {publ-imp-test.bib} as we need to check things first.}
-
-\definebtxdataset[apadef]
-% \usebtxdataset[apadef][publ-imp-apa.bib]
-\usebtxdataset[apadef][\cldcontext{resolvers.findfile("publ-imp-test.bib")}]
-\showbtxdatasetcompleteness[apadef]
-
-\stopchapter
-
-\stopbodymatter
-
-\startbackmatter
-
-\startchapter[title=Bibliography]
-
-\placelistofpublications [standard] %[criterium=all]
-
-\stopchapter
-
-\stopbackmatter
-
-\writestatus{!!!!!!}{CHECK HYPHENS}
-
-\stopdocument
-
-Todo:
-
-\setuplabeltext[en][reprint=reprint]
-\setuplabeltext[de][reprint=Nachdruck]
-
-note = {\labeltext{reprint} 2004}
-
diff --git a/doc/context/manuals/allkind/mreadme.tex b/doc/context/manuals/allkind/mreadme.tex
deleted file mode 100644
index 22af40afe..000000000
--- a/doc/context/manuals/allkind/mreadme.tex
+++ /dev/null
@@ -1,361 +0,0 @@
-% interface=en output=pdftex language=uk
-%
-% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa
-
-\environment mcommon
-
-\useurl[gpl-simple] [http://creativecommons.org/licenses/GPL/2.0/]
-\useurl[gpl-legal] [http://creativecommons.org/licenses/GPL/2.0/legalcode]
-\useurl[byncsa-simple][http://creativecommons.org/licenses/by-nc-sa/2.5/]
-\useurl[byncsa-legal] [http://creativecommons.org/licenses/by-nc-sa/2.5/legalcode]
-
-\useurl[garden] [http://contextgarden.net]
-\useurl[contextlist] [http://www.ntg.nl/mailman/listinfo/ntg-context]
-\useurl[development] [http://www.ntg.nl/mailman/listinfo/dev-context]
-\useurl[announce] [http://www.ntg.nl/mailman/listinfo/ann-context]
-\useurl[collector] [http://context.literatesolutions.com]
-\useurl[pragma] [http://www.pragma-ade.com]
-\useurl[mirror] [http://context.aanhet.net]
-
-\setupinteraction[state=start]
-
-% copied from cont-log: readme_logo
-
-\startuseMPgraphic{titlepage}{width,height}
- numeric width ; width = \MPvar{width} ;
- numeric height ; height = \MPvar{height} ;
- numeric delta ; delta := width/10 ;
- numeric circle ; circle := 2.5delta ;
- color c ; c := (.2,.4,.6) ;
- path p, q, r ;
- p := unitsquare xscaled width yscaled height ;
- z1 = (delta,height-2delta) ;
- z2 = (width-delta,height-delta) ;
- z3 = (width/2-delta,2delta+circle) ;
- z4 = (x3,delta+circle/2) ;
- q := z1 { dir -15 } .. z2 &
- z2 { dir -105 } .. z3 &
- z3 { dir 135 } .. z1 &
- cycle ;
- r := fullcircle xscaled circle yscaled (.85circle) rotated 15 shifted z4 ;
- pickup pencircle scaled (delta/1.5) ;
- fill p withcolor .50c ;
- fill q withcolor .75c ;
- fill r withcolor .75c ;
- draw p withcolor c ;
- draw q withcolor c ;
- pickup pencircle scaled (delta/2) ;
- draw r withcolor c ;
- setbounds currentpicture to p ;
-\stopuseMPgraphic
-
-\starttext
-
-\TitlePage{titlepage}{90}{Read Me First}{}{1}
-
-\subject {Introduction}
-
-What licence suits best for a \TEX\ like system is a matter of
-taste. Personally we dislike any licence that needs more than a few
-pages of dense legal code to get the message accross. A \TEX\
-related system like \CONTEXT\ is a hybrid of programs, scripts
-and|/|or macro code as well as documentation and sample code,
-including graphics. \TEX\ related systems also have a long
-standing tradition of providing support structures for users. In
-order to make support feasable, a \TEX\ based system like
-\CONTEXT\ assumes a certain logic and structure in the way the
-related files are named and organized in a tree structure. Even a
-small change in one of the elements may let such a system behave
-differently than manuals suggest. Swap a font, change some style
-defaults, leave out some pieces, and users may end up in
-confusion. A licence does not give a user any guarantees!
-
-In order to satisfy those responsible for distributing \CONTEXT,
-we need to choose a licence that makes them feel comfortable.
-Unfortunately we don't feel that comfortable with a licence that does
-not provide the guarantees that a system will not be adapted in
-such ways that the advertised behaviour changes. On the
-other hand, it is the responsibility of those distributing and
-extending the system to make sure that this does not happen.
-However, users should not automatically assume that what they get
-shipped is the same as the original, which is why we stress that
-support (from our side) will only be given on unaltered systems.
-
-First of all, what is \CONTEXT ? It's just a bunch of macros,
-written in \TEX\ and \METAPOST, meant for typesetting documents.
-The macros are accompanied by some scripts, written in \PERL\ (mainly
-the older scripts) \RUBY\ (the official ones) and \LUA\ (for
-embedded usage). The \CONTEXT\ distribution comes with a few fonts,
-files that help manage resources (e.g.\ map files), as well as
-patterns (based on official ones, so this is a derived work).
-
-The \CONTEXT\ distribution is packaged in a zip file organized in
-the \TDS\ structure.
-
-\starttabulate
-\NC \type {cont-tmf.zip} \NC The main distribution. \NC \NR
-\NC \type {cont-img.zip} \NC A few extra resources. \NC \NR
-\NC \type {cont-ext.zip} \NC Third party modules. \NC \NR
-\stoptabulate
-
-When we talk about \CONTEXT\ we also mean its graphical companion
-\METAFUN\ and \FOXET, an \XML\ related product. All these are
-included in the main distribution archive.
-
-The documentation can be downloaded from our website, one of its
-mirrors, the \TEX\ collection as distributed by \TEX\ user groups.
-For some manuals, source code is available in a subversion
-repository. The archives are also kept on \CTAN.
-
-That said, what licence does apply? We need to distinguish between
-things that resemble a program on the one hand and documentation
-on the other hand. We (currently) use a different licence for
-either of them.
-
-\subject {The Code}
-
-The program code (i.e. anything not under the \type {/doc}
-subtree) is distributed under the
-
-\startnarrower
-\goto{Creative Commons GNU GPL}[url(gpl-simple)]
-\stopnarrower
-
-For practical purposes distributers may also choose the \LATEX\
-project licence, which is considered to be a bit more \TEX\
-friendly. (BSD alike licences, the Ruby Licence and the Apache
-are all licences that apply well for \CONTEXT.)
-
-In practice, users may forget about the legal part, if only
-because I haven't even read (and understood) it completely myself,
-so let's stick to what Creative Commons makes of it:
-
-\startcolor[blue]
-The GNU General Public License is a Free Software license. Like
-any Free Software license, it grants to you the four following
-freedoms:
-
-\startitemize
-\item The freedom to run the program for any purpose.
-\item The freedom to study how the program works and adapt it to
- your needs.
-\item The freedom to redistribute copies so you can help your neighbour.
-\item The freedom to improve the program and release your improvements
- to the public, so that the whole community benefits.
-\stopitemize
-
-You may exercise the freedoms specified here provided that you
-comply with the express conditions of this license. The principal
-conditions are:
-
-You must conspicuously and appropriately publish on each copy
-distributed an appropriate copyright notice and disclaimer of
-warranty and keep intact all the notices that refer to this
-License and to the absence of any warranty; and give any other
-recipients of the Program a copy of the GNU General Public License
-along with the Program. Any translation of the GNU General Public
-License must be accompanied by the GNU General Public License.
-
-If you modify your copy or copies of the program or any portion of
-it, or develop a program based upon it, you may distribute the
-resulting work provided you do so under the GNU General Public
-License. Any translation of the GNU General Public License must be
-accompanied by the GNU General Public License.
-
-If you copy or distribute the program, you must accompany it with
-the complete corresponding machine-readable source code or with a
-written offer, valid for at least three years, to furnish the
-complete corresponding machine-readable source code.
-
-Any of these conditions can be waived if you get permission from
-the copyright holder.
-
-Your fair use and other rights are in no way affected by the above.
-\stopcolor
-
-\subject {Recommendations}
-
-Here are a few recommendations in case you want to distribute,
-extend of embed \CONTEXT\ in applications:
-
-\startitemize
-
-\item You can best leave the code base untouched. Most of
-\CONTEXT\ provides hooks and it's relatively easy to overload
-code. Leave the lower level system code untouched: changes may
-backfire when you update. Asking for more hooks is the best way to
-go.
-
-\item Put your own code in the right subpaths, i.e.\ modules
-approved by the development team under \type {.../third}, and
-styles and whatever else under \type {.../user}. This way your
-code will not interfere with existing code and updating will give
-less problems. Keep in mind that \TEX\ systems have their own way
-and order in locating files, and the load order often matters.
-
-\item Don't copy styles and change a few lines, but load the base one
-and built|/|patch on top of that. In the end you may benefit from
-improvements to the base style.
-
-\item Be original. The whole idea behind \CONTEXT\ is that you can
-write your own styles. On the \CONTEXT\ mailing list as well as on
-the Wiki there are enough advanced users to help you make a start.
-
-\item Don't hesitate to submit bugs reports and ask for
-extensions. It may even be that what you want is already present
-but yet undocumented.
-
-\item If things don't work as expected, check to what extend your
-system matches the (more or less) standard. We provide so called
-minimal \CONTEXT\ trees that can serve as a reference. Because
-\CONTEXT\ evolves, make sure your system is up to date.
-
-\item The scripts can best be called using \type {texmfstart}. This
-lessens dependencies on the location in the tree and ensures upward
-compatibility. It also prevents clashes with similary named scripts.
-
-\item Some scripts depend on each other. Don't mess around with the
-existing functionality and names of the scripts and then feed them
-back into the standard distributions.
-
-\stopitemize
-
-\subject {Documents}
-
-The documentation is provided under another Creative Commons licence
-
-\startnarrower
-\goto{Attribution NonCommercial ShareAlike}[url(byncsa-simple)]
-\stopnarrower
-
-This one says:
-
-\startcolor[blue]
-You are free:
-
-\startitemize
-\item to copy, distribute, display, and perform the work
-\item to make derivative works
-\stopitemize
-
-{\sc Attribution:} You must attribute the work in the manner
-specified by the author or licensor.
-
-{\sc NonCommercial:} You may not use this work for commercial
-purposes.
-
-{\sc Share Alike:} If you alter, transform, or build upon this
-work, you may distribute the resulting work only under a license
-identical to this one.
-
-\startitemize
-\item For any reuse or distribution, you must make clear to others
- the license terms of this work.
-\item Any of these conditions can be waived if you get permission from
- the copyright holder.
-\stopitemize
-
-Your fair use and other rights are in no way affected by the above.
-\stopcolor
-
-The non||commercial part is mostly a safeguard. We don't mind if
-user groups distribute printed copies, publish (parts of) manuals
-and|/|or if authors use example code in manuals and books about
-\CONTEXT.
-
-If you distribute \CONTEXT\ and related software on electronic media
-as part of \TEX\ distributions (either or not for money), you may
-also distribute the manuals and their sources in electronic form,
-preferable as provided by the maintainers of \CONTEXT.
-
-Keep in mind that logos and cover designs are not meant to be
-copied. We provide the source code for some manuals, but we don't
-always provide all graphics and other resources. For instance, in
-some manuals we use commercial fonts and you have to buy those
-yourself.
-
-We provide the typeset manuals at our website. Those are the official
-ones. We appreciate it if you do not to distribute manuals compiled
-on your own system as substitutes. The manuals are a showcase for what
-\CONTEXT\ provides. Help us to assure the quality.
-
-\subject {More information}
-
-We're not going to fill \mathematics{n}~pages with legal stuff, so if
-you want to know more, you have to consult the web for the legalities
-mentioned. Here are a few starting points:
-
-\startlines
-\goto{\url[gpl-simple]}[url(gpl-simple)]
-\goto{\url[gpl-legal]}[url(gpl-legal)]
-\stoplines
-
-\startlines
-\goto{\url[byncsa-simple]}[url(byncsa-simple)]
-\goto{\url[byncsa-legal]}[url(byncsa-legal)]
-\stoplines
-
-\CONTEXT\ itself can be fetched from the main site or its primary mirror:
-
-\startlines
-\goto{\url[pragma]}[url(pragma)]
-\goto{\url[mirror]}[url(mirror)]
-\stoplines
-
-A starting point for support can be found at:
-
-\startlines
-\goto{\url[contextlist]}[url(contextlist)]
-\goto{\url[garden]}[url(garden)]
-\stoplines
-
-Bugs and feature requests can be registered at the collector:
-
-\startlines
-\goto{\url[collector]}[url(collector)]
-\stoplines
-
-Releases are announced at:
-
-\startlines
-\goto{\url[announce]}[url(announce)]
-\stoplines
-
-The developers can be met at:
-
-\startlines
-\goto{\url[development]}[url(development)]
-\stoplines
-
-\subject {Disclaimer}
-
-To play safe we include a disclaimer here, taken from the BSD style
-licence. For some reason such a text is in capitals, so \unknown
-
-\start \sc \blue
-THIS SOFTWARE IS PROVIDED BY THE AUTHOR \quotation {AS IS} AND ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-\stop
-
-\unknown\ and don't bother discussing licence issues and related things
-with us for the mere sake of discussing licence stuff.
-
-\blank[2*big]
-
-\startlines
-Hans Hagen
-PRAGMA ADE
-Hasselt NL
-\stoplines
-
-\ColofonPage
-
-\stoptext
diff --git a/doc/context/manuals/allkind/publications-en.xml b/doc/context/manuals/allkind/publications-en.xml
deleted file mode 100644
index 92a4ea31a..000000000
--- a/doc/context/manuals/allkind/publications-en.xml
+++ /dev/null
@@ -1,387 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!-- bibliographies -->
-
-<cd:interface xmlns:cd="http://www.pragma-ade.com/commands" name="publications" language="en" version="2013.12.22">
-
- <!-- datasets -->
-
- <cd:command name="setupbtxdataset" file="publ-ini.mkiv" category="publications" hash="btxdataset">
- <cd:sequence>
- <cd:string value="setupbtxdataset"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1" optional="yes">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:assignments n="2" optional="yes">
- <!-- todo -->
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
- <cd:command name="definebtxdataset" file="publ-ini.mkiv" category="publications" hash="btxdataset">
- <cd:sequence>
- <cd:string value="definebtxdataset"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:assignments n="2" optional="yes">
- <cd:inherit name="setupbtxdataset" n="2"/>
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
- <cd:command name="usebtxdataset" file="publ-ini.mkiv" category="publications" hash="btxdataset">
- <cd:sequence>
- <cd:string value="usebtxdataset"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:keywords n="2">
- <cd:constant type="cd:file"/>
- </cd:keywords>
- </cd:arguments>
- </cd:command>
-
- <!-- rendering -->
-
- <cd:command name="setupbtxrendering" file="publ-ini.mkiv" category="publications" hash="btxrendering">
- <cd:sequence>
- <cd:string value="setupbtxrendering"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1" optional="yes">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:assignments n="2">
- <cd:parameter name="alternative">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="dataset">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="setups">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="method">
- <cd:constant type="local"/>
- <cd:constant type="global"/>
- <cd:constant type="none"/>
- <cd:constant type="force"/>
- </cd:parameter>
- <cd:parameter name="sorttype">
- <cd:constant type="short"/>
- <cd:constant type="reference"/>
- <cd:constant type="dataset"/>
- <cd:constant type="default"/>
- </cd:parameter>
- <cd:parameter name="criterium">
- <cd:constant type="cd:text"/> <!-- todo -->
- </cd:parameter>
- <cd:parameter name="refcommand">
- <cd:constant type="cd:text"/> <!-- todo -->
- </cd:parameter>
- <cd:parameter name="numbering">
- <cd:constant type="yes"/>
- <cd:constant type="cite"/>
- </cd:parameter>
- <cd:parameter name="width">
- <cd:constant type="cd:dimension"/>
- <cd:constant type="auto"/>
- </cd:parameter>
- <cd:parameter name="distance">
- <cd:constant type="cd:dimension"/>
- </cd:parameter>
- <cd:parameter name="continue">
- <cd:constant type="yes"/>
- <cd:constant type="no" default="yes"/>
- </cd:parameter>
- <cd:parameter name="repeat">
- <cd:constant type="yes"/>
- <cd:constant type="no" default="yes"/>
- </cd:parameter>
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
- <cd:command name="definebtxrendering" file="publ-ini.mkiv" category="publications" hash="btxrendering">
- <cd:sequence>
- <cd:string value="definebtxrendering"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:keywords n="2" optional="yes">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:assignments n="3" optional="yes">
- <cd:inherit name="setupbtxrendering" n="2"/>
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
- <cd:command name="placebtxrendering" file="publ-ini.mkiv" category="publications" hash="btxrendering">
- <cd:sequence>
- <cd:string value="placebtxrendering"/>
- </cd:sequence>
- </cd:command>
-
- <!-- lists -->
-
- <cd:command name="setupbtxlistvariant" file="publ-ini.mkiv" category="publications" hash="btxlistvariant">
- <cd:sequence>
- <cd:string value="setupbtxlistvariant"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1" optional="yes">
- <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>
- <cd:parameter name="lastnamesep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="finalnamesep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="firstnamesep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="juniorsep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="vonsep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="surnamesep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="surnamejuniorsep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="juniorjuniorsep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="surnamefirstnamesep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="surnameinitialsep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="etallimit">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="etaldisplay">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="etaltext">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="monthconversion">
- <cd:constant type="number"/>
- <cd:constant type="month"/>
- <cd:constant type="month:mnem"/>
- </cd:parameter>
- <cd:parameter name="authorconversion">
- <cd:constant type="name"/>
- <cd:constant type="normal"/>
- <cd:constant type="inverted"/>
- <cd:constant type="normalshort"/>
- <cd:constant type="invertedshort"/>
- </cd:parameter>
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
- <cd:command name="definebtxlistvariant" file="publ-ini.mkiv" category="publications" hash="btxlistvariant">
- <cd:sequence>
- <cd:string value="definebtxlistvariant"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- </cd:arguments>
- </cd:command>
-
- <!-- variants -->
-
- <cd:command name="setupbtxcitevariant" file="publ-ini.mkiv" category="publications" hash="btxcitevariant">
- <cd:sequence>
- <cd:string value="setupbtxcitevariant"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1" optional="yes">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:assignments n="2">
- <cd:parameter name="alternative">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="setups">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="interaction">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="andtext">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="otherstext">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="compress">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="putsep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="lastputsep">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="inbetween">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="right">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="middle">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="left">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="monthconversion">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="authorconversion">
- <cd:constant type="name"/>
- <cd:constant type="normal"/>
- <cd:constant type="inverted"/>
- <cd:constant type="normalshort"/>
- <cd:constant type="invertedshort"/>
- </cd:parameter>
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
- <cd:command name="definebtxcitevariant" file="publ-ini.mkiv" category="publications" hash="btxcitevariant">
- <cd:sequence>
- <cd:string value="definebtxcitevariant"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:keywords n="2" optional="yes">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:assignments n="3" optional="yes">
- <cd:inherit name="setupbtxvariant" n="3"/>
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
- <!-- refering -->
-
- <cd:command name="cite" file="publ-ini.mkiv" category="publications">
- <cd:sequence>
- <cd:string value="cite"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1" optional="yes">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- <cd:keywords n="2">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- </cd:arguments>
- </cd:command>
-
- <cd:command name="nocite" file="publ-ini.mkiv" category="publications">
- <cd:sequence>
- <cd:string value="nocite"/>
- </cd:sequence>
- <cd:arguments>
- <cd:keywords n="1">
- <cd:constant type="cd:name"/>
- </cd:keywords>
- </cd:arguments>
- </cd:command>
-
- <!-- list entries -->
-
-
- <cd:command name="setupbtxlist" file="publ-ini.mkiv" category="publications" hash="btxlist">
- <cd:sequence>
- <cd:string value="setupbtxlist"/>
- </cd:sequence>
- <cd:arguments>
- <cd:assignments n="1">
- <cd:parameter name="alternative">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="style">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="color">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="headstyle">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="headcolor">
- <cd:constant type="cd:text"/>
- </cd:parameter>
- <cd:parameter name="width">
- <cd:constant type="cd:dimension"/>
- </cd:parameter>
- <cd:parameter name="distance">
- <cd:constant type="cd:dimension"/>
- </cd:parameter>
- <cd:parameter name="hang">
- <cd:constant type="cd:number"/>
- </cd:parameter>
- <cd:parameter name="align">
- <cd:resolve name="align"/>
- </cd:parameter>
- <cd:parameter name="headalign">
- <cd:resolve name="symalign"/>
- </cd:parameter>
- <cd:parameter name="margin">
- <cd:constant type="cd:yes"/>
- <cd:constant type="cd:no"/>
- </cd:parameter>
- <cd:parameter name="before">
- <cd:constant type="cd:command" default="\blank"/>
- </cd:parameter>
- <cd:parameter name="inbetween">
- <cd:constant type="cd:command"/>
- </cd:parameter>
- <cd:parameter name="after">
- <cd:constant type="cd:command" default="\blank"/>
- </cd:parameter>
- <cd:parameter name="display">
- <cd:constant type="cd:yes"/>
- <cd:constant type="cd:no"/>
- </cd:parameter>
- <cd:parameter name="command">
- <cd:constant type="cd:command"/>
- </cd:parameter>
- </cd:assignments>
- </cd:arguments>
- </cd:command>
-
-
-</cd:interface>
diff --git a/doc/context/sources/general/manuals/mcommon.tex b/doc/context/sources/general/manuals/mcommon.tex
new file mode 100644
index 000000000..b6b6026e9
--- /dev/null
+++ b/doc/context/sources/general/manuals/mcommon.tex
@@ -0,0 +1,210 @@
+% content=tex
+%
+% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa
+
+\startenvironment mcommon
+
+% modules
+
+\usemodule[abr-02]
+
+% layout
+
+% \startmode[screen]
+% \setuppapersize[S6][S6]
+% \setupinteractionscreen[options=max]
+% \stopmode
+
+\setuplayout
+ [topspace=15mm,
+ header=15mm,
+ headerdistance=0mm,
+ footer=0cm,
+ width=middle,
+ height=middle]
+
+\setupinteraction
+ [state=start,
+ color=,
+ contrastcolor=,
+ style=]
+
+% fonts
+
+\definetypeface [mainface] [rm] [serif] [pagella] [default]
+\definetypeface [mainface] [ss] [sans] [heros] [default] % [rscale=1.1]
+\definetypeface [mainface] [tt] [mono] [heros] [default] % [rscale=1.1]
+\definetypeface [mainface] [mm] [math] [pagella] [default]
+
+\setupbodyfont[mainface,12pt]
+
+\definefont [BigFont] [SansBold*default at 60pt]
+\definefont [MedFont] [SansBold*default at 30pt]
+
+% colors (historically)
+
+\definecolor [NopColor] [r=.6,g=.4,b=.5]
+\definecolor [AltColor] [r=.4,g=.6,b=.5]
+\definecolor [TheColor] [r=.4,g=.5,b=.6]
+\definecolor [TmpColor] [r=.6,g=.5,b=.4]
+
+\definecolor [NopColor] [r=.40,g=.20,b=.20]
+\definecolor [AltColor] [r=.20,g=.40,b=.20]
+\definecolor [TheColor] [r=.20,g=.20,b=.40]
+\definecolor [TmpColor] [r=.40,g=.40,b=.20]
+
+\definecolor [red] [NopColor]
+\definecolor [green] [AltColor]
+\definecolor [blue] [TheColor]
+\definecolor [yellow][TmpColor]
+
+% spacing
+
+\setupwhitespace
+ [big]
+
+\setuptolerance
+ [verytolerant,stretch]
+
+% verbatim
+
+\setuptype
+ [color=AltColor]
+
+\setuptyping
+ [color=AltColor]
+
+% structure
+
+\setupitemize
+ [each]
+ [color=TheColor]
+
+\definedescription
+ [switch]
+ [headstyle=type,
+ headcolor=TheColor,
+ location=serried,
+ width=broad]
+
+\defineenumeration
+ [topic]
+ [location=serried,
+ width=broad,
+ headstyle=,
+ headcolor=TheColor,
+ text=,
+ left={[},
+ right={]}]
+
+\setuphead
+ [section]
+ [style=\bfb,
+ color=TheColor]
+
+\setuplist
+ [section]
+ [alternative=c,
+ color=TheColor,
+ textcolor=black,
+ pagecolor=black]
+
+% whatever
+
+\setupsystem
+ [random=medium]
+
+\setupfloats
+ [ntop=100]
+
+\setupinteraction
+ [style=,
+ color=NopColor,
+ contrastcolor=NopColor]
+
+% tables and frames
+
+\setuptabulate
+ [rulethickness=.5pt,
+ rulecolor=AltColor]
+
+\setuptables
+ [rulethickness=.5pt,
+ rulecolor=AltColor]
+
+\setupframedtexts
+ [rulethickness=.5pt,
+ framecolor=TheColor,
+ width=\textwidth]
+
+% quick reference things
+
+\usemodule[set-11] \loadsetups
+
+\setupframedtexts
+ [setuptext]
+ [rulethickness=.5pt,
+ framecolor=AltColor]
+
+% titlepage
+
+\startsetups titlepage
+ \defineoverlay
+ [logo]
+ [\useMPgraphic{titlepage}{width=\overlaywidth,height=\overlayheight}]
+ \setupbackgrounds
+ [page]
+ [background=logo]
+ \startstandardmakeup
+ \dontcomplain
+ \BigFont
+ \setupinterlinespace
+ \vfill
+ \setupalign[left]
+ \let\\=\par
+ \dontleavehmode
+ \rotate
+ [rotation=90]
+ {\color
+ [lightgray]
+ {\getvariable{document}{title}}}
+ \par
+ \stopstandardmakeup
+ \setupbackgrounds
+ [page]
+ [background=]
+\stopsetups
+
+\startsetups colofon
+ \blank[2*big]
+ \testpage[3]
+ \startpacked
+ \getvariable{document}{author}\par
+ \getvariable{document}{affiliation}\par
+ \getvariable{document}{location}\par
+ \stoppacked
+\stopsetups
+
+\setupdocument
+ [title=No Title,
+ before=\setups{titlepage},
+ after=\setups{colofon}]
+
+% urls
+
+\useurl[gpl-simple] [http://creativecommons.org/licenses/GPL/2.0/]
+\useurl[gpl-legal] [http://creativecommons.org/licenses/GPL/2.0/legalcode]
+\useurl[byncsa-simple][http://creativecommons.org/licenses/by-nc-sa/2.5/]
+\useurl[byncsa-legal] [http://creativecommons.org/licenses/by-nc-sa/2.5/legalcode]
+
+\useurl[garden] [http://contextgarden.net]
+\useurl[install] [http://wiki.contextgarden.net/ConTeXt_Standalone]
+\useurl[texlive] [http://www.tug.org/texlive/]
+\useurl[group] [http://group.contextgarden.net]
+\useurl[list] [http://www.ntg.nl/mailman/listinfo/ntg-context]
+\useurl[development] [http://www.ntg.nl/mailman/listinfo/dev-context]
+\useurl[announce] [http://www.ntg.nl/mailman/listinfo/ann-context]
+\useurl[collector] [http://tracker.luatex.org]
+\useurl[pragma] [http://www.pragma-ade.com]
+
+\stopenvironment
diff --git a/doc/context/sources/general/manuals/readme/mreadme.tex b/doc/context/sources/general/manuals/readme/mreadme.tex
new file mode 100644
index 000000000..b2af11bc4
--- /dev/null
+++ b/doc/context/sources/general/manuals/readme/mreadme.tex
@@ -0,0 +1,372 @@
+% interface=en engine=luatex language=uk
+%
+% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa
+
+\environment mcommon
+
+% copied from cont-log: readme_logo
+
+\startuseMPgraphic{titlepage}{width,height}
+ numeric width ; width = \MPvar{width} ;
+ numeric height ; height = \MPvar{height} ;
+ numeric delta ; delta := width/10 ;
+ numeric circle ; circle := 2.5delta ;
+ color c ; c := (.2,.4,.6) ;
+ path p, q, r ;
+ p := unitsquare xscaled width yscaled height ;
+ z1 = (delta,height-2delta) ;
+ z2 = (width-delta,height-delta) ;
+ z3 = (width/2-delta,2delta+circle) ;
+ z4 = (x3,delta+circle/2) ;
+ q := z1 { dir -15 } .. z2 & z2 { dir -105 } .. z3 & z3 { dir 135 } .. z1 & cycle ;
+ r := fullcircle xscaled circle yscaled (.85circle) rotated 15 shifted z4 ;
+ pickup pencircle scaled (delta/1.5) ;
+ fill p withcolor .50c ;
+ fill q withcolor .75c ;
+ fill r withcolor .75c ;
+ draw p withcolor c ;
+ draw q withcolor c ;
+ pickup pencircle scaled (delta/2) ;
+ draw r withcolor c ;
+ setbounds currentpicture to p ;
+\stopuseMPgraphic
+
+\startdocument
+ [title={Read Me First},
+ author={Hans Hagen},
+ affiliation={PRAGMA ADE},
+ location={Hasselt NL}]
+
+\startsubject[title={Introduction}]
+
+What licence suits best for a \TEX\ like system is a matter of taste. Personally
+we dislike any licence that needs more than a few pages of dense legal code to
+get the message across. A \TEX\ related system like \CONTEXT\ is a hybrid of
+programs, scripts and|/|or macro code as well as documentation and sample code,
+including graphics. \TEX\ related systems also have a long standing tradition of
+providing support structures for users. In order to make support feasible, a
+\TEX\ based system like \CONTEXT\ assumes a certain logic and structure in the
+way the related files are named and organized in a tree structure. Even a small
+change in one of the elements may let such a system behave differently than
+manuals suggest. Swap a font, change some style defaults, leave out some pieces,
+and users may end up in confusion. A licence does not give a user any guarantees!
+
+In order to satisfy those responsible for distributing \CONTEXT, we need to
+choose a licence that makes them feel comfortable. Unfortunately we don't feel
+that comfortable with a licence that does not provide the guarantees that a
+system will not be adapted in such ways that the advertised behaviour changes. On
+the other hand, it is the responsibility of those distributing and extending the
+system to make sure that this does not happen. However, users should not
+automatically assume that what they get shipped is the same as the original,
+which is why we stress that support (from our side) will only be given on
+unaltered systems.
+
+First of all, what is \CONTEXT ? It's just a bunch of macros, written in \TEX\
+and \METAPOST, meant for typesetting documents. The macros are accompanied by
+some scripts, written in \PERL\ (mainly the older scripts) \RUBY\ (also older
+ones) and \LUA\ (the current fashion). The \CONTEXT\ distribution comes with a
+few fonts, files that help manage resources (e.g.\ map files needed for \MKII),
+as well as patterns (based on official ones, so this is a derived work).
+
+The \CONTEXT\ distribution is packaged in a zip file organized in the \TDS\
+structure.
+
+\starttabulate[|lT|p|]
+\NC \type {cont-tmf.zip} \NC the main distribution that has all relevant files \NC \NR
+\NC \type {cont-tst.7z} \NC a bunch of test files that can also serve as examples \NC \NR
+\NC \type {cont-mpd.zip} \NC a \METAPOST\ to \PDF\ converter (not needed in \CONTEXT) \NC \NR
+\NC \type {cont-ppc.zip} \NC a macro package for typesetting chemistry (not needed in \CONTEXT) \NC \NR
+\NC \type {cont-sci.zip} \NC configuration files for using \CONTEXT\ in the \SCITE\ editor \NC \NR
+\stoptabulate
+
+There are two flavours of \CONTEXT: \MKII\ and \MKIV. The first one is frozen and
+will not be extended. It runs on top of \PDFTEX\ or \XETEX. The \MKIV\ version is
+actively developed and runs on top of \LUATEX\ (an engine that is developed
+alongside \CONTEXT\ but that can also be used for other macro packages).
+
+The documentation can be downloaded from our website or the Wiki. Some manuals
+ship with source code. We might ship more source code but only when the source is
+stable and clean and can serve as an example.
+
+That said, what licence does apply? We need to distinguish between things that
+resemble a program on the one hand and documentation on the other hand. We
+(currently) use a different licence for either of them.
+
+\stopsubject
+
+\startsubject[title={The Code}]
+
+The program code (i.e. anything not under the \type {/doc} subtree) is
+distributed under the
+
+\startnarrower
+\goto{Creative Commons GNU GPL}[url(gpl-simple)]
+\stopnarrower
+
+For practical purposes distributers may also choose the \LATEX\ project licence,
+which is considered to be a bit more \TEX\ friendly. (BSD alike licences, the
+Ruby Licence and the Apache are all licences that apply well for \CONTEXT.)
+
+In practice, users may forget about the legal part, if only because I haven't
+even read (and understood) it completely myself, so let's stick to what Creative
+Commons makes of it:
+
+\startcolor[blue]
+The GNU General Public License is a Free Software license. Like any Free Software
+license, it grants to you the four following freedoms:
+
+\startitemize
+ \startitem
+ The freedom to run the program for any purpose.
+ \stopitem
+ \startitem
+ The freedom to study how the program works and adapt it to your needs.
+ \stopitem
+ \startitem
+ The freedom to redistribute copies so you can help your neighbour.
+ \stopitem
+ \startitem
+ The freedom to improve the program and release your improvements to the
+ public, so that the whole community benefits.
+ \stopitem
+\stopitemize
+
+You may exercise the freedoms specified here provided that you comply with the
+express conditions of this license. The principal conditions are:
+
+You must conspicuously and appropriately publish on each copy distributed an
+appropriate copyright notice and disclaimer of warranty and keep intact all the
+notices that refer to this License and to the absence of any warranty; and give
+any other recipients of the Program a copy of the GNU General Public License
+along with the Program. Any translation of the GNU General Public License must be
+accompanied by the GNU General Public License.
+
+If you modify your copy or copies of the program or any portion of it, or develop
+a program based upon it, you may distribute the resulting work provided you do so
+under the GNU General Public License. Any translation of the GNU General Public
+License must be accompanied by the GNU General Public License.
+
+If you copy or distribute the program, you must accompany it with the complete
+corresponding machine-readable source code or with a written offer, valid for at
+least three years, to furnish the complete corresponding machine-readable source
+code.
+
+Any of these conditions can be waived if you get permission from the copyright
+holder.
+
+Your fair use and other rights are in no way affected by the above.
+\stopcolor
+
+\stopsubject
+
+\startsubject[title={Recommendations}]
+
+Here are a few recommendations in case you want to distribute, extend of embed
+\CONTEXT\ in applications:
+
+\startitemize
+
+\startitem
+ You can best leave the code base untouched. Most of \CONTEXT\ provides hooks
+ and it's relatively easy to overload code. Leave the lower level system code
+ untouched: changes may backfire when you update. Asking for more hooks is the
+ best way to go.
+\stopitem
+
+\startitem
+ Put your own code in the right subpaths, i.e.\ modules approved by the
+ development team under \type {.../third}, and styles and whatever else under
+ \type {.../user}. This way your code will not interfere with existing code
+ and updating will give less problems. Keep in mind that \TEX\ systems have
+ their own way and order in locating files, and the load order often matters.
+\stopitem
+
+\startitem
+ Don't copy styles and change a few lines, but load the base one and
+ built|/|patch on top of that. In the end you may benefit from improvements to
+ the base style.
+\stopitem
+
+\startitem
+ Be original. The whole idea behind \CONTEXT\ is that you can write your own
+ styles. On the \CONTEXT\ mailing list as well as on the Wiki there are enough
+ advanced users to help you make a start.
+\stopitem
+
+\startitem
+ Don't hesitate to submit bugs reports and ask for extensions. It may even be
+ that what you want is already present but yet undocumented.
+\stopitem
+
+\startitem
+ If things don't work as expected, check to what extend your system matches
+ the (more or less) standard. We provide so called minimal \CONTEXT\ trees
+ that can serve as a reference. Because \CONTEXT\ evolves, make sure your
+ system is up to date. The \CONTEXT\ garden provides ways to install and
+ update the standard distribution.
+\stopitem
+
+\startitem
+ The scripts can best be called using \type {mtxrun}. This lessens dependencies
+ on the location in the tree and ensures upward compatibility. It also prevents
+ clashes with similar scripts.
+\stopitem
+
+\startitem
+ Some scripts depend on each other. Don't mess around with the existing
+ functionality and names of the scripts and then feed them back into the
+ standard distributions.
+\stopitem
+
+\stopitemize
+
+\stopsubject
+
+\startsubject[title={Documents}]
+
+The documentation is provided under another Creative Commons licence
+
+\startnarrower
+ \goto{Attribution NonCommercial ShareAlike}[url(byncsa-simple)]
+\stopnarrower
+
+This one says:
+
+\startcolor[blue]
+You are free:
+
+\startitemize
+ \startitem to copy, distribute, display, and perform the work \stopitem
+ \startitem to make derivative works \stopitem
+\stopitemize
+
+{\sc Attribution:} You must attribute the work in the manner specified by the
+author or licensor.
+
+{\sc NonCommercial:} You may not use this work for commercial purposes.
+
+{\sc Share Alike:} If you alter, transform, or build upon this work, you may
+distribute the resulting work only under a license identical to this one.
+
+\startitemize
+ \startitem
+ For any reuse or distribution, you must make clear to others the license
+ terms of this work.
+ \stopitem
+ \startitem
+ Any of these conditions can be waived if you get permission from the
+ copyright holder.
+ \stopitem
+\stopitemize
+
+Your fair use and other rights are in no way affected by the above.
+\stopcolor
+
+The non||commercial part is mostly a safeguard. We don't mind if user groups
+distribute printed copies, publish (parts of) manuals and|/|or if authors use
+example code in manuals and books about \CONTEXT.
+
+If you distribute \CONTEXT\ and related software on electronic media as part of
+\TEX\ distributions (either or not for money), you may also distribute the
+manuals and their sources in electronic form, preferable as provided by the
+maintainers of \CONTEXT.
+
+Keep in mind that logos and cover designs are not meant to be copied. We provide
+the source code for some manuals, but we don't always provide all graphics and
+other resources. For instance, in some manuals we use commercial fonts and you
+have to buy those yourself.
+
+We provide the typeset manuals at our website. Those are the official ones. We
+appreciate it if you do not to distribute manuals compiled on your own system as
+substitutes. The manuals are a showcase for what \CONTEXT\ provides. Help us to
+assure the quality.
+
+\stopsubject
+
+\startsubject[title={More information}]
+
+We're not going to fill \mathematics{n}~pages with legal stuff, so if you want to
+know more, you have to consult the web for the legalities mentioned. Here are a
+few starting points:
+
+\startlines
+\goto{\url[gpl-simple]}[url(gpl-simple)]
+\goto{\url[gpl-legal]}[url(gpl-legal)]
+\stoplines
+
+\startlines
+\goto{\url[byncsa-simple]}[url(byncsa-simple)]
+\goto{\url[byncsa-legal]}[url(byncsa-legal)]
+\stoplines
+
+\CONTEXT\ itself can be fetched from the main site or the garden:
+
+\startlines
+\goto{\url[pragma]}[url(pragma)]
+\goto{\url[install]}[url(install)]
+\stoplines
+
+These always ship the latest versions. Alternatively you can install the whole
+\TEX\ distribution, which is a yearly snapshot:
+
+\startlines
+\goto{\url[texlive]}[url(texlive)]
+\stoplines
+
+A starting point for support can be found at:
+
+\startlines
+\goto{\url[list]}[url(list)]
+\goto{\url[garden]}[url(garden)]
+\stoplines
+
+And of course there is the \CONTEXT\ group:
+
+\startlines
+\goto{\url[group]}[url(group)]
+\stoplines
+
+Bugs and feature requests can be registered at the collector:
+
+\startlines
+\goto{\url[collector]}[url(collector)]
+\stoplines
+
+Releases are announced at:
+
+\startlines
+\goto{\url[announce]}[url(announce)]
+\stoplines
+
+The developers can be met at:
+
+\startlines
+\goto{\url[development]}[url(development)]
+\stoplines
+
+\stopsubject
+
+\startsubject[title={Disclaimer}]
+
+To play safe we include a disclaimer here, taken from the BSD style licence. For
+some reason such a text is always in unreadable capitals, so \unknown
+
+\start \txx \blue
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR \quotation {AS IS} AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+\stop
+
+\unknown\ and don't bother discussing licence issues and related things with us
+for the mere sake of discussing licence stuff.
+
+\stopsubject
+
+\stopdocument
diff --git a/doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex b/doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex
new file mode 100644
index 000000000..fc7a269bb
--- /dev/null
+++ b/doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex
@@ -0,0 +1,335 @@
+% language=uk
+
+% author : Hans Hagen, PRAGMA ADE, NL
+% license : Creative Commons, Attribution-NonCommercial-ShareAlike 3.0 Unported
+
+\usemodule[art-01,abr-02]
+
+\definecolor
+ [maincolor]
+ [r=.4]
+
+\definecolor
+ [extracolor]
+ [g=.4]
+
+\setupbodyfont
+ [11pt]
+
+\setuptype
+ [color=maincolor]
+
+\setuptyping
+ [color=maincolor]
+
+\definefontsynonym
+ [TitlePageMono]
+ [file:lmmonoproplt10-bold*default]
+
+\setuphead
+ [color=maincolor]
+
+\usesymbols
+ [cc]
+
+\setupinteraction
+ [hidden]
+
+\loadfontgoodies[lm]
+
+\startdocument
+ [metadata:author=Hans Hagen,
+ metadata:title=SwigLib basics,
+ author=Hans Hagen,
+ affiliation=PRAGMA ADE,
+ location=Hasselt NL,
+ title=SwigLib basics,
+ support=www.contextgarden.net,
+ website=www.pragma-ade.nl]
+
+\startluasetups[swiglib]
+ for i=1,640 do
+ context.definedfont { string.formatters["TitlePageMono at %p"](65536*(10+math.random(5))) }
+ context("SwigLib ")
+ end
+ context.removeunwantedspaces()
+\stopluasetups
+
+\startMPpage
+
+StartPage ;
+
+ fill Page enlarged 1cm withcolor \MPcolor{extracolor} ;
+
+ draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{swiglib}}")
+ xysized (PaperWidth,PaperHeight)
+ shifted center Page
+ withcolor .8white ;
+
+ draw textext.ulft("\definedfont[TitlePageMono]basics")
+ xsized .75PaperWidth
+ shifted lrcorner Page
+ shifted (-1cm,2cm)
+ withcolor \MPcolor{maincolor} ;
+
+% draw textext.ulft("\definedfont[TitlePageMono]in context mkiv")
+% xsized .6PaperWidth
+% shifted lrcorner Page
+% shifted (-1cm,6cm)
+% withcolor \MPcolor{maincolor} ;
+
+StopPage ;
+
+\stopMPpage
+
+\dontcomplain
+
+\startsubject[title=Contents]
+
+\placelist[section][alternative=a]
+
+\stopsubject
+
+\startsection[title=Introduction]
+
+The \SWIGLIB\ project is related to \LUATEX\ and aims as adding portable library
+support to this \TEX\ engine without too much fixed binding. The project does not
+provide \LUA\ code, unless really needed, because it assumes that macro packages
+have different demands. It also fits in the spirit of \TEX\ and \LUA\ to minimize
+the core components.
+
+The technical setup is by Luigi Scarso and documentation about how to build the
+libraries is part of the \SWIGLIB\ repository. Testing happens with help of the
+\CONTEXT\ (garden) infrastructure. This short document only deals with usage in
+\CONTEXT\ but also covers rather plain usage.
+
+\blank \start \em todo: reference to Luigi's manual \stop \blank
+
+\stopsection
+
+\startsection[title=Inside \CONTEXT]
+
+The recommended way to load a library in \CONTEXT\ is by using the
+\type {swiglib} function. This function lives in the global namespace.
+
+\starttyping
+local gm = swiglib("gmwand.core")
+\stoptyping
+
+After this call you have the functionality available in the \type {gm}
+namespace. This way of loading makes \CONTEXT\ aware that such a library
+has been loading and it will report the loaded libraries as part of the
+statistics.
+
+If you want, you can use the more ignorant \type {require} instead but in
+that case you need to be more explicit.
+
+\starttyping
+local gm = require("swiglib.gmwand.core")
+\stoptyping
+
+Here is an example of using such a library (by Luigi):
+
+\startbuffer
+\startluacode
+local gm = swiglib("gmwand.core")
+local findfile = resolvers.findfile
+
+gm.InitializeMagick(".")
+
+local magick_wand = gm.NewMagickWand()
+local drawing_wand = gm.NewDrawingWand()
+local pixel_wand = gm.NewPixelWand();
+
+gm.MagickSetSize(magick_wand,800,600)
+gm.MagickReadImage(magick_wand,"xc:gray")
+
+gm.DrawPushGraphicContext(drawing_wand)
+
+gm.DrawSetFillColor(drawing_wand,pixel_wand)
+
+gm.DrawSetFont(drawing_wand,findfile("dejavuserifbold.ttf"))
+gm.DrawSetFontSize(drawing_wand,96)
+gm.DrawAnnotation(drawing_wand,200,200,"ConTeXt 1")
+
+gm.DrawSetFont(drawing_wand,findfile("texgyreschola-bold.otf"))
+gm.DrawSetFontSize(drawing_wand,78)
+gm.DrawAnnotation(drawing_wand,250,300,"ConTeXt 2")
+
+gm.DrawSetFont(drawing_wand,findfile("lmroman10-bold.otf"))
+gm.DrawSetFontSize(drawing_wand,48)
+gm.DrawAnnotation(drawing_wand,300,400,"ConTeXt 3")
+
+gm.DrawPopGraphicContext(drawing_wand)
+
+gm.MagickDrawImage(magick_wand,drawing_wand)
+
+gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.png",1)
+gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.jpg",1)
+gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.pdf",1)
+
+gm.DestroyDrawingWand(drawing_wand)
+gm.DestroyPixelWand(pixel_wand)
+gm.DestroyMagickWand(magick_wand)
+\stopluacode
+\stopbuffer
+
+\typebuffer \getbuffer
+
+In practice you will probably stay away from manipulating text this way, but it
+illustrates that you can use the regular \CONTEXT\ helpers to locate files.
+
+\startlinecorrection[big]
+ \startcombination[3*1]
+ {\externalfigure[swiglib-mkiv-gm-1.png][width=.3\textwidth]} {png}
+ {\externalfigure[swiglib-mkiv-gm-1.pdf][width=.3\textwidth]} {pdf}
+ {\externalfigure[swiglib-mkiv-gm-1.jpg][width=.3\textwidth]} {jpg}
+ \stopcombination
+\stoplinecorrection
+
+You'd better make sure to use unique filenames for such graphics. Of course a more
+clever mechanism would only run time consuming tasks once for each iteration of a
+document.
+
+\stopsection
+
+\startsection[title=Outside \CONTEXT]
+
+In the \CONTEXT\ distribution we ship some generic macros and code for usage in
+plain \TEX\ but there is no reason why they shouldn't work in other macro packages
+as well. A rather plain example is this:
+
+\starttyping
+\input luatex-swiglib.tex
+
+\directlua {
+ dofile("luatex-swiglib-test.lua")
+}
+
+\pdfximage {luatex-swiglib-test.jpg} \pdfrefximage\pdflastximage
+
+\end
+\stoptyping
+
+Assuming that you made the \type {luatex-plain} format, such a file can be processed using:
+
+\starttyping
+luatex --fmt=luatex=plain luatex-swiglib-test.tex
+\stoptyping
+
+The loaded \LUA\ file \type {luatex-swiglib-test.lua} liike like this:
+
+\starttyping
+local gm = swiglib("gmwand.core")
+
+gm.InitializeMagick(".")
+
+local magick_wand = gm.NewMagickWand()
+local drawing_wand = gm.NewDrawingWand()
+
+gm.MagickSetSize(magick_wand,800,600)
+gm.MagickReadImage(magick_wand,"xc:red")
+gm.DrawPushGraphicContext(drawing_wand)
+gm.DrawSetFillColor(drawing_wand,gm.NewPixelWand())
+gm.DrawPopGraphicContext(drawing_wand)
+gm.MagickDrawImage(magick_wand,drawing_wand)
+gm.MagickWriteImages(magick_wand,"./luatex-swiglib-test.jpg",1)
+
+gm.DestroyDrawingWand(drawing_wand)
+gm.DestroyMagickWand(magick_wand)
+\stoptyping
+
+Instead of loading a library with the \type {swiglib} function, you can also
+use \type {require}:
+
+\starttyping
+local gm = require("swiglib.gmwand.core")
+\stoptyping
+
+Watch the explicit \type {swiglib} reference. Both methods are equivalent.
+
+\stopsection
+
+\startsection[title={The libraries}]
+
+Most libraries are small but some can be rather large and have additional files.
+This is why we keep them separated. On my system they are collected in the
+platform binary tree:
+
+\starttyping
+e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/gmwand
+e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql
+e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/....
+\stoptyping
+
+One can modulate on this:
+
+\starttyping
+...tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/core.dll
+...tex/texmf-mswin/bin/lib/luajittex/lua/swiglib/mysql/core.dll
+...tex/texmf-mswin/bin/lib/luatex/context/lua/swiglib/mysql/core.dll
+\stoptyping
+
+are all valid. When versions are used you can provide an additional argument to the
+\type {swiglib} loader:
+
+\starttyping
+tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/5.6/core.dll
+\stoptyping
+
+This works with:
+
+\starttyping
+local mysql = swiglib("mysql.core","5.6")
+\stoptyping
+
+as well as:
+
+\starttyping
+local mysql = swiglib("mysql.core")
+\stoptyping
+
+It is hard to predict how operating systems look up libraries and especially
+nested loads, but as long as the root of the \type {swiglib} path is known to the
+file search routine. We've kept the main conditions for success simple: the core
+library is called \type {core.dll} or \type {core.so}. Each library has an
+(automatically called) initialize function named \type {luaopen_core}. There is no
+reason why (sym)links from the \type {swiglib} path to someplace else shouldn't
+work.
+
+In \type {texmfcnf.lua} you will find an entry like:
+
+\starttyping
+CLUAINPUTS = ".;$SELFAUTOLOC/lib/{$engine/context,$engine}/lua//"
+\stoptyping
+
+Which in practice boils down to a search for \type {luatex} or \type {luajittex}
+specific libraries. When both binaries are compatible and there are no \type
+{luajittex} binaries, the regular \type {luatex} libraries will be used.
+
+The \type {swiglib} loader function mentioned in previous sections load libraries
+in a special way: it changes dir to the specific path and then loads the library
+in the usual way. After that it returns to the path where it started out. After
+this, when the library needs additional libraries (and for instance graphicmagick
+needs a lot of them) it will first look on its own path (which is remembered).
+
+The \MKIV\ lookups are somewhat more robust in the sense that they first check
+for matches on engine specific paths. This comes in handy when the search
+patterns are too generic and one can match on for instance \type {luajittex}
+whilc \type {luatex} is used.
+
+\stopsection
+
+\startsection[title=Colofon]
+
+\starttabulate[|B|p|]
+\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR
+\NC version \NC \currentdate \NC \NR
+\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR
+\NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR
+\NC comment \NC the swiglib infrastructure is implemented by Luigi Scarso \NC \NR
+\stoptabulate
+
+\stopsection
+
+\stopdocument
diff --git a/doc/context/sources/general/manuals/tiptrick/tiptrick.tex b/doc/context/sources/general/manuals/tiptrick/tiptrick.tex
new file mode 100644
index 000000000..54a785134
--- /dev/null
+++ b/doc/context/sources/general/manuals/tiptrick/tiptrick.tex
@@ -0,0 +1,117 @@
+% interface=en
+%
+% author: Hans Hagen - Pragma ADE - www.pragma-ade.com
+
+\setupbodyfont
+ [dejavu]
+
+\setuppapersize
+ [HD-]
+
+\setuplayout
+ [location=middle,
+ header=0pt,
+ footer=0pt,
+ backspace=2.25cm,
+ topspace=2.25cm,
+ width=middle,
+ height=middle]
+
+\setupcolors
+ [state=start]
+
+\startreusableMPgraphic{page}
+ StartPage ;
+ picture p ; path s ;
+ fill Page withcolor .5red ;
+ draw Page withpen pensquare scaled 2cm withcolor .75[.5red,white] ;
+ s := (Field[Text][Text] enlarged .5cm) squeezed (.1cm,.15cm) ;
+ fill s withcolor .75[.5red,white] ;
+ if false :
+ p := image (graphictext "\ss TIP" withfillcolor .2white ;) ;
+ else :
+ p := textext.raw("\ss TIP") ;
+ setbounds p to (boundingbox p rightenlarged -0.025bbwidth(p)) ;
+ fi ;
+ p := p xysized(PaperWidth-1cm,PaperHeight-1cm) ;
+ p := p shifted .5(bbwidth(Page)-bbwidth(p),bbheight(Page)-bbheight(p)) ;
+ draw p withcolor .2white ;
+ clip p to s ;
+ draw p withcolor .875[.5red,white] ; ;
+ StopPage ;
+\stopreusableMPgraphic
+
+\defineoverlay
+ [page]
+ [\reuseMPgraphic{page}]
+
+\setupbackgrounds
+ [page]
+ [background=page,
+ state=repeat]
+
+\definecolor[red][r=.5]
+
+\setuphead
+ [chapter]
+ [style=\tfb,
+ before=,
+ after={\blank[line]}]
+
+\setupblank
+ [halfline]
+
+% xml interface
+
+\startxmlsetups xml:tips
+ \xmlflush{#1}
+\stopxmlsetups
+
+\startxmlsetups xml:tip
+ \startstandardmakeup
+ \startnamedsection[title][title=\xmlfirst{#1}{/title}]
+ \xmlall{#1}{/(remark|command)}
+ \vfill
+ \stopnamedsection
+ \stopstandardmakeup
+\stopxmlsetups
+
+\startxmlsetups xml:remark
+ \blank
+ \xmlflush{#1}
+ \blank
+\stopxmlsetups
+
+\definehighlight
+ [command]
+ [style=mono,
+ color=red,
+ command=no]
+
+\startxmlsetups xml:command
+ \blank
+ \starthighlight[command]
+ \xmlflush{#1}
+ \stophighlight
+ \blank
+\stopxmlsetups
+
+\startxmlsetups xml:reference
+ \vfill
+ \hfill\strut see:\space
+ \xmlflush{#1}
+\stopxmlsetups
+
+\startxmlsetups xml:initialize
+ \xmlsetsetup {#1} {
+ tips|tip|remark|command|reference
+ } {xml:*}
+\stopxmlsetups
+
+\xmlregisterdocumentsetup{main}{xml:initialize}
+
+\starttext
+
+ \xmlprocessfile{main}{tiptrick.xml}{}
+
+\stoptext
diff --git a/doc/context/sources/general/manuals/tiptrick/tiptrick.xml b/doc/context/sources/general/manuals/tiptrick/tiptrick.xml
new file mode 100644
index 000000000..8b4a30011
--- /dev/null
+++ b/doc/context/sources/general/manuals/tiptrick/tiptrick.xml
@@ -0,0 +1,53 @@
+<?xml version='1.0'?>
+
+<!-- author: Hans Hagen - Pragma ADE - www.pragma-ade.com -->
+
+<!-- feel free to submit more tips -->
+
+<tips xmlns="www.pragma-ade.com/schemas/tip.rng">
+
+ <tip>
+ <title>Generating Formats</title>
+ <remark>for all languages:</remark>
+ <command>context --make --all</command>
+ <remark>only english interface:</remark>
+ <command>context --make en</command>
+ <remark>for plain tex:</remark>
+ <command>mtxrun --script plain --make</command>
+ <!-- reference>mtexexec.pdf</reference -->
+ </tip>
+
+ <tip>
+ <title>Updating</title>
+ <remark>when installed from the wiki:</remark>
+ <command>..../first-setup(.cmd)</command>
+ <remark>when downloaded from the website:</remark>
+ <command>cd ..../tex/texmf-context</command>
+ <command>wget http://www.pragma-ade.com/context/current/cont-tmf.zip</command>
+ <command>unzip cont-tmf.zip</command>
+ <command>mtxrun --generate</command>
+ <!-- reference>minstall.pdf</reference -->
+ </tip>
+
+ <tip>
+ <title>Generating Command Lists</title>
+ <remark>quick reference document of english and dutch commands:</remark>
+ <command>context --interface=nl --global --result=setup-nl x-set-12.mkiv</command>
+ <command>context --interface=en --global --result=setup-en x-set-12.mkiv</command>
+ </tip>
+
+ <tip>
+ <title>Module Documentation</title>
+ <remark>pretty printed, annotated module documentation:</remark>
+ <command>mtxrun --script modules syst-aux.mkiv</command>
+ </tip>
+
+ <tip>
+ <title>Listings</title>
+ <remark>verbatim listings of (ascii) files:</remark>
+ <command>context --extra=listing --bodyfont=8pt --scite somefile.tex</command>
+ <command>context --extra=listing --bodyfont=8pt --scite somefile.lua</command>
+ <command>context --extra=listing --bodyfont=8pt --scite somefile.xml</command>
+ </tip>
+
+</tips>
diff --git a/doc/context/sources/general/manuals/tools/tools-mkiv.tex b/doc/context/sources/general/manuals/tools/tools-mkiv.tex
new file mode 100644
index 000000000..5f20e6985
--- /dev/null
+++ b/doc/context/sources/general/manuals/tools/tools-mkiv.tex
@@ -0,0 +1,501 @@
+% language=uk
+
+% author : Hans Hagen, PRAGMA ADE, NL
+% license : Creative Commons, Attribution-NonCommercial-ShareAlike 3.0 Unported
+
+\usemodule[abr-02]
+
+\setuplayout
+ [width=middle,
+ height=middle,
+ backspace=2cm,
+ topspace=1cm,
+ footer=0pt,
+ bottomspace=2cm]
+
+\definecolor
+ [DocumentColor]
+ [r=.5]
+
+\setuptype
+ [color=DocumentColor]
+
+\setuptyping
+ [color=DocumentColor]
+
+\usetypescript
+ [iwona]
+
+\setupbodyfont
+ [iwona]
+
+\setuphead
+ [chapter]
+ [style=\bfc,
+ color=DocumentColor]
+
+\setuphead
+ [section]
+ [style=\bfb,
+ color=DocumentColor]
+
+\setupinteraction
+ [hidden]
+
+\setupwhitespace
+ [big]
+
+\setupheadertexts
+ []
+
+\setupheadertexts
+ []
+ [{\DocumentColor \type {luatools mtxrun context}\quad\pagenumber}]
+
+\usesymbols[cc]
+
+\def\sTEXMFSTART{\type{texmfstart}}
+\def\sLUATOOLS {\type{luatools}}
+\def\sMTXRUN {\type{mtxrun}}
+\def\sCONTEXT {\type{context}}
+\def\sKPSEWHICH {\type{kpsewhich}}
+\def\sMKTEXLSR {\type{mktexlsr}}
+\def\sXSLTPROC {\type{xsltproc}}
+
+\usemodule[narrowtt]
+
+\startdocument
+ [metadata:author=Hans Hagen,
+ metadata:title={Tools: luatools, mtxrun, context},
+ author=Hans Hagen,
+ affiliation=PRAGMA ADE,
+ location=Hasselt NL,
+ title=Tools,
+ extra-1=luatools,
+ extra-2=mtxrun,
+ extra-3=context,
+ support=www.contextgarden.net,
+ website=www.pragma-ade.nl]
+
+\startMPpage
+ StartPage ;
+ picture p ; p := image (
+ for i=1 upto 21 :
+ for j=1 upto 30 :
+ drawarrow (fullcircle rotated uniformdeviate 360) scaled 10 shifted (i*15,j*15) ;
+ endfor ;
+ endfor ;
+ ) ;
+ p := p ysized (bbheight(Page)-4mm) ;
+ fill Page enlarged 2mm withcolor \MPcolor{DocumentColor} ;
+ draw p shifted (center Page - center p) withpen pencircle scaled 2 withcolor .5white ;
+ numeric dx ; dx := bbwidth(Page)/21 ;
+ numeric dy ; dy := bbheight(Page)/30 ;
+ p := textext("\tt\bf\white\getvariable{document}{extra-1}") xsized(14*dx) ;
+ p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,8dy) ;
+ draw p ;
+ p := textext("\tt\bf\white\getvariable{document}{extra-2}") xsized(14*dx) ;
+ p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,5dy) ;
+ draw p ;
+ p := textext("\tt\bf\white\getvariable{document}{extra-3}") xsized(14*dx) ;
+ p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,2dy) ;
+ draw p ;
+ setbounds currentpicture to Page ;
+ StopPage
+\stopMPpage
+
+\startsubject[title=Contents]
+
+\placelist[section][alternative=a]
+
+\stopsubject
+
+\startsection[title={Remark}]
+
+This manual is work in progress. Feel free to submit additions or corrections.
+Before you start reading, it is good to know that in order to get starting with
+\CONTEXT, the easiest way to do that is to download the standalone distribution
+from \type {contextgarden.net}. After that you only need to make sure that \type
+{luatex} is in your path. The main command you use is then \type {context} and
+normally it does all the magic it needs itself.
+
+\stopsection
+
+\startsection[title={Introduction}]
+
+Right from the start \CONTEXT\ came with programs that managed the process of
+\TEX-ing. Although you can perfectly well run \TEX\ directly, it is a fact that
+often multiple runs are needed as well as that registers need to be sorted.
+Therefore managing a job makes sense.
+
+First we had \TEXEXEC\ and \TEXUTIL, and both were written in \MODULA, and as
+this language was not supported on all platforms the programs were rewritten in
+\PERL. Following that a few more tools were shipped with \CONTEXT.
+
+When we moved on to \RUBY\ all the \PERL\ scripts were rewritten and when
+\CONTEXT\ \MKIV\ showed up, \LUA\ replaced \RUBY. As we use \LUATEX\ this means
+that currently the tools and the main program share the same language. For \MKII\
+scripts like \TEXEXEC\ will stay around but the idea is that there will be \LUA\
+alternatives for them as well.
+
+Because we shipped many scripts, and because the de facto standard \TEX\
+directory structure expects scripts to be in certain locations we not only ship
+tools but also some more generic scripts that locate and run these tools.
+
+\stopsection
+
+\startsection[title={The location}]
+
+Normally you don't need to know so many details about where the scripts
+are located but here they are:
+
+\starttyping
+<texroot>/scripts/context/perl
+<texroot>/scripts/context/ruby
+<texroot>/scripts/context/lua
+<texroot>/scripts/context/stubs
+\stoptyping
+
+This hierarchy was actually introduced because \CONTEXT\ was shipped with a bunch
+of tools. As mentioned, we nowadays focus on \LUA\ but we keep a few of the older
+scripts around in the \PERL\ and \RUBY\ paths.Now, if you're only using \CONTEXT\
+\MKIV, and this is highly recommended, you can forget about all but the \LUA\
+scripts.
+
+\stopsection
+
+\startsection[title={The traditional finder}]
+
+When you run scripts multiple times, and in the case of \CONTEXT\ they are even
+run inside other scripts, you want to minimize the startup time. Unfortunately
+the traditional way to locate a script, using \sKPSEWHICH, is not that fast,
+especially in a setup with many large trees Also, because not all tasks can be
+done with the traditional scripts (take format generation) we provided a runner
+that could deal with this: \sTEXMFSTART. As this script was also used in more
+complex workflows, it had several tasks:
+
+\startitemize[packed]
+\item locate scripts in the distribution and run them using the right
+ interpreter
+\item do this selectively, for instance identify the need for a run using
+ checksums for potentially changed files (handy for image conversion)
+\item pass information to child processes so that lookups are avoided
+\item choose a distribution among several installed versions (set the root
+ of the \TEX\ tree)
+\item change the working directory before running the script
+\item resolve paths and names on demand and launch programs with arguments
+ where names are expanded controlled by prefixes (handy for
+ \TEX-unware programs)
+\item locate and open documentation, mostly as part the help systems in
+ editors, but also handy for seeing what configuration file is used
+\item act as a \KPSEWHICH\ server cq.\ client (only used in special cases,
+ and using its own database)
+\stopitemize
+
+Of course there were the usual more obscure and undocumented features as
+well. The idea was to use this runner as follows:
+
+\starttyping
+texmfstart texexec <further arguments>
+texmfstart --tree <rootoftree> texexec <further arguments>
+\stoptyping
+
+These are just two ways of calling this program. As \sTEXMFSTART\ can initialize
+the environment as well, it is basically the only script that has to be present
+in the binary path. This is quite comfortable as this avoids conflicts in names
+between the called scripts and other installed programs.
+
+Of course calls like above can be wrapped in a shell script or batch file without
+penalty as long as \sTEXMFSTART\ itself is not wrapped in a caller script that
+applies other inefficient lookups. If you use the \CONTEXT\ minimals you can be
+sure that the most efficient method is chosen, but we've seen quite inefficient
+call chains elsewhere.
+
+In the \CONTEXT\ minimals this script has been replaced by the one we will
+discuss in the next section: \sMTXRUN\ but a stub is still provided.
+
+\stopsection
+
+\startsection[title={The current finder}]
+
+In \MKIV\ we went a step further and completely abandoned the traditional lookup
+methods and do everything in \LUA. As we want a clear separation between
+functionality we have two main controlling scripts: \sMTXRUN\ and \sLUATOOLS. The
+last name may look somewhat confusing but the name is just one on in a series.
+\footnote {We have \type {ctxtools}, \type {exatools}, \type {mpstools}, \type
+{mtxtools}, \type {pdftools}, \type {rlxtools}, \type {runtools}, \type
+{textools}, \type {tmftools} and \type {xmltools}. Most if their funtionality is
+already reimplemented.}
+
+In \MKIV\ the \sLUATOOLS\ program is nowadays seldom used. It's just a drop in
+for \sKPSEWHICH\ plus a bit more. In that respect it's rather dumb in that it
+does not use the database, but clever at the same time because it can make one
+based on the little information available when it runs. It can also be used to
+generate format files either or not using \LUA\ stubs but in practice this is not
+needed at all.
+
+For \CONTEXT\ users, the main invocation of this tool is when the \TEX\ tree is
+updated. For instance, after adding a font to the tree or after updating
+\CONTEXT, you need to run:
+
+\starttyping
+mtxrun --generate
+\stoptyping
+
+After that all tools will know where to find stuff and how to behave well within
+the tree. This is because they share the same code, mostly because they are
+started using \sMTXRUN. For instance, you process a file with:
+
+\starttyping
+mtxrun --script context <somefile>
+\stoptyping
+
+Because this happens often, there's also a shortcut:
+
+\starttyping
+context <somefile>
+\stoptyping
+
+But this does use \sMTXRUN\ as well. The help information of \sMTXRUN\ is rather
+minimalistic and if you have no clue what an option does, you probably never
+needed it anyway. Here we discuss a few options. We already saw that we can
+explicitly ask for a script:
+
+\starttyping
+mtxrun --script context <somefile>
+\stoptyping
+
+but
+
+\starttyping
+mtxrun context <somefile>
+\stoptyping
+
+also works. However, by using \type {--script} you limit te lookup to the valid
+\CONTEXT\ \MKIV\ scripts. In the \TEX\ tree these have names prefixed by \type
+{mtx-} and a lookup look for a plural as well. So, the next two lookups are
+equivalent:
+
+\starttyping
+mtxrun --script font
+mtxrun --script fonts
+\stoptyping
+
+Both will run \type {mtx-fonts.lua}. Actually, this is one of the scripts that
+you might need when your font database is somehow outdated and not updated
+automatically:
+
+\starttyping
+mtxrun --script fonts --reload --force
+\stoptyping
+
+Normally \sMTXRUN\ is all you need in order to run a script. However, there are a
+few more options:
+
+\ctxlua{os.execute("mtxrun > tools-mkiv-help.tmp")}
+
+\typefile[ntyping]{tools-mkiv-help.tmp}
+
+Don't worry,you only need those obscure features when you integrate \CONTEXT\ in
+for instance a web service or when you run large projects where runs and paths
+take special care.
+
+\stopsection
+
+\startsection[title={Updating}]
+
+There are two ways to update \CONTEXT\ \MKIV. When you manage your
+trees yourself or when you use for instance \TEXLIVE, you act as
+follows:
+
+\startitemize[packed]
+\item download the file cont-tmf.zip from \type {www.pragma-ade.com} or elsewhere
+\item unzip this file in a subtree, for instance \type {tex/texmf-local}
+\item run \type {mtxrun --generate}
+\item run \type {mtxrun --script font --reload}
+\item run \type {mtxrun --script context --make}
+\stopitemize
+
+Or shorter:
+
+\startitemize[packed]
+\item run \type {mtxrun --generate}
+\item run \type {mtxrun font --reload}
+\item run \type {context --make}
+\stopitemize
+
+Normally these commands are not even needed, but they are a nice test if your
+tree is still okay. To some extend \sCONTEXT\ is clever enough to decide if the
+databases need to be regenerated and|/|or a format needs to be remade and|/|or if
+a new font database is needed.
+
+Now, if you also want to run \MKII, you need to add:
+
+\startitemize[packed]
+\item run \type {mktexlsr}
+\item run \type {texexec --make}
+\stopitemize
+
+The question is, how to act when \sLUATOOLS\ and \sMTXRUN\ have been updated
+themselves? In that case, after unzipping the archive, you need to do the
+following:
+
+\startitemize[packed]
+\item run \type {luatools --selfupdate}
+\item run \type {mtxrun --selfupdate}
+\stopitemize
+
+For quite a while we shipped so called \CONTEXT\ minimals. These zip files
+contained only the resources and programs that made sense for running \CONTEXT.
+Nowadays the minimals are installed and synchronized via internet. \footnote
+{This project was triggered by Mojca Miklavec who is also charge of this bit of
+the \CONTEXT\ infrastructure. More information can be found at \type
+{contextgarden.net}.} You can just run the installer again and no additional
+commands are needed. In the console you will see several calls to \sMTXRUN\ and
+\sLUATOOLS\ fly by.
+
+\stopsection
+
+\startsection[title={The tools}]
+
+We only mention the tools here. The most important ones are \sCONTEXT\ and \type
+{fonts}. You can ask for a list of installed scripts with:
+
+\starttyping
+mtxrun --script
+\stoptyping
+
+On my machine this gives:
+
+\ctxlua{os.execute("mtxrun --script > tools-mkiv-help.tmp")}
+
+\typefile[ntyping]{tools-mkiv-help.tmp}
+
+The most important scripts are \type {mtx-fonts} and \type {mtx-context}. By
+default fonts are looked up by filename (the \type {file:} prefix before font
+names in \CONTEXT\ is default). But you can also lookup fonts by name (\type
+{name:}) or by specification (\type {spec:}). If you want to use these two
+methods, you need to generate a font database as mentioned in the previous
+section. You can also use the font tool to get information about the fonts
+installed on your system.
+
+\stopsection
+
+\startsection[title={Running \CONTEXT}]
+
+The \sCONTEXT\ tool is what you will use most as it manages your
+run.
+
+\ctxlua{os.execute("context > tools-mkiv-help.tmp")}
+
+\typefile[ntyping]{tools-mkiv-help.tmp}
+
+There are few exert options too:
+
+\ctxlua{os.execute("context --expert > tools-mkiv-help.tmp")}
+
+\typefile[ntyping]{tools-mkiv-help.tmp}
+
+You might as well forget about these unless you are one of the
+\CONTEXT\ developers.
+
+\stopsection
+
+\startsection[title={Prefixes}]
+
+A handy feature of \sMTXRUN\ (and as most features an inheritance of
+\sTEXMFSTART) is that it will resolve prefixed arguments. This can be of help
+when you run programs that are unaware of the \TEX\ tree but nevertheless need to
+locate files in it.
+
+\ctxlua{os.execute("mtxrun --prefixes > tools-mkiv-help.tmp")}
+
+\typefile[ntyping]{tools-mkiv-help.tmp}
+
+An example is:
+
+\starttyping
+mtxrun --execute xsltproc file:whatever.xsl file:whatever.xml
+\stoptyping
+
+The call to \sXSLTPROC\ will get two arguments, being the complete path to the
+files (given that it can be resolved). This permits you to organize the files in
+a similar was as \TEX\ files.
+
+\stopsection
+
+\startsection[title={Stubs}]
+
+As the tools are written in the \LUA\ language we need a \LUA\ interpreter and or
+course we use \LUATEX\ itself. On \UNIX\ we can copy \sLUATOOLS\ and \sMTXRUN\ to
+files in the binary path with the same name but without suffix. Starting them in
+another way is a waste of time, especially when \sKPSEWHICH\ is used to find
+then, something which is useless in \MKIV\ anyway. Just use these scripts
+directly as they are self contained.
+
+For \sCONTEXT\ and other scripts that we want convenient access to, stubs are
+needed, like:
+
+\starttyping
+#!/bin/sh
+mtxrun --script context "$@"
+\stoptyping
+
+This is also quite efficient as the \sCONTEXT\ script \type {mtx-context} is
+loaded in \sMTXRUN\ and uses the same database.
+
+On \WINDOWS\ you can copy the scripts as|-|is and associate the suffix with
+\LUATEX\ (or more precisely: \type {texlua}) but then all \LUA\ script will be
+run that way which is not what you might want.
+
+In \TEXLIVE\ stubs for starting scripts were introduced by Fabrice Popineau. Such
+a stub would start for instance \sTEXMFSTART, that is: it located the script
+(\PERL\ or \RUBY) in the \TEX\ tree and launched it with the right interpreter.
+Later we shipped pseudo binaries of \sTEXMFSTART: a \RUBY\ interpreter plus
+scripts wrapped into a self contained binary.
+
+For \MKIV\ we don't need such methods and started with simple batch files,
+similar to the \UNIX\ startup scripts. However, these have the disadvantage that
+they cannot be used in other batch files without using the \type {start} command.
+In \TEXLIVE\ this is taken care of by a small binary written bij T.M.\ Trzeciak
+so on \TEXLIVE\ 2009 we saw a call chain from \type {exe} to \type {cmd} to \type
+{lua} which is somewhat messy.
+
+This is why we now use an adapted and stripped down version of that program that
+is tuned for \sMTXRUN, \sLUATOOLS\ and \sCONTEXT. So, we moved from the original
+\type {cmd} based approach to an \type {exe} one.
+
+\starttyping
+mtxrun.dll
+mtxrun.exe
+\stoptyping
+
+You can copy \type {mtxrun.exe} to for instance \type {context.exe} and it will
+still use \sMTXRUN\ for locating the right script. It also takes care of mapping
+\sTEXMFSTART\ to \sMTXRUN. So we've removed the intermediate \type {cmd} step,
+can not run the script as any program, and most of all, we're as efficient as can
+be.
+
+Of course this program is only meaningful for the \CONTEXT\ approach to tools.
+
+It may all sound more complex than it is but once it works users will not notice
+those details. Als, in practice not that much has changed in running the tools
+between \MKII\ and \MKIV\ as we've seen no reason to change the methods.
+
+\stopsection
+
+\startsubject[title={Colofon}]
+
+\starttabulate[|B|p|]
+ \NC author \NC \documentvariable{author},
+ \documentvariable{affiliation},
+ \documentvariable{location} \NC \NR
+ \NC version \NC \currentdate \NC \NR
+ \NC website \NC \documentvariable{website} \endash\
+ \documentvariable{support} \NC \NR
+ \NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR
+\stoptabulate
+
+\stopsubject
+
+\stopdocument
diff --git a/doc/context/sources/general/manuals/units/units-mkiv.tex b/doc/context/sources/general/manuals/units/units-mkiv.tex
new file mode 100644
index 000000000..0d91c67df
--- /dev/null
+++ b/doc/context/sources/general/manuals/units/units-mkiv.tex
@@ -0,0 +1,538 @@
+% language=uk
+
+\usemodule[art-01,abr-02,physics-units]
+
+\definecolor[red] [darkred]
+\definecolor[green] [darkgreen]
+\definecolor[blue] [darkblue]
+\definecolor[yellow] [darkyellow]
+\definecolor[magenta][darkmagenta]
+\definecolor[cyan] [darkcyan]
+
+\definecolor[maincolor] [darkcyan]
+\definecolor[extracolor][darkmagenta]
+
+\setupbodyfont
+ [10pt]
+
+\setuptyping
+ [color=extracolor]
+
+\setuptype
+ [color=extracolor] % darkyellow
+
+% \setupnumbering
+% [alternative=doublesided]
+
+\setupinteraction
+ [hidden]
+
+\setuphead
+ [section]
+ [color=maincolor]
+
+\usesymbols[cc]
+
+\startdocument
+ [metadata:author=Hans Hagen,
+ metadata:title=Units,
+ author=Hans Hagen,
+ affiliation=PRAGMA ADE,
+ location=Hasselt NL,
+ title=Units,
+ extra=ConTeXt MkIV,
+ support=www.contextgarden.net,
+ website=www.pragma-ade.nl]
+
+\unexpanded\def\UnitsHack#1#2%
+ {\setbox\scratchbox\hbox{\bf\strut#1#2/}% kerning and such
+ \hbox to \wd\scratchbox{\bf\strut#1\hss/\hss#2}}
+
+\startMPpage
+
+ StartPage ;
+ fill Page enlarged 2mm withcolor \MPcolor{darkcyan} ;
+ pickup pencircle scaled 2mm ;
+ picture p, q, r ;
+ p := textext("\ssbf\WORD{\documentvariable{title}}") xsized (bbheight Page - 2cm) rotated 90 ;
+ q := textext("\ssbf\WORD{\documentvariable{author}}") ysized 1cm ;
+ r := textext("\ssbf\WORD{\documentvariable{extra}}") xsized bbwidth q ;
+ draw anchored.rt (p, center rightboundary Page shifted (-1cm, 0mm)) withcolor white ;
+ draw anchored.lft(q, ulcorner Page shifted ( 1cm, -84mm)) withcolor white ; % \MPcolor{darkred} ;
+ draw anchored.lft(r, ulcorner Page shifted ( 1cm,-108mm)) withcolor white ; % \MPcolor{darkred} ;
+ StopPage ;
+
+\stopMPpage
+
+% \page[empty] \setuppagenumber[start=1]
+
+\startsubject[title={Contents}]
+
+\placelist[section][criterium=all,interaction=all]
+
+\stopsubject
+
+\startsection[title={Introduction}]
+
+In \CONTEXT\ \MKII\ there is a module that implements consistent
+typesetting of units (quantities and dimensions). In \MKIV\ this
+functionality is now part of the physics core modules. This is
+also one of the mechanisms that got a new user interface: instead
+of using commands we now parse text. Thanks to those users who
+provided input we're more complete now that in \MKII. You can browse
+the mailing list archive to get some sense of history.
+
+\stopsection
+
+\startsection[title={The main command}]
+
+The core command is \type {\unit}. The argument to this command gets
+parsed and converted into a properly typeset dimension. Normally there
+will be a quantity in front.
+
+\starttabulate
+\NC \type{10 meter} \NC \unit{10 meter} \NC \NR
+\NC \type{10 meter per second} \NC \unit{10 meter per second} \NC \NR
+\NC \type{10 square meter per second} \NC \unit{10 square meter per second} \NC \NR
+\stoptabulate
+
+The parser knows about special cases, like synonyms:
+
+\starttabulate
+\NC \type{10 degree celsius} \NC \unit{10 degree celsius} \NC \NR
+\NC \type{10 degrees celsius} \NC \unit{10 degrees celsius} \NC \NR
+\NC \type{10 celsius} \NC \unit{10 celsius} \NC \NR
+\stoptabulate
+
+The units can be rather complex, for example:
+
+\startbuffer
+\unit{30 kilo pascal square meter / second kelvin}
+\stopbuffer
+
+\typebuffer
+
+This comes out as: \ignorespaces\getbuffer\removeunwantedspaces. Depending
+on the unit at had, recognition is quite flexible. The following variants
+all work out ok.
+
+\starttabulate
+\NC \type{10 kilogram} \NC \unit{10 kilogram} \NC \NR
+\NC \type{10 kilo gram} \NC \unit{10 kilo gram} \NC \NR
+\NC \type{10 k gram} \NC \unit{10 k gram} \NC \NR
+\NC \type{10 kilo g} \NC \unit{10 kilo g} \NC \NR
+\NC \type{10 k g} \NC \unit{10 k g} \NC \NR
+\NC \type{10 kg} \NC \unit{10 kg} \NC \NR
+\NC \type{10 kilog} \NC \unit{10 kilog} \NC \NR
+\NC \type{10 kgram} \NC \unit{10 kgram} \NC \NR
+\stoptabulate
+
+Of course being consistent makes sense, so normally you will use
+a consistent mix of short or long keywords.
+
+You can provide a qualifier that gets lowered and appended to
+the preceding unit.
+
+\startbuffer
+\unit{112 decibel (A)}
+\stopbuffer
+
+\typebuffer
+
+This gives: \ignorespaces\getbuffer\removeunwantedspaces. Combinations
+are also possible:
+
+\starttabulate
+\NC \type{5 watt per meter celsius} \NC \unit{5 watt per meter celsius} \NC \NR
+\NC \type{5 watt per meter degrees celsius} \NC \unit{5 watt per meter degrees celsius} \NC \NR
+\NC \type{5 watt per meter kelvin} \NC \unit{5 watt per meter kelvin} \NC \NR
+\NC \type{5 watt per meter per kelvin} \NC \unit{5 watt per meter per kelvin} \NC \NR
+\NC \type{10 arcminute} \NC \unit{10 arcminute} \NC \NR
+\NC \type{10 arcminute 20 arcsecond} \NC \unit{10 arcminute 20 arcsecond} \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title={Extra units}]
+
+To some extent units can be tuned. You can for instance
+influence the spacing between a number and a unit:
+
+\startbuffer
+ \unit{35 kilogram per cubic meter}
+\setupunit[space=normal] \unit{35 kilogram per cubic meter}
+\setupunit[space=big] \unit{35 kilogram per cubic meter}
+\setupunit[space=medium] \unit{35 kilogram per cubic meter}
+\setupunit[space=small] \unit{35 kilogram per cubic meter}
+\setupunit[space=none] \unit{35 kilogram per cubic meter}
+\stopbuffer
+
+\typebuffer
+
+Of course no spacing looks rather bad:
+
+\startlines
+\getbuffer
+\stoplines
+
+Another parameter is \type {separator}. In order to demonstrate
+this we define an extra unit command:
+
+\startbuffer
+\defineunit[sunit][separator=small]
+\defineunit[nunit][separator=none]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We now have two more commands:
+
+\startbuffer
+\unit {35 kilogram cubic meter}
+\sunit{35 kilogram cubic meter}
+\nunit{35 kilogram cubic meter}
+\stopbuffer
+
+\typebuffer
+
+These three commands give different results:
+
+\startlines
+\getbuffer
+\stoplines
+
+Valid separators are \type {normal}, \type {big}, \type {medium},
+\type {small}, \type {none}. You can let units stand out by
+applying color or a specific style.
+
+\startbuffer
+\setupunit[style=\bi,color=maincolor]
+\unit{10 square meter per second}
+\stopbuffer
+
+\typebuffer
+
+Keep in mind that all defined units inherit from their parent
+definition unless they are set up themselves.
+
+\start \blank \getbuffer \blank \stop
+
+To some extent you can control rendering in text and math mode. As
+an example we define an extra instance.
+
+\startbuffer
+\defineunit[textunit][alternative=text]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
+test \unit {10 cubic meter per second} test
+test \textunit{10 cubic meter per second} test
+test $\unit {10 cubic meter per second}$ test
+test $\textunit{10 cubic meter per second}$ test
+test 10 \unit {cubic meter per second} test
+test 10 \textunit{cubic meter per second} test
+test $10 \unit {cubic meter per second}$ test
+test $10 \textunit{cubic meter per second}$ test
+\stopbuffer
+
+\typebuffer
+
+\startlines
+\getbuffer
+\stoplines
+
+\stopsection
+
+\startsection[title={Labels}]
+
+The units, prefixes and operators are typeset using the label
+mechanism which means that they can be made to adapt to a language
+and|/|or adapted. Instead of language specific labels you can also
+introduce mappings that don't relate to a language at all. As an
+example we define some bogus mapping.
+
+\startbuffer
+\setupunittext
+ [whatever]
+ [meter=retem,
+ second=dnoces]
+
+\setupprefixtext
+ [whatever]
+ [kilo=olik]
+
+\setupoperatortext
+ [whatever]
+ [solidus={ rep }]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Such a mapping can be partial and the current language will
+be the default fallback and itselfs falls back on the English
+language mapping.
+
+\startbuffer
+\unit{10 km/s}
+\unit{10 Kilo Meter/s}
+\unit{10 kilo Meter/s}
+\unit{10 Kilo m/s}
+\unit{10 k Meter/s}
+\stopbuffer
+
+\typebuffer
+
+When we typeset this we get the normal rendering:
+
+\startlines
+\getbuffer
+\stoplines
+
+However, when we change the language parameter, we get
+a different result:
+
+\startlines
+\setupunit[language=whatever]\getbuffer
+\stoplines
+
+The alternative rendering is set up as follows:
+
+\starttyping
+\setupunit[language=whatever]
+\stoptyping
+
+You can also decide to use a special instance of units:
+
+\starttyping
+\defineunit[wunit][language=whatever]
+\stoptyping
+
+This will define the \type {\wunit} command and leave the original
+\type {\unit} command untouched.
+
+\stopsection
+
+\startsection[title={Digits}]
+
+In addition to units we have digits. These can be used independently
+but the same functionality is also integrated in the unit commands.
+The main purpose of this command is formatting in tables, of which
+we give an example below.
+
+\starttabulate[|l|r|]
+\NC \type{12,345.67 kilogram} \NC \unit{12,345.67 kilogram} \NR
+\NC \type{__,__1.23 kilogram} \NC \unit{__,__1.23 kilogram} \NR
+\NC \type{__,___.12 kilogram} \NC \unit{__,___.12 kilogram} \NR
+\NC \type{__,__1.== kilogram} \NC \unit{__,__1.== kilogram} \NR
+\NC \type{__,___:23 kilogram} \NC \unit{__,___:23 kilogram} \NR
+\stoptabulate
+
+The \type {_} character serves as placeholders. There are some
+assumptions to how numbers are constructed. In principe the input
+assumes a comma to separate thousands and a period to separate the
+fraction.
+
+\getbuffer
+
+You can swap periods and commas in the output. In fact there are a
+few methods available. For instance we can separate the thousands
+with a small space instead of a symbol.
+
+\startbuffer
+\starttabulate[|c|r|r|]
+\HL
+\NC 0 \NC \setupunit[method=0]\unit{00,000.10 kilogram}
+ \NC \setupunit[method=0]\unit{@@,@@0.10 kilogram} \NC \NR
+\NC 1 \NC \setupunit[method=1]\unit{00,000.10 kilogram}
+ \NC \setupunit[method=1]\unit{@@,@@0.10 kilogram} \NC \NR
+\NC 2 \NC \setupunit[method=2]\unit{00,000.10 kilogram}
+ \NC \setupunit[method=2]\unit{@@,@@0.10 kilogram} \NC \NR
+\NC 3 \NC \setupunit[method=3]\unit{00,000.10 kilogram}
+ \NC \setupunit[method=3]\unit{@@,@@0.10 kilogram} \NC \NR
+\NC 4 \NC \setupunit[method=4]\unit{00,000.10 kilogram}
+ \NC \setupunit[method=4]\unit{@@,@@0.10 kilogram} \NC \NR
+\NC 5 \NC \setupunit[method=5]\unit{00,000.10 kilogram}
+ \NC \setupunit[method=5]\unit{@@,@@0.10 kilogram} \NC \NR
+\NC 6 \NC \setupunit[method=6]\unit{00,000.10 kilogram}
+ \NC \setupunit[method=6]\unit{@@,@@0.10 kilogram} \NC \NR
+\HL
+\stoptabulate
+\stopbuffer
+
+\typebuffer % [bodyfont=9pt]
+
+\getbuffer
+
+The digit modes can be summarized as::
+
+\startitemize[n,packed]
+\item periods/comma
+\item commas/period
+\item thinmuskips/comma
+\item thinmuskips/period
+\item thickmuskips/comma
+\item thickmuskips/period
+\stopitemize
+
+You can reverse the order of commas and period in the input by
+setting the parameter \type {order} to \type {reverse}.
+
+The digit parser handles a bunch of special characters as
+well as different formats. We strongly suggest you to use
+the grouped call.
+
+\starttabulate[|l|l|l|]
+\NC \type{.} \NC , . \NC comma or period \NC \NR
+\NC \type{,} \NC , . \NC comma or period \NC \NR
+\NC \type{:} \NC \NC invisible period \NC \NR
+\NC \type{;} \NC \NC invisible comma \NC \NR
+\NC \type{_} \NC \NC invisible space \NC \NR
+\NC \type{/} \NC \NC invisible sign \NC \NR
+\NC \type{-} \NC $-$ \NC minus sign \NC \NR
+\NC \type{+} \NC $+$ \NC plus sign \NC \NR
+\NC \type{//} \NC \NC invisible high sign \NC \NR
+\NC \type{--} \NC $\negative$ \NC high minus sign \NC \NR
+\NC \type{++} \NC $\positive$ \NC high plus sign \NC \NR
+\NC \type{=} \NC $\zeroamount$ \NC zero padding \NC \NR
+\stoptabulate
+
+Let's give some examples:
+
+\starttabulate[|l|r|]
+\NC \type{1} \NC \ruledhbox{\strut\digits{1}} \NC \NR
+\NC \type{12} \NC \ruledhbox{\strut\digits{12}} \NC \NR
+\NC \type{12.34} \NC \ruledhbox{\strut\digits{12.34}} \NC \NR
+\NC \type{123,456} \NC \ruledhbox{\strut\digits{123,456}} \NC \NR
+\NC \type{123,456.78} \NC \ruledhbox{\strut\digits{123,456.78}} \NC \NR
+\NC \type{12,34} \NC \ruledhbox{\strut\digits{12,34}} \NC \NR
+\NC \type{.1234} \NC \ruledhbox{\strut\digits{.1234}} \NC \NR
+\NC \type{1234} \NC \ruledhbox{\strut\digits{1234}} \NC \NR
+\NC \type{123,456.78^9} \NC \ruledhbox{\strut\digits{123,456.78^9}} \NC \NR
+\NC \type{123,456.78e9} \NC \ruledhbox{\strut\digits{123,456.78e9}} \NC \NR
+\NC \type{/123,456.78e-9} \NC \ruledhbox{\strut\digits{/123,456.78e-9}} \NC \NR
+\NC \type{-123,456.78e-9} \NC \ruledhbox{\strut\digits{-123,456.78e-9}} \NC \NR
+\NC \type{+123,456.78e-9} \NC \ruledhbox{\strut\digits{+123,456.78e-9}} \NC \NR
+\NC \type{//123,456.78e-9} \NC \ruledhbox{\strut\digits{//123,456.78e-9}} \NC \NR
+\NC \type{--123,456.78e-9} \NC \ruledhbox{\strut\digits{--123,456.78e-9}} \NC \NR
+\NC \type{++123,456.78e-9} \NC \ruledhbox{\strut\digits{++123,456.78e-9}} \NC \NR
+\NC \type{___,___,123,456,789.00} \NC \ruledhbox{\strut\digits{___,___,123,456,789.00}} \NC \NR
+\NC \type{___,___,_12,345,678.==} \NC \ruledhbox{\strut\digits{___,___,_12,345,678.==}} \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title={Adding units}]
+
+It is possible to add extra snippets. This is a two step process:
+first some snippet is defined, next a proper label is set up. In the
+next example we define a couple of \TEX\ dimensions:
+
+\startbuffer
+\registerunit
+ [unit]
+ [point=point,
+ basepoint=basepoint,
+ scaledpoint=scaledpoint,
+ didot=didot,
+ cicero=cicero]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Possible categories are: \type {prefix}, \type {unit}, \type {operator},
+\type {suffix}, \type {symbol},\type {packaged}. Next we define labels:
+
+\startbuffer
+\setupunittext
+ [point=pt,
+ basepoint=bp,
+ scaledpoint=sp,
+ didot=dd,
+ cicero=cc]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+Now we can use use these:
+
+\startbuffer
+\unit{10 point / second}
+\stopbuffer
+
+\typebuffer
+
+Of course you can wonder what this means.
+
+\blank \getbuffer \blank
+
+When no label is defined the long name is used:
+
+\startbuffer
+\registerunit
+ [unit]
+ [page=page]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+This is used as:
+
+\startbuffer
+\unit{10 point / page}
+\stopbuffer
+
+\typebuffer
+
+Which gives:
+
+\blank \getbuffer \blank
+
+\stopsection
+
+\startsection[title={Built in keywords}]
+
+A given sequence of keywords is translated in an list of internal
+keywords. For instance \type {m}, \type {Meter} and \type {meter}
+all become \type {meter} and that one is used when resolving a
+label. In the next tables the right column mentions the internal
+keyword. The right column shows the Cased variant, but a lowercase
+one is built|-|in as well.
+
+The following prefixes are built|-|in:
+
+\showunits[prefixes]
+
+The following units are supported, including some combinations:
+
+\showunits[units]
+
+The amount of operators is small:
+
+\showunits[operators]
+
+There is also a small set of (names) suffixes:
+
+\showunits[suffixes]
+
+Some symbols get a special treatment:
+
+\showunits[symbols]
+
+These are also special:
+
+\showunits[packaged]
+
+\startsection[title={Colofon}]
+
+\starttabulate[|B|p|]
+\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR
+\NC version \NC \currentdate \NC \NR
+\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR
+\NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR
+\stoptabulate
+
+\stopsection
+
+\stopdocument
diff --git a/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex b/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex
new file mode 100644
index 000000000..fd4737296
--- /dev/null
+++ b/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex
@@ -0,0 +1,351 @@
+% language=uk
+
+% \usepath[jobfile:]
+% \setupexternalfigures[directory=jobfile:]
+% \usepath[toppath:]
+% \setupexternalfigures[directory=toppath:]
+
+\usemodule
+ [abr-04]
+
+\setupbodyfont
+ [bookman,11pt]
+
+\definecolor
+ [maincolor]
+ [s=.35]
+
+\setuplayout
+ [height=middle,
+ width=middle,
+ footer=0pt]
+
+\setupwhitespace
+ [big]
+
+\setuphead
+ [chapter]
+ [style=\bfc,
+ color=maincolor,
+ header=high]
+
+\setuphead
+ [section]
+ [style=\bfb,
+ color=maincolor]
+
+\setuptyping
+ [color=maincolor]
+
+\setuptype
+ [color=maincolor]
+
+% \showframe
+
+\startdocument
+ [metadata:author=Hans Hagen,
+ metadata:title=Workflow support in context,
+ author=Hans Hagen,
+ affiliation=PRAGMA ADE,
+ location=Hasselt NL,
+ title=workflow,
+ extra=support in context,
+ support=www.contextgarden.net,
+ website=www.pragma-ade.nl]
+
+\definefontfeature[LatinModernMonoVariable][default][liga=no]
+\definefont[LatinModernMonoVariable][LMTypewriterVarWd-Regular*LatinModernMonoVariable sa 1]
+
+\startMPpage
+
+ fill fullsquare xysized(PaperWidth,PaperHeight) withcolor .4white ;
+
+ draw image (
+ fill arrowhead fullcircle scaled .5 rotated 0 scaled 10 withcolor white ;
+ fill arrowhead fullcircle scaled .5 rotated 120 scaled 10 withcolor white ;
+ fill arrowhead fullcircle scaled .5 rotated 240 scaled 10 withcolor white ;
+ fill arrowhead fullcircle scaled .5 rotated 60 scaled 10 withcolor white ;
+ fill arrowhead fullcircle scaled .5 rotated 180 scaled 10 withcolor white ;
+ fill arrowhead fullcircle scaled .5 rotated 300 scaled 10 withcolor white ;
+ ) xsized (.9PaperWidth) shifted (0,.2PaperWidth) ;
+
+ draw image (
+ fill arrowhead fullcircle scaled .5 rotated 0 scaled 10 withcolor .4red withtransparency (1,.5) ;
+ fill arrowhead fullcircle scaled .5 rotated 120 scaled 10 withcolor .4green withtransparency (1,.5) ;
+ fill arrowhead fullcircle scaled .5 rotated 240 scaled 10 withcolor .4blue withtransparency (1,.5) ;
+ fill arrowhead fullcircle scaled .5 rotated 60 scaled 10 withcolor .4cyan withtransparency (1,.5) ;
+ fill arrowhead fullcircle scaled .5 rotated 180 scaled 10 withcolor .4magenta withtransparency (1,.5) ;
+ fill arrowhead fullcircle scaled .5 rotated 300 scaled 10 withcolor .4yellow withtransparency (1,.5) ;
+ ) xsized (.9PaperWidth) shifted (0,.2PaperWidth) ;
+
+ draw textext ("\LatinModernMonoVariable \documentvariable{title}") xsized (.9PaperWidth) shifted (0,-.425PaperWidth) withcolor white ;
+ draw textext ("\LatinModernMonoVariable \documentvariable{extra}") xsized (.9PaperWidth) shifted (0,-.575PaperWidth) withcolor white ;
+
+\stopMPpage
+
+\startfrontmatter
+
+\starttitle[title=Contents]
+
+ \placelist[chapter]
+
+\stoptitle
+
+\stopfrontmatter
+
+\startbodymatter
+
+\startchapter[title=Introduction]
+
+This manual contains some information about features that can help you to manage
+workflows or \CONTEXT\ related processes. Because we use \CONTEXT\ ourselves all
+that we need ends up in the distribution. When you discover something workflow
+related that is not yet covered here, you can tell me. I simply forget about all
+there is (especially if it's made for projects.)
+
+\startlines
+\documentvariable{author},
+\documentvariable{affiliation}
+\documentvariable{location}
+\currentdate[month,year]
+\stoplines
+
+\stopsubject
+
+\stopchapter
+
+\startchapter[title=Accessing resources]
+
+One of the benefits of \TEX\ is that you can use it in automated workflows
+where large quantities of data is involved. A document can consist of
+several files and normally also includes images. Of course there are styles
+involved too. At \PRAGMA\ normally put styles and fonts in:
+
+\starttyping
+/data/site/context/tex/texmf-project/tex/context/user/<project>/...
+/data/site/context/tex/texmf-fonts/data/<foundry>/<collection>/...
+\stoptyping
+
+alongside
+
+\starttyping
+/data/framework/...
+\stoptyping
+
+where the job management services are put, while we put resources in:
+
+\starttyping
+/data/resources/...
+\stoptyping
+
+The processing happens in:
+
+\starttyping
+/data/work/<uuid user space>/
+\stoptyping
+
+Putting styles (and resources like logos and common images) and fonts (if the
+project has specific ones not present in the distribution) in the \TEX\ tree
+makes sense because that is where such files are normally searched. Of course you
+need to keep the distributions file database upto|-|date after adding files there.
+
+Processing has to happen isolated from other runs so there we use unique
+locations. The services responsible for running also deal with regular cleanup
+of these temporary files.
+
+Resources are somewhat special. They can be stable, i.e.\ change seldom, but more
+often they are updated or extended periodically (or even daily). We're not
+talking of a few files here but of thousands. In one project we have 20 thousand
+resources, that can be combined into arbitrary books, and in another one, each
+chapter alone is about 400 \XML\ and image files. That means we can have 5000
+files per book and as we have at least 20 books, we end up with 100K files. In
+the first case accessing the resources is easy because there is a well defined
+structure (under our control) so we know exactly where each file sits in the
+resource tree. In the 100K case there is a deeper structure which is in itself
+predictable but because many authors are involved the references to these files
+are somewhat instable (and undefined). It is surprising to notice that publishers
+don't care about filenames (read: cannot control all the parties involved) which
+means that we have inconsist use of mixed case in filenames, and spaces,
+underscores and dashes creeping in. Because typesetting for paper is always at
+the end of the pipeline (which nowadays is mostly driven by (limitations) of web
+products) we need to have a robust and flexible lookup mechanism. It's a side
+effect of the click and point culture: if objects are associated (filename in
+source file with file on the system) anything you key in will work, and
+consistency completely depends on the user. And bad things then happen when files
+are copied, renamed, etc. In that stadium we can better be tolerant than try to
+get it fixed. \footnote {From what we normally receive we often conclude that
+copy|-|editing and image production companies don't impose any discipline or
+probably simply lack the tools and methods to control this. Some of our workflows
+had checkers and fixers, so that when we got 5000 new resources while only a few
+needed to be replaced we could filter the right ones. It was not uncommon to find
+duplicates for thousands of pictures: similar or older variants.}
+
+\starttyping
+foo.jpg
+bar/foo.jpg
+images/bar/foo.jpg
+images/foo.jpg
+\stoptyping
+
+The xml files have names like:
+
+\starttyping
+b-c.xml
+a/b-c.jpg
+a/b/b-c.jpg
+a/b/c/b-c.jpg
+\stoptyping
+
+So it's sort of a mess, especially if you add arbitrary casing to this. Of course
+one can argue that a wrong (relative) location is asking for problems, it's less
+an issue here because each image has a unique name. We could flatten the resource
+tree but having tens of thousands of files on one directory is asking for
+problems when you want to manage them.
+
+The typesetting (and related services) run on virtual machines. The three
+directories:
+
+\starttyping
+/data/site
+/data/resources
+/data/work
+\stoptyping
+
+are all mounted as nfs shares on a network storage. For the styles (and binaries)
+this is no big deal as normally these files are cached, but the resources are
+another story. Scanning the complete (mounted) resource tree each run is no
+option so there we use a special mechanism in \CONTEXT\ for locating files.
+
+Already early in the development of \MKIV\ one of the locating mechanisms was
+the following:
+
+\starttyping
+tree:////data/resources/foo/**/drawing.jpg
+tree:////data/resources/foo/**/Drawing.jpg
+\stoptyping
+
+Here the tree is scanned once per run, which is normally quite okay when there
+are not that many files and when the files reside on the machine itself. For a
+more high performance approach using network shares we have a different
+mechanism. This time it looks like this:
+
+\starttyping
+dirlist:/data/resources/**/drawing.jpg
+dirlist:/data/resources/**/Drawing.jpg
+dirlist:/data/resources/**/just/some/place/drawing.jpg
+dirlist:/data/resources/**/images/drawing.jpg
+dirlist:/data/resources/**/images/drawing.jpg?option=fileonly
+dirfile:/data/resources/**/images/drawing.jpg
+\stoptyping
+
+The first two lookups are wildcard. If there is a file with that name, it will be
+found. If there are more, the first hit is used. The second and third examples
+are more selective. Here the part after the \type {**} has to match too. So here
+we can deal with multiple files named \type {drawing.jpg}. The last two
+equivalent examples are more tolerant. If no explicit match is found, a lookup
+happens without being selective. The case of a name is ignored but when found, a
+name with the right case is used.
+
+You can hook a path into the resolver for source files, for example:
+
+\starttyping
+\usepath [dirfile://./resources/**]
+\setupexternalfigures[directory=dirfile://./resources/**]
+\stoptyping
+
+You need to make sure that file(name)s in that location don't override ones in
+the regular \TEX\ tree. These extra paths are only used for source file lookups
+so for instance font lookups are not affected.
+
+When you add, remove or move files the tree, you need to remove the \type
+{dirlist.*} files in the root because these are used for locating files. A new
+file will be generated automatically. Don't forget this!
+
+\stopchapter
+
+\startchapter[title=Graphics]
+
+\startsection[title=Bad names]
+
+After many years of using \CONTEXT\ in workflows where large amounts of source files
+as well as graphics were involved we can safely say that it's hard for publishers to
+control the way these are named. This is probably due to the fact that in a
+click|-|and|-|point based desktop publishing workflow names don't matter as one stays on
+one machine, and names are only entered once (after that these names become abstractions and
+get cut and pasted). Proper consistent resource managament is simply not part of the flow.
+
+This means that you get names like:
+
+\starttyping
+foo_Bar_01_03-a.EPS
+foo__Bar-01a_03.eps
+foo__Bar-01a_03.eps
+foo BarA 01-03.eps
+\stoptyping
+
+Especially when a non proportional screen font is used multiple spaces can look
+like one. In fancy screen fonts upper and lowercase usage might get obscured. It
+really makes one wonder if copy|-|editing or adding labels to graphics isn't
+suffering from the same problem.
+
+Anyhow, as in an automated rendering workflow the rendering is often the last step you
+can imagine that when names get messed up it's that last step that gets blamed. It's not
+that hard to sanitize names of files on disk as well as in the files that refer to them,
+and we normally do that we have complete control. This is no option when all the resources
+are synchronzied from elsewhere. In that case the only way out is signaling potential
+issues. Say that in the source file there is a reference:
+
+\starttyping
+foo_Bar_01_03-a.EPS
+\stoptyping
+
+and that the graphic on disk has the same name, but for some reason after an update
+has become:
+
+\starttyping
+foo-Bar_01_03-a.EPS
+\stoptyping
+
+The old image is probably still there so the update is not reflected in the final
+product. This is not that uncommon when you deal with tens of thousands of files,
+many editors and graphic designers, and no strict filename policy.
+
+For this we provide the following tracing option:
+
+\starttyping
+\enabletrackers[graphics.lognames]
+\stoptyping
+
+This will put information in the log file about included graphics, like:
+
+\starttyping
+system > graphics > start names
+
+used graphic > asked : cow.pdf
+used graphic > comment : not found
+used graphic > asked : t:/sources/cow.pdf
+used graphic > format : pdf
+used graphic > found : t:/sources/cow.pdf
+used graphic > used : t:/sources/cow.pdf
+
+system > graphics > stop names
+\stoptyping
+
+You can also information to the file itself:
+
+\starttyping
+\usemodule[s-figures-names]
+\stoptyping
+
+Of course that has to be done at the end of the document. Bad names are reported
+and suitable action can be taken.
+
+\stopsection
+
+\stopchapter
+
+\stopbodymatter
+
+\stopdocument
+
+\disabledirectives[resolvers.maxreadlevel]
diff --git a/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex b/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex
new file mode 100644
index 000000000..677b339db
--- /dev/null
+++ b/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex
@@ -0,0 +1,1041 @@
+% language=uk
+
+% author : Hans Hagen, PRAGMA ADE, NL
+% license : Creative Commons, Attribution-NonCommercial-ShareAlike 3.0 Unported
+
+\usemodule[art-01,abr-02]
+
+\definecolor[red] [darkred]
+\definecolor[green] [darkgreen]
+\definecolor[blue] [darkblue]
+\definecolor[yellow] [darkyellow]
+\definecolor[magenta][darkmagenta]
+\definecolor[cyan] [darkcyan]
+
+\setupexternalfigures
+ [location={local,default}]
+
+\setupbodyfont
+ [10pt]
+
+\setuptyping
+ [color=darkyellow]
+
+\setuptype
+ [color=darkcyan]
+
+% \setupnumbering
+% [alternative=doublesided]
+
+\setuphead
+ [section]
+ [color=darkmagenta]
+
+\setupinteraction
+ [hidden]
+
+\startdocument
+ [metadata:author=Hans Hagen,
+ metadata:title=Extreme Tables,
+ author=Hans Hagen,
+ affiliation=PRAGMA ADE,
+ location=Hasselt NL,
+ title=Extreme Tables,
+ extra=ConTeXt MkIV,
+ support=www.contextgarden.net,
+ website=www.pragma-ade.nl]
+
+\startMPpage
+
+ StartPage ;
+ fill Page enlarged 2mm withcolor magenta/4 ;
+ pickup pencircle scaled 2mm ;
+ numeric n ; n := bbheight Page ;
+ forever :
+ n := n / 1.5 ;
+ draw bottomboundary Page shifted (0, n) withcolor 2yellow/3 withtransparency (1,0.5) ;
+ draw topboundary Page shifted (0,-n) withcolor 2yellow/3 withtransparency (1,0.5) ;
+ exitif n < 2cm ;
+ endfor ;
+ numeric n ; n := bbheight Page ;
+ forever :
+ n := n / 1.5 ;
+ draw leftboundary Page shifted ( n,0) withcolor 2cyan/3 withtransparency (1,0.5) ;
+ draw rightboundary Page shifted (-n,0) withcolor 2cyan/3 withtransparency (1,0.5) ;
+ exitif n < 2cm ;
+ endfor ;
+ picture p, q, r ;
+ p := textext("\ssbf\WORD{\documentvariable{title}}") xsized (bbheight Page - 2cm) rotated 90 ;
+ q := textext("\ssbf\WORD{\documentvariable{author}}") ysized 1cm ;
+ r := textext("\ssbf\WORD{\documentvariable{extra}}") xsized bbwidth q ;
+ draw anchored.rt (p, center rightboundary Page shifted (-1cm,0cm)) withcolor white ;
+ draw anchored.bot(q, center bottomboundary Page shifted ( 1cm,4.4cm)) withcolor white ;
+ draw anchored.bot(r, center bottomboundary Page shifted ( 1cm,2.8cm)) withcolor white ;
+ StopPage ;
+
+\stopMPpage
+
+% \page[empty] \setuppagenumber[start=1]
+
+\startsubject[title={Contents}]
+
+\placelist[section][criterium=all,interaction=all]
+
+\stopsubject
+
+\startsection[title={Introduction}]
+
+This is a short introduction to yet another table mechanism built in \CONTEXT. It
+is a variant of the so called natural tables but it has a different
+configuration. Also, the implementation is completely different. The reason for
+writing it is that in one of our projects we had to write styles for documents
+that had tables spanning 30 or more pages and apart from memory constraints this
+is quite a challenge for the other mechanisms, if only because splitting them
+into successive floats is not possible due to limitations of \TEX. The extreme
+table mechanism can handle pretty large tables and split them too. As each cell
+is basically a \type {\framed} and as we need to do two passes over the table,
+this mechanism is not the fastest but it is some two times faster than the
+natural tables mechanism, and in most cases can be used instead.
+
+\stopsection
+
+\startsection[title={The structure}]
+
+The structure of the tables is summarized here. There can be the usual head, body
+and foot specifications and we also support the optional header in following
+pages.
+
+\starttyping
+\definextable [tag] | [tag][parent]
+\setupxtable [settings] | [tag][settings]
+
+\startxtable[tag|settings]
+ \startxtablehead|next|body|foot[tag|settings]
+ \startxrowgroup[tag|settings]
+ \startxrow[settings]
+ \startxcellgroup[tag|settings]
+ \startxcell[settings] ... \stopxcell
+ \stopxcellgroup
+ \stopxrow
+ \startxrowgroup
+ \stopxtablehead|next|body|foot
+\stopxtable
+\stoptyping
+
+Contrary to what you might expect, the definition command defines a new set of
+command. You don't need to use this in order to set up a new settings
+environment. Settings and definitions can inherit so you can build a chain of
+parent|-|child settings. The grouping is nothing more than a switch to a new set
+of settings.
+
+\stopsection
+
+\startsection[title={Direct control}]
+
+A simple table with just frames is defined as follows:
+
+\startbuffer
+\startxtable
+ \startxrow
+ \startxcell one \stopxcell
+ \startxcell two \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+You can pass parameters for tuning the table:
+
+\startbuffer
+\startxtable[offset=1cm]
+ \startxrow
+ \startxcell one \stopxcell
+ \startxcell two \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+You can (for as much as they make sense) use the same settings as the \type
+{\framed} command, as long as you keep in mind that messing with the frame
+related offsets can have side effects.
+
+\stopsection
+
+\startsection[title={Sets of settings}]
+
+Instead of directly passing settings you can use a predefined set. Of course you
+can also combine these methods.
+
+\startbuffer
+\definextable
+ [myxtable]
+
+\definextable
+ [myxtable:important]
+ [myxtable]
+
+\setupxtable
+ [myxtable]
+ [width=4cm,
+ foregroundcolor=red]
+
+\setupxtable
+ [myxtable:important]
+ [background=color,
+ backgroundcolor=red,
+ foregroundcolor=white]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We can use these settings in table. Although it is not really needed to define a
+set beforehand (i.e.\ you can just use the setup command) it is cleaner and more
+efficient too.
+
+\startbuffer
+\startxtable[myxtable]
+ \startxrow[foregroundcolor=green]
+ \startxcell one \stopxcell
+ \startxcell two \stopxcell
+ \startxcellgroup[foregroundcolor=blue]
+ \startxcell tree \stopxcell
+ \startxcell four \stopxcell
+ \stopxcellgroup
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \startxcellgroup[myxtable:important]
+ \startxcell gamma \stopxcell
+ \startxcell delta \stopxcell
+ \stopxcellgroup
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+The overhead of (chained) settings is quite acceptable and it helps to keep the
+source of the table uncluttered from specific settings.
+
+\stopsection
+
+\startsection[title={Defining}]
+
+If needed you can define your own encapsulating commands. The following example
+demonstrates this:
+
+\startbuffer
+\definextable[mytable]
+\stopbuffer
+
+\getbuffer \typebuffer
+
+We now can use the \type{mytable} wrapper:
+
+\startbuffer
+\startmytable[height=4cm,width=8cm,align={middle,lohi}]
+ \startxrow
+ \startxcell test \stopxcell
+ \stopxrow
+\stopmytable
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+One drawback of using buffers is that they don't play well in macro definitions.
+In that case you need to use the following wrapper:
+
+\startbuffer
+\starttexdefinition MyTable #1#2#3#4
+ \startembeddedxtable
+ \startxrow
+ \startxcell #1 \stopxcell
+ \startxcell #2 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell #3 \stopxcell
+ \startxcell #4 \stopxcell
+ \stopxrow
+ \stopembeddedxtable
+\stoptexdefinition
+\stopbuffer
+
+\typebuffer \getbuffer
+
+This macro is used as any other macro with arguments:
+
+\startbuffer
+\MyTable{one}{two}{three}{four}
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+\stopsection
+
+\startsection[title={Stretching}]
+
+If you don't give the width of a cell, the widest natural size will be taken.
+Otherwise the given width applies to the whole column.
+
+\startbuffer
+\startxtable
+ \startxrow
+ \startxcell[width=1cm] one \stopxcell
+ \startxcell[width=2cm] two \stopxcell
+ \startxcell[width=3cm] tree \stopxcell
+ \startxcell[width=4cm] four \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \startxcell gamma \stopxcell
+ \startxcell delta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+You can let the cells stretch so that the whole width of the text area is taken.
+
+\startbuffer[one]
+\startxtable[option=stretch]
+ \startxrow
+ \startxcell[width=1cm] one \stopxcell
+ \startxcell[width=2cm] two \stopxcell
+ \startxcell[width=3cm] tree \stopxcell
+ \startxcell[width=4cm] four \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \startxcell gamma \stopxcell
+ \startxcell delta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer[one]
+
+The available left over space is equally distributed among the cells.
+
+\startlinecorrection[blank] \getbuffer[one] \stoplinecorrection
+
+\startbuffer[two]
+\startxtable[option={stretch,width}]
+ \startxrow
+ \startxcell[width=1cm] one \stopxcell
+ \startxcell[width=2cm] two \stopxcell
+ \startxcell[width=3cm] tree \stopxcell
+ \startxcell[width=4cm] four \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \startxcell gamma \stopxcell
+ \startxcell delta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+An alternative is to distribute the space proportionally:
+
+\typebuffer[two]
+
+\startlinecorrection[blank] \getbuffer[two] \stoplinecorrection
+
+Just to stress the difference we show both alongside now:
+
+\startlinecorrection[blank]
+ \getbuffer[one]
+ \blank
+ \getbuffer[two]
+\stoplinecorrection
+
+You can specify the width of a cell with each cell but need to keep into mind
+that that value is then used for the whole column:
+
+\startbuffer
+\startxtable
+ \startxrow
+ \startxcell[width=1em] one \stopxcell
+ \startxcell[width=2em] two \stopxcell
+ \startxcell[width=3em] tree \stopxcell
+ \startxcell[width=4em] four \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \startxcell gamma \stopxcell
+ \startxcell delta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+You can enforce that larger columns win via the \type {option} parameter:
+
+\startbuffer
+\startxtable[option=max]
+ \startxrow
+ \startxcell[width=1em] one \stopxcell
+ \startxcell[width=2em] two \stopxcell
+ \startxcell[width=3em] tree \stopxcell
+ \startxcell[width=4em] four \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \startxcell gamma \stopxcell
+ \startxcell delta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+\stopsection
+
+\startsection[title={Spacing}]
+
+It is possible to separate the cells by horizontal and/or vertical space. As an
+example we create a setup.
+
+\startbuffer
+\setupxtable
+ [myztable]
+ [option=stretch,
+ foregroundcolor=blue,
+ columndistance=10pt,
+ leftmargindistance=20pt,
+ rightmargindistance=30pt]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+You can use the \type {textwidth} parameter to set a specific maximum width. We
+now apply the previous settings to an extreme table:
+
+\startbuffer
+\startxtable[myztable]
+ \startxrow
+ \startxcell[width=1cm] one \stopxcell
+ \startxcell[width=2cm,distance=5pt] two \stopxcell
+ \startxcell[width=3cm] tree \stopxcell
+ \startxcell[width=4cm] four \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell[width=1cm] alpha \stopxcell
+ \startxcell[width=2cm] beta \stopxcell
+ \startxcell[width=3cm] gamma \stopxcell
+ \startxcell[width=4cm] delta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+As you can see here, we can still locally overload the settings but keep in mind
+that these apply to the whole column then, not to the specific cell.
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+Vertical spacing is (currently) setup differently, i.e.\ as an argument to the
+\type {\blank} command.
+
+\startbuffer
+\startxtable[spaceinbetween=medium]
+ \startxrow
+ \startxcell one \stopxcell
+ \startxcell two \stopxcell
+ \startxcell tree \stopxcell
+ \startxcell four \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \startxcell gamma \stopxcell
+ \startxcell delta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+Specifying spacing this way improves consistency with the rest of the document
+spacing.
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+\stopsection
+
+\startsection[title={Spanning}]
+
+Of course we can span cells horizontally as well as vertically. Future versions
+might provide more advanced options but the basics work okay.
+
+\startbuffer
+\startxtable
+ \startxrow
+ \startxcell one \stopxcell
+ \startxcell[nx=2] two + three \stopxcell
+ \startxcell four \stopxcell
+ \startxcell five \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell[nx=3] alpha + beta + gamma \stopxcell
+ \startxcell[nx=2] delta + epsilon \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+This spans a few cells horizontally:
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+The next example gives a span in two directions:
+
+\startbuffer
+\startxtable
+ \startxrow
+ \startxcell alpha 1 \stopxcell
+ \startxcell beta 1 \stopxcell
+ \startxcell gamma 1 \stopxcell
+ \startxcell delta 1 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha 2 \stopxcell
+ \startxcell[nx=2,ny=2] whatever \stopxcell
+ \startxcell delta 2 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha 3 \stopxcell
+ \startxcell delta 3 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha 4 \stopxcell
+ \startxcell beta 4 \stopxcell
+ \startxcell gamma 4 \stopxcell
+ \startxcell delta 4 \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+Of course, spanning is always a compromise but the best fit found by this
+mechanism takes natural width, given width and available space into account.
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+\stopsection
+
+\startsection[title={Partitioning}]
+
+You can partition a table as follows:
+
+\startbuffer
+\startxtable
+ \startxtablehead
+ \startxrow
+ \startxcell head one \stopxcell
+ \startxcell head two \stopxcell
+ \startxcell head tree \stopxcell
+ \startxcell head four \stopxcell
+ \stopxrow
+ \stopxtablehead
+ \startxtablenext
+ \startxrow
+ \startxcell next one \stopxcell
+ \startxcell next two \stopxcell
+ \startxcell next tree \stopxcell
+ \startxcell next four \stopxcell
+ \stopxrow
+ \stopxtablenext
+ \startxtablebody
+ \startxrow
+ \startxcell body one \stopxcell
+ \startxcell body two \stopxcell
+ \startxcell body tree \stopxcell
+ \startxcell body four \stopxcell
+ \stopxrow
+ \stopxtablebody
+ \startxtablefoot
+ \startxrow
+ \startxcell foot one \stopxcell
+ \startxcell foot two \stopxcell
+ \startxcell foot tree \stopxcell
+ \startxcell foot four \stopxcell
+ \stopxrow
+ \stopxtablefoot
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+There can be multiple such partitions and they are collected in head, next, body
+and foot groups. Normally the header ends up at the beginning and the footer at
+the end. When a table is split, the first page gets the header and the following
+pages the next one.
+
+You can let headers and footers be repeated by setting the \type {header}
+and|/|or \type {footer} parameters to \type {repeat}.
+
+\starttyping
+\setupxtable
+ [split=yes,
+ header=repeat,
+ footer=repeat]
+\stoptyping
+
+The table can be flushed in the running text but also in successive
+floats. Given that the table is in a buffer:
+
+\starttyping
+\placetable[here,split]{A big table.}{\getbuffer}
+\stoptyping
+
+When you specify \type {split} as \type {yes} the caption is taken into account
+when calculating the available space.
+
+There are actually three different split methods. The \type {yes} option works in
+text mode as well as in floats, but in text mode no headers and footers get
+repeated. If you want that feature in a text flush you have to set \type {split}
+to \type {repeat} as well.
+
+You can keep rows together by passing a \type {samepage} directive. This
+parameter can get the values \type {before}, \type {after} and \type {both}.
+
+\starttyping
+\startxtable[split=yes]
+ \startxrow \startxcell \tttf .01. \stopxcell \stopxrow
+ \startxrow \startxcell \tttf .... \stopxcell \stopxrow
+ \startxrow \startxcell \tttf \red .21. \stopxcell \stopxrow
+ \startxrow[samepage=both] \startxcell \tttf \red .22. \stopxcell \stopxrow
+ \startxrow[samepage=both] \startxcell \tttf \red .23. \stopxcell \stopxrow
+ \startxrow \startxcell \tttf .... \stopxcell \stopxrow
+ \startxrow \startxcell \tttf .99. \stopxcell \stopxrow
+\stopxtable
+\stoptyping
+
+\stopsection
+
+\startsection[title={nesting}]
+
+Extreme tables can be nested but you need to keep an eye on inheritance here as
+the inner table uses the settings from the encapsulating cell. The widths and
+heights of the inner table default to \type {fit}. We could cook up a more
+complex nesting model but this one is easy to follow.
+
+\startbuffer
+\startxtable
+ \startxrow
+ \startxcell[offset=0pt]
+ \startxtable[background=color,backgroundcolor=green,
+ foregroundcolor=white,offset=1ex]
+ \startxrow
+ \startxcell[width=1cm] one \stopxcell
+ \startxcell[width=2cm] two \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell[width=3cm] alpha \stopxcell
+ \startxcell[width=4cm] beta \stopxcell
+ \stopxrow
+ \stopxtable
+ \stopxcell
+ \startxcell two \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell
+ \startxtable[background=color,backgroundcolor=red,
+ foregroundcolor=white]
+ \startxrow
+ \startxcell one \stopxcell
+ \startxcell two \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \stopxrow
+ \stopxtable
+ \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer
+
+Here we just manipulate the offset a bit.
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+\stopsection
+
+\startsection[title={Buffers}]
+
+When you don't want to clutter your document source too much buffers can be if
+help:
+
+\startbuffer
+\startbuffer[test]
+\startxtable
+ \startxrow
+ \startxcell[width=1cm] one \stopxcell
+ \startxcell[width=2cm] two \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell alpha \stopxcell
+ \startxcell beta \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+\stopbuffer
+
+\typebuffer \getbuffer
+
+One way of getting this table typeset is to say:
+
+\starttyping
+\getbuffer[test]
+\stoptyping
+
+Normally this is quite okay. However, internally extreme tables become also
+buffers. If you don't like the overhead of this double buffering you can use the
+following command:
+
+\starttyping
+\processxtablebuffer[test]
+\stoptyping
+
+This can save you some memory and runtime, but don't expect miracles. Also, this
+way of processing does not support nested tables (unless \type {{}} is used).
+
+\stopsection
+
+\startsection[title={XML}]
+
+The following example demonstrates that we can use this mechanism in \XML\ too.
+The example was provided by Thomas Schmitz. First we show how a table looks like
+in \XML:
+
+\startbuffer[test]
+<table>
+ <tablerow>
+ <tablecell>
+ One
+ </tablecell>
+ <tablecell>
+ Two
+ </tablecell>
+ </tablerow>
+ <tablerow>
+ <tablecell>
+ <b>Three</b>
+ </tablecell>
+ <tablecell>
+ Four
+ </tablecell>
+ </tablerow>
+</table>
+\stopbuffer
+
+\typebuffer[test]
+
+We need to map these elements to setups:
+
+\startbuffer
+\startxmlsetups xml:testsetups
+ \xmlsetsetup{main}{b|table|tablerow|tablecell}{xml:*}
+\stopxmlsetups
+
+\xmlregistersetup{xml:testsetups}
+\stopbuffer
+
+\typebuffer \getbuffer
+
+The setups themselves are rather simple as we don't capture any attributes.
+
+\startbuffer
+\startxmlsetups xml:b
+ \bold{\xmlflush{#1}}
+\stopxmlsetups
+
+\startxmlsetups xml:table
+ \startembeddedxtable
+ \xmlflush{#1}
+ \stopembeddedxtable
+\stopxmlsetups
+
+\startxmlsetups xml:tablerow
+ \startxrow
+ \xmlflush{#1}
+ \stopxrow
+\stopxmlsetups
+
+\startxmlsetups xml:tablecell
+ \startxcell
+ \xmlflush{#1}
+ \stopxcell
+\stopxmlsetups
+\stopbuffer
+
+\typebuffer \getbuffer
+
+We now process the example. Of course it will also work for files.
+
+\startbuffer
+ \xmlprocessbuffer{main}{test}{}
+\stopbuffer
+
+\typebuffer
+
+The result is:
+
+\startlinecorrection[blank] \getbuffer \stoplinecorrection
+
+\stopsection
+
+\startsection[title={Natural tables}]
+
+For the impatient a small additional module is provided that remaps the natural
+table commands onto extreme tables:
+
+\startbuffer
+\usemodule[ntb-to-xtb]
+\stopbuffer
+
+\typebuffer \getbuffer
+
+After that:
+
+\startbuffer
+\bTABLE
+ \bTR
+ \bTD[background=color,backgroundcolor=red] one \eTD
+ \bTD[width=2cm] two \eTD
+ \eTR
+ \bTR
+ \bTD[width=5cm] alpha \eTD
+ \bTD[background=color,backgroundcolor=yellow] beta \eTD
+ \eTR
+\eTABLE
+\stopbuffer
+\stopbuffer
+
+\typebuffer
+
+Will come out as:
+
+\startlinecorrection[blank]
+\getbuffer
+\stoplinecorrection
+
+You can restore and remap the commands with the following helpers:
+
+\starttyping
+\restoreTABLEfromxtable
+\mapTABLEtoxtable
+\stoptyping
+
+Of course not all functionality of the natural tables maps onto similar
+functionality of extreme tables, but on the average the result will look rather
+similar.
+
+\stopsection
+
+\startsection[title={Colofon}]
+
+\starttabulate[|B|p|]
+\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR
+\NC version \NC \currentdate \NC \NR
+\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR
+\NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR
+\stoptabulate
+
+\stopsection
+
+\startsection[title={Examples}]
+
+On the following pages we show some examples of (experimental) features. For this
+we will use the usual quotes from Ward, Tufte and Davis etc.\ that you can find
+in the distribution.
+
+\page
+
+\startbuffer
+\startxtable[bodyfont=6pt]
+ \startxrow
+ \startxcell \input ward \stopxcell
+ \startxcell \input tufte \stopxcell
+ \startxcell \input davis \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
+\startxtable[bodyfont=6pt,option=width]
+ \startxrow
+ \startxcell \input ward \stopxcell
+ \startxcell \input tufte \stopxcell
+ \startxcell \input davis \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\page
+
+\startbuffer
+\startxtable[bodyfont=6pt]
+ \startxrow
+ \startxcell \externalfigure[cow.pdf][width=3cm] \stopxcell
+ \startxcell \input tufte \stopxcell
+ \startxcell \input davis \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
+\startxtable[bodyfont=6pt,option=width]
+ \startxrow
+ \startxcell \externalfigure[cow.pdf][width=3cm] \stopxcell
+ \startxcell \input tufte \stopxcell
+ \startxcell \input davis \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\page
+
+\startbuffer
+\startxtable[option=stretch]
+ \startxrow
+ \startxcell bla \stopxcell
+ \startxcell bla bla \stopxcell
+ \startxcell bla bla bla \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\startbuffer
+\startxtable[option={stretch,width}]
+ \startxrow
+ \startxcell bla \stopxcell
+ \startxcell bla bla \stopxcell
+ \startxcell bla bla bla \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer \getbuffer
+
+\page
+
+\startbuffer
+\setupxtable[suffix][align=middle,foregroundcolor=red]
+\setupxtable[blabla][foregroundstyle=slanted]
+\setupxtable[crap] [foregroundcolor=blue]
+\setupxtable[bold] [crap][foregroundstyle=bold]
+
+\startxtable % [frame=off]
+ \startxtablehead
+ \startxrow[bold]
+ \startxcell[suffix] head a \stopxcell
+ \startxcell[blabla] head b \stopxcell
+ \startxcell head c \stopxcell
+ \stopxrow
+ \stopxtablehead
+ \startxtablebody
+ \startxrow
+ \startxcell[suffix][ny=2] cell a 1 \stopxcell
+ \startxcell cell b 1 \stopxcell
+ \startxcell cell c 1 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell cell b 2 \stopxcell
+ \startxcell cell c 2 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell[suffix] cell a 3 \stopxcell
+ \startxcell cell b 3 \stopxcell
+ \startxcell cell c 3 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell[suffix] cell a 4 \stopxcell
+ \startxcell cell b 4 \stopxcell
+ \startxcell cell c 4 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell[suffix] cell a 5 \stopxcell
+ \startxcell cell b 5 \stopxcell
+ \startxcell cell c 5 \stopxcell
+ \stopxrow
+ \stopxtablebody
+\stopxtable
+\stopbuffer
+
+\typebuffer \start \getbuffer \stop
+
+\page
+
+\startbuffer
+\startxtable[option=stretch]
+ \startxrow
+ \startxcell[option=fixed] first cell \stopxcell
+ \startxcell 101 \stopxcell
+ \startxcell 102 \stopxcell
+ \startxcell 103 \stopxcell
+ \stopxrow
+ \startxrow
+ \startxcell 2\high{nd} cell \stopxcell
+ \startxcell a \stopxcell
+ \startxcell b \stopxcell
+ \startxcell c \stopxcell
+ \stopxrow
+\stopxtable
+\stopbuffer
+
+\typebuffer \start \getbuffer \stop
+
+\stopdocument