
\usemodule[bib]
\setupbodyfont[10pt]
\setupoutput[pdftex]
\startpublication[k=me,
                  t=article,
                  a=Hoekwater,
                  y=1999,
                  s=TH99,
                  n=1]
\artauthor[]{Taco}[T.]{}{Hoekwater}
\arttitle{\CONTEXT\ Publication Module, The user documententation}
\journal{MAPS}
\pubyear{To appear}
\note{In case you didn't know: it's the article you are reading now}
\pages{66--76}
\stoppublication

\setupitemize[each][packed]
\unprotect

\input setupa

\startsetup
    \command[setuppublicationlist]
    \type[\c!vars!]
    \variable[\c!totalnumber][\c!text!][]
    \variable[\c!samplesize][\c!text!][]
    \variable[\c!editor][\tex{invertedauthor},\tex{invertedshortauthor},\tex{normalshortauthor},\tex{normalauthor}][]
    \variable[\c!author][\tex{invertedauthor},\tex{invertedshortauthor},\tex{normalshortauthor},\tex{normalauthor}][]
    \variable[\c!artauthor][\tex{invertedauthor},\tex{invertedshortauthor},\tex{normalshortauthor},\tex{normalauthor}][]
    \variable[\c!namesep][\c!text!][]
    \variable[\c!lastnamesep][\c!text!][]
    \variable[\c!firstnamesep][\c!text!][]
    \variable[\c!juniorsep][\c!text!][]
    \variable[\c!vonsep][\c!text!][]
    \variable[\c!surnamesep][\c!text!][]
    \inheritvariables[\y!setuplist][]
\stopsetup

\startsetup
    \command [setupcite]
    \type    [\c!vals!\c!vars!]
    \value   [author,authoryear,authoryears,key,number,num,page,short,type,year,data][]
    \variable[\c!pubsep][\c!text!][]
    \variable[\c!lastpubsep][\c!text!][]
    \variable[\c!inbetween][\c!text!][]
    \variable[\c!left][\c!text!][]
    \variable[\c!right][\c!text!][]
    \variable[\c!compress][\v!yes,\v!no][]
\stopsetup

\startsetup
    \command[setuppublications]
    \type[\c!vars!]
    \variable[\c!autohang][\v!yes,\v!no][]
    \variable[\c!numbering][\v!yes,\v!no,\v!short,\v!bib][]
    \variable[\c!criterium][\v!all,\v!cite][]
    \variable[\c!sorttype][\v!bbl,\v!cite][]
    \variable[\c!alternative][\c!text!,apa][]
    \variable[\c!refcommand][author,authoryear,authoryears,key,number,num,page,short,type,year,data][]
\stopsetup

\startsetup
    \command [usepublications]
    \type    [\c!vals!]
    \value   [file(s)][]
\stopsetup

\startsetup
    \command [setupbibtex]
    \type    [\c!vars!]
    \variable[database][file(s)][]
    \variable[sort][\v!no,\c!author,\v!title,\v!short][]
\stopsetup


\startsetup
    \command [startpublication]
    \type    [\c!vars!]
    \variable[k][\c!text!][]
    \variable[a][\c!text!][]
    \variable[y][\c!text!][]
    \variable[s][\c!text!][]
    \variable[t][\c!text!][]
    \variable[n][\c!text!][]
\stopsetup

\protect

\def\BIBTEX{Bib\TeX}
\def\MAPS{Maps}


\starttext


\placecontent


\section{Introduction}

This module takes care of references to publications and the
typesetting of publication lists, as well as providing an interface
between \BIBTEX and \CONTEXT.

This is a preliminary version, there might still be changes needed or
wanted in the near future. In particular, there are some minor issues
with the multi-lingual interface that still need to be solved.

The bibliographic subsystem consists of the main module
\type{m-bib.tex}; a helper module (\type{m-list.tex}); four \BIBTEX\
styles (\type{cont-xx.bst}); and an example configuration file
(\type{bibl-apa.tex}) that specifies formatting instructions for the
citations and the list of references.


