Author: frank Date: 2006-10-06 16:24:26 +0000 (Fri, 06 Oct 2006) New Revision: 1689
Removed: tetex-base/branches/upstream/3.0.dfsg.1/doc/context/bib/bibmod-doc.tex Log: deleting context documentation that was forgotten when repackaging Deleted: tetex-base/branches/upstream/3.0.dfsg.1/doc/context/bib/bibmod-doc.tex =================================================================== --- tetex-base/branches/upstream/3.0.dfsg.1/doc/context/bib/bibmod-doc.tex 2006-10-06 16:24:20 UTC (rev 1688) +++ tetex-base/branches/upstream/3.0.dfsg.1/doc/context/bib/bibmod-doc.tex 2006-10-06 16:24:26 UTC (rev 1689) @@ -1,807 +0,0 @@ - -\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 [EMAIL PROTECTED], 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 [EMAIL PROTECTED]'s added) - - bugfix on 890: \getcommacommandsize added (inside \dobibauthoryear) - - bugfix on 902: \relax added for counter assignment _______________________________________________ Pkg-tetex-commits mailing list Pkg-tetex-commits@lists.alioth.debian.org http://lists.alioth.debian.org/mailman/listinfo/pkg-tetex-commits