diff options
Diffstat (limited to 'doc')
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 Binary files differdeleted file mode 100644 index 338008015..000000000 --- a/doc/context/document/general/manuals/mreadme.pdf +++ /dev/null diff --git a/doc/context/document/general/manuals/tiptrick.pdf b/doc/context/document/general/manuals/tiptrick.pdf Binary files differdeleted file mode 100644 index 3ced360e1..000000000 --- a/doc/context/document/general/manuals/tiptrick.pdf +++ /dev/null diff --git a/doc/context/documents/general/manuals/mreadme.pdf b/doc/context/documents/general/manuals/mreadme.pdf Binary files differnew file mode 100644 index 000000000..59cc2a621 --- /dev/null +++ b/doc/context/documents/general/manuals/mreadme.pdf diff --git a/doc/context/documents/general/manuals/swiglib-mkiv.pdf b/doc/context/documents/general/manuals/swiglib-mkiv.pdf Binary files differnew file mode 100644 index 000000000..54d36aeb2 --- /dev/null +++ b/doc/context/documents/general/manuals/swiglib-mkiv.pdf diff --git a/doc/context/documents/general/manuals/tiptrick.pdf b/doc/context/documents/general/manuals/tiptrick.pdf Binary files differnew file mode 100644 index 000000000..edfa6f0ad --- /dev/null +++ b/doc/context/documents/general/manuals/tiptrick.pdf diff --git a/doc/context/documents/general/manuals/tools-mkiv.pdf b/doc/context/documents/general/manuals/tools-mkiv.pdf Binary files differnew file mode 100644 index 000000000..cd2c062eb --- /dev/null +++ b/doc/context/documents/general/manuals/tools-mkiv.pdf diff --git a/doc/context/documents/general/manuals/units-mkiv.pdf b/doc/context/documents/general/manuals/units-mkiv.pdf Binary files differnew file mode 100644 index 000000000..50e09def5 --- /dev/null +++ b/doc/context/documents/general/manuals/units-mkiv.pdf diff --git a/doc/context/documents/general/manuals/xtables-mkiv.pdf b/doc/context/documents/general/manuals/xtables-mkiv.pdf Binary files differnew file mode 100644 index 000000000..0544696d4 --- /dev/null +++ b/doc/context/documents/general/manuals/xtables-mkiv.pdf 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 Binary files differdeleted file mode 100644 index ed8d0456c..000000000 --- a/doc/context/manuals/allkind/mkiv-publications.pdf +++ /dev/null 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 |