\subsection{General overview}

A typical input file obeys following structure:
\startitemize[n]
\item A call to \type{\usemodule[bib]}.
\item Some optional setup commands for the bibliographic module.
\item A number of definitions of publications to be referenced in the
main text of the article. The source of these definitions can be
a combination of:
    \startitemize
    \item an implicit \BIBTEX-generated BBL file (read at \type{starttext})
    \item one or more explicit \BIBTEX-generated BBL files
    \item an included definition file in the preamble
    \item included macros before \type{\starttext}
    \stopitemize
    All of these possibilities will be explained below. For now, it is
    only important to realize that of all these definitions have to be known
    {\it before} the first citation in the text.
\item \type{\starttext}
\item The body text, with a number of \type{\cite} commands.
\item The list of publications, called using the command
    \type{\placepublications} or the command\break \type{\completepublications}.
\item \type{\stoptext}
\stopitemize


\section{Setup commands}

Bibliographic references tend to use a specific `style', a collection
of rules for the use of \type{\cite} as well as for the formatting
that is applied to the publication list. The \CONTEXT\ bibliographic
module allows one to define all of these style options in one single
file. Unlike \LATEX, his style includes the formatting of the items
themselves. 

\subsection{Global settings: \type{\setuppublications}}

The most important user-level command is
\type{\setuppublications}. Most of the options to this command
are set by the bibliography style, and
should only be overridden with great care, but a
few of them are of immediate interest to the user. The command
should be given before \type{\starttext}, and it sets some
global information about the bibliographic references used
in the document. \CONTEXT\ needs this information in order
to function correctly. 

\setup{setuppublications}

\starttabulate[|l|p|]
\NC alternative\NC This gives the name of a bibliography style\crlf
     Currently, there is only one style, which is APA-like,
     and that style is therefore also the default.\NC\NR
\NC sorttype\NC How the publications in the final publication
     list should be sorted. `cite' means: by the order in which
     they were first cited in your text. `bbl' tells the
     module to keep the relative ordering in which the publication 
     definitions were found\crlf
     The current default for apa is `cite'\NC\NR 
\NC criterium\NC Whether to list only the referenced
     publications or all of them.\crlf
     If this value is `all', then if `sorttype' equals `cite', this 
     means that all referred-to publications are listed 
     before all others, otherwise (if `sorttype' equals `bbl') you will
     just get a typeset version of the used database(s).\crlf
     The default for apa is `used'\NC\NR
\NC numbering\NC Whether or not the  publication list
     should be labelled and if so, how. \type{yes} uses the item number in
     the publication list as label. \type{short} uses the short
     label. \type{bib}
     uses the original number in the \BIBTEX\ database as a label. 
     Anything else turns labelling off.\crlf
     The default for apa is `no'\NC\NR 
\NC numbercommand\NC A macro that can be used to typeset the label is
    numbering is turned on. The default behaviour is to typeset the label
    as-is, flush left.\NC\NR
\NC autohang\NC Whether or not the
     hanging indent should be re-calculated based on the real size of the
     label. This option only applies if numbering is turned on.\crlf
     The default is `no'.\NC\NR  
\NC refcommand    \NC the default option for \type{\cite}\NC \NR 
\stoptabulate

Since most of the options should be set by a bibliography style,
the specification of `alternative' implies that all other arguments
in the same command will be ignored. If you want to make minor changes
to a bibliography style, do it in two separate commands, like this:

\starttyping
\setuppublications[alternative=apa]
\setuppublications[refcommand=author]
\stoptyping



\subsection{How the entries are formatted: \type{\setuppublicationlist}}

\setup{setuppublicationlist}

The list of publications at the end of the article is essentially a
normal context `list' that behaves much like the list that defines the
table of contents, with the following changes:

The module defines a few new options. These options are static, they
do {\it not} change to follow the selected context interface.

The first two options provide default widths for `autohang':
\starttabulate[|l|p|]
\NC totalnumber\NC The total number of items in the following list (used for autohang).\NC\NR
\NC samplesize\NC The longest short label in the list (used for autohang)\NC\NR
\stoptabulate

All the other extra options are needed to control micro||typesetting
of things that are buried deep within macros. There is a separate
command to handle the larger layout options
(\type{\setuppublicationlayout}, explained below), but the options
here are the only way to make changes in the formatting used for
editors', authors', and article authors' names.
\starttabulate[|l|p|]
\NC editor    \NC command to typeset one editor  in the publication list.\NC \NR 
\NC author    \NC command to typeset one author  in the publication list.\NC \NR 
\NC artauthor \NC command to typeset one article author  in the publication list.\NC \NR 
\NC namesep   \NC the separation between consecutive names (either
                  editors, authors or artauthors).\NC \NR 
\NC lastnamesep   \NC the separation before the last name in a list of names.\NC \NR 
\NC firstnamesep \NC the separation following the fistname or inits within a name in the publication list.\NC \NR 
\NC juniorsep     \NC likewise for `junior'.\NC \NR 
\NC vonsep        \NC likewise for `von'.\NC \NR 
\NC surnamesep     \NC likewise for surname.\NC \NR 
\stoptabulate
The commands after `editor' e.g. are predefined
macros that control how a single name is typeset. The four supplied
macros provide formatting that looks like this:

{\setvalue{@@currentalternative}{data}
\starttabulate[|l|p|]
\NC\tex{invertedauthor}\NC         \invertedauthor{Taco}{von}{Hoekwater}{T}{jr}\NC\NR
\NC\tex{invertedshortauthor}\NC    \invertedshortauthor{Taco}{von}{Hoekwater}{T}{jr}\NC\NR
\NC\tex{normalauthor}\NC           \normalauthor{Taco}{von}{Hoekwater}{T}{jr}\NC\NR
\NC\tex{normalshortauthor}\NC      \normalshortauthor{Taco}{von}{Hoekwater}{T}{jr}\NC\NR
\stoptabulate
}
As you can see in the examples, there is a connection between certain
styles of displaying a name and the punctuation used. Punctuation in
this document has been set up by the `ap' style, and that style makes
sure that \type{\invertedshortauthor} looks good, since that is the default
command for `apa' style. (Keep in mind that the comma at the end of the
author will be inserted by either `namesep' or `lastnamesep'.)

In case you are not happy with the predefined macros; it is quite simple to
define one of these macros yourself, it is a simple macro with 5
arguments: firstnames, von-part, surname, inits, junior.

For reference, here is the definition of \type{\normalauthor},
\starttyping
\def\normalauthor#1#2#3#4#5%
     {\bibdoifelse{#1}{#1\bibalternative{firstnamesep}}{}%
      \bibdoifelse{#2}{#2\bibalternative{vonsep}}{}%
                       #3\bibalternative{surnamesep}%
      \bibdoifelse{#5}{#5}{}}
\stoptyping
but commands can be a lot simpler, like this:
\starttyping
\def\surnameonly#1#2#3#4#5{#3}
\setuppublicationlist[editor=\surnameonly]
\stoptyping


Apart from these extra options,
the module itself sets some of the options to the internal call to
\type{\setuplist} itself.

To get a reasonable layout for the reference list, the following are
set as a precaution:
\starttabulate[|l|p|]
\NC alternative\NC Always re-initialized to `a'. This makes sure that no
space is allocated for the page number.\NC\NR
\NC pagenumber\NC Always re-initialized to `no'. The list is a bit of
a special one, and page numbers don't make much sense. All entries
will (currently) have the same page number: the number of the page on
which \type{\placepublications} was called.\NC\NR
\NC criterium\NC Always set to `all'. You need this! If you want
partial lists, set `criterium' to `used', and `sorttype' to
`cite'. This combination will reset itself after each call to 
\type{\placepublications}\NC\NR
\stoptabulate


And also, the following options are initialized depending on the
global settings for `numbering' and `autohang':
\starttabulate[|l|p|]
\NC width\NC Set to the calculated width of the largest label (only if autohang is `yes')\NC\NR
\NC distance\NC Set to 0pt (only if autohang is `yes')\NC\NR
\NC numbercommand\NC The command given in `setuppublications' if numbering is turned on, otherwise empty.\NC\NR
\NC textcommand\NC Set to a macro that outdents the body text if numbering is turned off, otherwise empty\NC\NR
\stoptabulate



\subsection{Setting citation options: \type{\setupcite}}

The \type{\cite} command has a lot of sub-options, as could be seen
above in the setting of `refcommand'. And even the options have options:

\setup{setupcite}

Here are the possible keywords:
\starttabulate[|l|p|]
\NC pubsep       \NC separator between publication references in a 
                  \type{\cite} command.\NC \NR 
\NC lastpubsep   \NC same, but for the 
                    last publication in the list.\NC \NR 
\NC left  \NC left side of a \type{\cite} (like \type{[})\NC \NR 
\NC inbetween \NC the separator between parts of a single citation.\NC\NR
\NC right     \NC right side of a \type{\cite} (like \type{]})\NC \NR 
\NC compress \NC Whether \type{\cite} should try to
compress it's argument list. 
The default is `yes'\NC\NR
\stoptabulate
Not all options apply to all types of \type{\cite} commands.
E.g. `compress'  does not apply to the citation
list for all options of \type{\cite}, since sometimes compression does
not make sense or is not possible. The `num' version compresses
into a condensed sorted list, and the various `author' styles try
to compress all publications by one author, but e.g. years are
never compressed.

Likewise, `inbetween' only applies to three types: `authoryear' (a
space), `authoryears' (a comma followed by a space), and `num' (where
it is `--' (an endash), the character used to separate number ranges).

\subsection{Setting up \BIBTEX: \type{\setupbibtex}}

\BIBTEX\ bibliographic databases are converted into \type{.bbl} files,
and the generated file is just a more \TEX-minded representation of
the full database(s).

The four \type{.bst} files do not do any actual formatting on the
entries, and they do not subset the database either. Instead, the
{\it entire} database is converted into \TEX-parseable records. About the
only thing the \type{.bst} files do is sorting the entries (and
\BIBTEX\ itself resolves any `STRING' specifications, of course).

The module will read the created \type{\jobname.bbl} file
and select the parts that are needed for the current article.

\setup{setupbibtex}

\starttabulate[|l|p|]
\NC database\NC List of bibtex database file names to be
     used. The module will write a very short \type{.aux} file instructing
     \BIBTEX\ to create a (possibly very large) \type{\jobname.bbl} file,
     that will be \type{\input} by the module (at \type{\starttext}).\NC\NR
\NC sort\NC How the publications in the
     \BIBTEX\ database file should be sorted.\crlf
     The default here is `no' (\type{cont-no.bst}), meaning no sorting at all. 
     `author' (\type{cont-au.bst}) sorts alphabetically on author and within that on year,
     `title' (\type{cont-ti.bst}) sorts alphabetically on title and then on author and
     year, and `short' (\type{cont-ab.bst}) sorts on the short key that is generated
     by \BIBTEX.\NC\NR 
\stoptabulate

For now, you need to run \BIBTEX\ by hand to create the
\type{\jobname.bbl} file (\type{texutil} will hopefully do this for
you in the future). 

You may want to create the \type{\jobname.bbl} yourself. The
\type{.bbl} syntax is explained below. There is no default
database of course, and you do not {\it have} to use one: it is
perfectly OK to just \type{\input} a file with the bibliographic
records, as long as it has the right input syntax. Or even to include
the definitions themselves in the preamble of your document.

The most efficient calling order when using \BIBTEX\ is:
\starttyping
texexec --once myfile
bibtex myfile
texexec myfile
\stoptyping

Texexec should be smart enough to recognize how many
runs are needed in the final part, but it seems it
sometimes does one iteration too few. So you might
have to call texexec one last time to get the page references
correct. Numbered references always need at least one run more
than author, year references, because the final number in
the reference list is usually not decided upon yet at the 
moment the \type{\cite} command is encountered.


\subsection{Borrowing publications: \type{\usepublications}}

It is also possible to instruct the module to use the bibliographic 
references belonging to another document. This is done by using the command
\type{\usepublications[files]}, where \type{files} is a list of other
\CONTEXT\ documents (without extension). 

\setup{usepublications}

To be precise, this command will use the \type{.bbl} and \type{.tuo}
files from the other document(s), and will therefore not work if these
files cannot be found (the \type{.tuo} file is needed to get correct
page references for \type{\cite[page]}).


\section{Citations}

Citations are handled through the \type{\cite} command.

\type{\cite} has three basic appearances:

\starttabulate[|l|p|]
\NC\type{\cite[keys]}\NC Executes the style-defined default
  citation command. This is the preferred way of usage, since
  some styles might use numeric citations while others might
  use a variation of the (author,year) style.\crlf
  `keys' is a list of one of more publication IDs.\NC\NR
\NC\type{\cite[option][keys]}\NC The long form, which 
  allows you to manually select the style you want. See below
  for the list of valid `option's.\NC\NR
\NC\type{\cite$\{$keys$\}$}\NC For compatibility (with 
  existing \LATEX\ .bib databases). Please
  don't use this form in new documents or databases.\NC\NR
\stoptabulate

\subsection{Cite options}

Right now, the interesting bits are the keys
for the argument of \type{\startpublication}


Following is the full list of recognized keywords for \type{\cite},
with a short explanation where the data comes from. Most of the
information that is usable within \type{\cite} comes from the argument
to \type{\startpublication}. This command is covered in detail below, 
but here is an example:

\starttyping
\startpublication[k=me,
                  t=article,
                  a=Hoekwater,
                  y=1999,
                  s=TH99,
                  n=1]
...
\stoppublication
\stoptyping


All of these options are {\it valid} in all publication styles, since
\CONTEXT\ always has the needed information available. But not all of
these are {\it sensible} in a particular style: using numbered references if
the list of publications itself is not numbered is not a good idea, for
instance. Also, some of the keys are somewhat strange and only
provided for future extensions.

First, here are the simple ones:
\starttabulate[|l|l|p|]
\NC author\NC      \cite[author][me] \NC(from `a')\hfil\NC\NR
\NC key\NC         \cite[key][me]\NC (from `k')\hfil\NC\NR
\NC number\NC      \cite[number][me]\NC (from `n')\hfil\NC\NR
\NC short\NC       \cite[short][me]\NC (from `s')\hfil\NC\NR
\NC type\NC        \cite[type][me]\NC (from `t')\hfil\NC\NR
\NC year\NC        \cite[year][me]\NC (from `y')\hfil\NC\NR
\stoptabulate
Keep in mind that `n' is a database sequence number, and not
necesarily the same number that is used in the list of
publications. For instance, if `sorttype' is cite, the list will be
re-ordered, but the `n' value will remain the same. To get to the
number that is finally used, use
\starttabulate[|l|l|p|]
\NC num\NC         \cite[num][me]\NC (this is a reference to
                                        the sequence number used in the publication list)\hfil\NC\NR
\stoptabulate
If the list of publications is not numbered visually, there will still
be a number available.

Three of the options are combinations:
\starttabulate[|l|l|p|]
\NC authoryear\NC  \cite[authoryear][me]\NC(from `a' and `y')\hfil\NC\NR
\NC authoryears\NC \cite[authoryears][me]\NC(from `a' and `y')\hfil\NC\NR
\NC data\NC        \vtop{\hsize .45\hsize \cite[data][me]}\NC The data content of the entry\hfil\NC\NR
\stoptabulate

And the last one is a page reference to the {\it first} place where
the entry was cited. This is not always the page number in the list of
publications: if there was a \type{\cite[data]} somewhere in the
document, that page number will be the number used (as you can see
from the example).
\starttabulate[|l|l|p|]
\NC page\NC        \cite[page][me]\NC (a page reference)\hfil\NC\NR
\stoptabulate


\section{Placing the publication list}

This is really simple: use \type{\completepublications} 
or \type{\placepublications} at the location in your
text where you want the publication list to appear. As is normal in
\CONTEXT, \type{\placepublications} gives you a raw list, and
\type{\completepublications} a list with a heading. The module uses
the following defaults for the generated head:
\starttyping
\setupheadtext[en][pubs=References]
\setupheadtext[nl][pubs=Literatuur]
\setupheadtext[du][pubs=Literatur]
\stoptyping
These can be redefined as needed.

\section{The bbl file}

A typical bbl file consists of one initial command 
(\type{\setuppublicationlist}) that sets some information
about the number of entries in the bbl file and the widths
of the labels for the list, and that command is followed by a number of
appearances of:
\starttyping
\startpublication[k=,
                  t=,
                  a=,
                  y=,
                  s=,
                  n=]
... 
\stoppublication 
\stoptyping

The full appearance version of \type{\cite} 
accepts a number of option keywords, and we saw earlier that
the argument of the \type{\startpublication} command
defines most of the things we can reference to. This section explains
the precise syntax for \type{\startpublication}.


Each single block defines one bibliographic entry. I apologise
for the use of single||letter keys, but these have the advantage of
being a)\quad short and b)\quad safe w.r.t. the multi-lingual interface.

Each entry becomes one internal \TeX\ command.

\setup{startpublication}

Here is the full example that has been used throughout this document:
\starttyping
\startpublication[k=me,
                  t=article,
                  a=Hoekwater,
                  y=1999,
                  s=TH99,
                  n=1]
\artauthor[]{Taco}[T.]{}{Hoekwater}
\arttitle{\CONTEXT\ Publication Module, The user documententation}
\journal{MAPS}
\pubyear{To appear}
\note{In case you didn't know: it's the article you are reading now}
\pages{66--76}
\stoppublication
\stoptyping

\subsection{Defining a publication}

Here is the full list of commands that can appear
between \type{\startpublication} and \type{\stoppublication}. All
top-level commands within such a block should be one of the following
(if you use other commands, they might be typeset at the beginning of
your document or something similar).

Order within an entry is irrelevant, except for the relative
order of the three commands that might appear more than
once: \type{\artauthor}, \type{\author} and \type{\editor}.

Here is the full list of commands that can be used. Most of
these are `normal' \BIBTEX\ field names (in lowercase), but some
are extra special, either because they come from non-standard
databases that I know of, or because the bst file has pre-processed
the contents of the field:

\starttabulate[|l|p|]
\NC\type{\abstract{\#1}}\NC just text.\NC\NR
\NC\type{\annotate{\#1}}\NC just text.\NC\NR
\NC\type{\artauthor[\#1]{\#2}[\#3]{\#4}{\#5}}\NC For an author of any publication
    that appears within a larger publication, like an article that appears
    within a journal or as part of a proceedings. \NC\NR
\NC\type{\arttitle{\#1}}\NC The title of such a partial publication.\NC\NR
\NC\type{\author[\#1]{\#2}[\#3]{\#4}{\#5}}\NC The author of a standalone
    publication, like a monograph.\NC\NR
\NC\type{\chapter{\#1}}\NC the chapter number, if this entry is
referring to a smaller section of a publication. It might actually
be a part number or a (sub)section number, but the \BIBTEX\ field
happens to be called \type{CHAPTER}. The field \type{\type} (below) 
differentiates between these.\NC\NR
\NC\type{\city{\#1}}\NC city of publication.\NC\NR
\NC\type{\comment{\#1}}\NC just text.\NC\NR
\NC\type{\country{\#1}}\NC country of publication.\NC\NR
\NC\type{\crossref{\#1}}\NC A cross-reference to another 
    bibliographic entry. It will insert a citation
    to that entry, forcing it to be typeset as well.\NC\NR
\NC\type{\edition{\#1}}\NC The edition.\NC\NR
\NC\type{\editor[\#1]{\#2}[\#3]{\#4}{\#5}}\NC The editor of e.g.
    an edited volume.\NC\NR
\NC\type{\institute{\#1}}\NC The institute at which the publication
    what published.\NC\NR
\NC\type{\isbn{\#1}}\NC isbn number (for books)\NC\NR
\NC\type{\issn{\#1}}\NC issn number (for journals)\NC\NR
\NC\type{\issue{\#1}}\NC issue number (for journals)\NC\NR
\NC\type{\journal{\#1}}\NC The journal's name.\NC\NR
\NC\type{\keyword{\#1}}\NC just text (for use in indices).\NC\NR
\NC\type{\keywords{\#1}}\NC just text (for use in indices).\NC\NR
\NC\type{\month{\#1}}\NC month of publication\NC\NR
\NC\type{\names{\#1}}\NC just text (for use in indices).\NC\NR
\NC\type{\note{\#1}}\NC just text (this is the 
            `standard' \BIBTEX\ commentary field).\NC\NR
\NC\type{\notes{\#1}}\NC just text.\NC\NR
\NC\type{\organization{\#1}}\NC Like institute, but for e.g. companies.\NC\NR
\NC\type{\pages{\#1}}\NC Either the number of pages, or the page range
         for a partial publication. The `t' key to startpublication
         will decide automatically what is meant.\NC\NR
\NC\type{\pubname{\#1}}\NC Publisher's name.\NC\NR
\NC\type{\pubyear{\#1}}\NC Year of publication. Within this command,
        the \BIBTEX\ bst files will sometimes insert the command
        \type{\maybeyear}, which is needed to make sure that 
        the bbl file stay flexible enough to allow all styles of
        formatting.\NC\NR
\NC\type{\series{\#1}}\NC Possible book series information.\NC\NR
\NC\type{\size{\#1}}\NC Size in KB of a PDF file (this came from
        the NTG \MAPS\ database)\NC\NR
\NC\type{\thekey{\#1}}\NC \BIBTEX's `KEY' field. See the \BIBTEX\ 
    documentation for it's use. This is {\it not} related to
    the key used for citing this entry.\NC\NR
\NC\type{\title{\#1}}\NC The title of a book.\NC\NR
\NC\type{\type{\#1}}\NC \BIBTEX's `TYPE' field. See the \BIBTEX\ 
    documentation for it's use. This is {\it not} related
    to the type of entry that is used for deciding on the
    layout.\NC\NR
\NC\type{\volume{\#1}}\NC Volume number for multi-part books or 
    journals.\NC\NR
\stoptabulate
Rather a large list, this is caused by the desire to support as many
existing \BIBTEX\ databases as possible. 

As you can see, almost all commands have precisely one argument. The
only exceptions are the three commands that deal ith names:
\type{\artauthor}, \type{\author} and \type{\editor}.  At the moment,
these three commands require 5 arguments (of which two look like they
are optional. They are {\it not}!) 


Adding in one of your own fields is reasonably simple:

\starttyping
\newbibfield[mycommand]
\stoptyping
This will define \type{\mycommand} for use within
a publication (plus \type{\bib@mycommand}, it's internal form) as
well as the command \type{\insertmycommand} that can be used
within \type{\setuppublicationlayout} to fetch the supplied
value (see below). 


\section{Defining a publication type layout}

Publication style files of course take care of setting defaults for the
commands as explained earlier, but the largest part of a such a
publication style is concerned with specifying layouts for various
types of publications.

The command that does the work is \type{\setuppublicationlayout}.  It
has an option argument that is a \type{type}, and all publications
that have this type given as argument to the `t' key of
\type{\startpublication} will be typeset by executing the commands
that appear in the group following the command.

For reference, here is one of the commands from \type{bibl-apa}:
\starttyping
\setuppublicationlayout[article]{%
   \insertartauthors{}{ }{\insertthekey{}{ }{}}%
   \insertpubyear{(}{). }{\unskip.}%
   \insertarttitle{\bgroup }{\egroup. }{}%
   \insertjournal{\bgroup \it}{\egroup}
    {\insertcrossref{In }{}{}}%
   \insertvolume
    {, }
    {\insertissue{(}{)}{}\insertpages{:}{.}{.}}
    {\insertpages{, pages }{.}{.}}%
   \insertnote{ }{.}{}%
   \insertcomment{}{.}{}%
}
\stoptyping
For every command in the long list given in the previous paragraph, there is 
a corresponding \type{\insertxxx} command. (As usual, \type{\author}
etc. are special: they have a macro called \type{\insertxxxs}
instead). All of these \type{\insertxxx} macros use the same logic:

\starttyping
\insertartauthors{<before>}{<after>}{<not found>}
\stoptyping

Sounds easy? It is! But it is also often tedious: database entries can
be tricky things: some without issue numbers, others without page
numbers, some even without authors. So, you often need to nest rather
a lot of commands in the \type{<not found>} section of the `upper'
command, and \type{\unskip} and \type{\ignorespaces} are good friends
as well.

There is nothing special about the type name you give in the argument,
except that every \type{\startpublication} that does not have a `t'
key is assumed to be of type `article', and undefined `t' values imply
that the data is completely ignored.

\type{bibl-apa} defines layouts for the `standard' publication types
that are defined in the example bibliography that comes with \BIBTEX.

\completepublications

\stoptext


Changes since Jun 25, 2001:

All .bst files:

  New keys : 
	\doi + 'o='   (all types)
	\eprint       (all types)
	\howpublished (booklet,misc: previously mapped to \pubname)

  Output of default \types no longer happens (moved to bibl-xxx)
	'chapter'
	'Technical report'
	'Master's Thesis'
	'PhD thesis'
 
  Case changing of \edition and \type no longer happens

Totally new bibliography style for Physics: bibl-aps.tex

Bibl-apa.tex:

  support for \cite[doi] (cf. 'short')
 
  support for Oxford Comma ('finalnamesep' parameter)
 
  6 new keys for 'et.al.' limitation:
	'artauthoretallimit'
	'artauthoretaltext'
	'authoretallimit'
	'authoretaltext'
	'editoretallimit'
	'editoretaltext'

  bugfix on line 261 (inproceedings: 'authors' instead of 'artauthors') 

  bugfix on line 282 (inproceedings: formatting around 'pubname')

  insert default \types (4x)

M-bib.tex:

   New constants:

	    authoretallimit: authoretallimit authoretallimit
	 artauthoretallimit: artauthoretallimit artauthoretallimit
	    editoretallimit: editoretallimit editoretallimit
	     authoretaltext: authoretaltext authoretaltext
	  artauthoretaltext: artauthoretaltext artauthoretaltext
	     editoretaltext: editoretaltext editoretaltext
	       finalnamesep: finalnamesep finalnamesep

   New simlebibdefs:

	doi
	eprint
	howpublished

  
  Et.al. support in \complexbibinsert

  'o=' support (and \bibdoiref) for \cite 

  splitoff \preinitializepublist from \initializepublist, and a
  sneaky bugfix for \schrijfnaarlijst

  bugfix: indirection added for '@@pbinummercommando' (ConTeXt core changed)

  bugfix on 748: \reference expansion order changed in \dotypesetapublication
	 (a series of \@EA's added)

  bugfix on 890: \getcommacommandsize added (inside \dobibauthoryear)

  bugfix on 902: \relax added for counter assignment
