diff options
Diffstat (limited to 'Master/texmf-dist/doc')
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/CHANGES | 9 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/Makefile | 44 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/README | 12 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/idxstyle.ist | 39 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/local.bib | 132 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.pdf | bin | 0 -> 910956 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.ps.gz | bin | 0 -> 429694 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec1.tex | 570 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec2.tex | 672 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec3.tex | 749 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec4.tex | 841 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec5.tex | 179 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.tex | 145 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_style.sty | 130 |
14 files changed, 3522 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/CHANGES b/Master/texmf-dist/doc/bibtex/tamethebeast/CHANGES new file mode 100644 index 00000000000..68397e16ec3 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/CHANGES @@ -0,0 +1,9 @@ +v1.00 2004/07/21 First release on CTAN. +v1.01 2004/08/15 Corrected two related errors in sec3 + (about left brace and @preamble) +v1.10 2005/03/06 Some corrections. + Added hyperref. +v1.20 2005/06/10 Added LPPL licence notes + Minor corrections and additions +v1.30 2005/10/16 Corrected many typos (thanks to Roger Jeurissen + and Maarten Grachten) diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/Makefile b/Master/texmf-dist/doc/bibtex/tamethebeast/Makefile new file mode 100644 index 00000000000..647f51b3333 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/Makefile @@ -0,0 +1,44 @@ +## Makefile +## Copyright 2003-2005 Nicolas Markey +# +# This work may be distributed and/or modified under the +# conditions of the LaTeX Project Public License, either version 1.3 +# of this license or (at your option) any later version. +# The latest version of this license is in +# http://www.latex-project.org/lppl.txt +# and version 1.3 or later is part of all distributions of LaTeX +# version 2003/12/01 or later. +# +# This work has the LPPL maintenance status "maintained". +# The Current Maintainer of this work is Nicolas Markey +# +# This work consists of the files +# ttb_en.tex +# ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +# ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +# local.bib idxstyle.ist Makefile +# and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + +all: + LATEX=latex make tex + dvips ttb_en -o + +pdf: + LATEX=pdflatex make tex + +tex: *.tex + ${LATEX} ttb_en.tex + makeindex -s idxstyle.ist bibtex + makeindex -s idxstyle.ist latex + bibtex ttb_en + ${LATEX} ttb_en.tex + ${LATEX} ttb_en.tex + +clean: + rm -f *.aux ttb_en.log ttb_en.blg *.ilg *.ind *.idx \ + ttb_en.bbl ttb_en.toc ttb_en.dvi ttb_en.out \ + ttb_en.ptc* ttb_en.mtc* ttb_en.bmt *~ + +tgz: + tar zcvf ttb_en.tgz Makefile ttb_*.tex ttb_*.sty local.bib \ + idxstyle.ist README CHANGES diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/README b/Master/texmf-dist/doc/bibtex/tamethebeast/README new file mode 100644 index 00000000000..e39177d4fad --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/README @@ -0,0 +1,12 @@ +Tame the BeaST -- The B to X of BibTeX +======================================== + Nicolas MARKEY + <markey@lsv.ens-cachan.fr> + v1.3 2005/10/16 + + +This is an (as complete as possible) documentation +about bibliographies in LaTeX, thus mainly about +BibTeX. + +Comments welcome! diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/idxstyle.ist b/Master/texmf-dist/doc/bibtex/tamethebeast/idxstyle.ist new file mode 100644 index 00000000000..d93f54269f8 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/idxstyle.ist @@ -0,0 +1,39 @@ +%% idxstyle.ist +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf +% +% +% This file is derived from fridx1.ist: +% FICHIER fridx1.ist +% Personnalisation Numero 1 d'un index (faire makeindex -s fridx1.ist) +% -------------------------------------------------------------------- + +headings_flag 1 +heading_prefix "{\\large \\bf \\hfil--\\ " +heading_suffix " --\\ \\hfil}\\nopagebreak\n" +symhead_negative "symbols" +symhead_positive "Symbols" + +delim_0 " \\dotfill \ " +delim_1 " \\dotfill \ " +delim_2 " \\dotfill \ " +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/local.bib b/Master/texmf-dist/doc/bibtex/tamethebeast/local.bib new file mode 100644 index 00000000000..f24ffb664cf --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/local.bib @@ -0,0 +1,132 @@ +%% local.bib +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + +@book{latex:dps, + author = "Lamport, Leslie", + title = "{{\LaTeX}}: a Document Preparation System", + publisher = "Addison-Wesley", + year = 1997, + month = mar, +} + +@book{latex:lc, + title = "The {{\LaTeX}} Companion", + author = "Goossens, Michel and Mittelbach, Frank and Samarin, + Alexander", + publisher = "Addison-Wesley", + year = 1993, + month = dec, +} + +@book{latex:lc2, + title = "The {{\LaTeX}} Companion~--- Second Edition", + author = "Mittelbach, Frank and Goossens, Michel and + Braams, Johannes and Carlisle, David and Rowley, Chris", + publisher = "Addison-Wesley", + year = 2004, + month = apr, +} + + +@manual{natbib, + author = "Daly, Patrick W.", + title = "Natural Sciences Citations and References", + year = 1999, + month = may, + } + +@manual{bibentry, + author = "Daly, Patrick W.", + title = "A {{\LaTeX}} Package to Place Bibliography Entries in Text", + year = 1999, + month = feb, + } + +@manual{multibib, + author = "Hansen, Thorsten", + title = "The {\textbf{multibib}} package", + year = 2000, + month = jan, +} + +@manual{bibunit, + author = "Hansen, Thorsten", + title = "The {\textbf{bibunits}} package", + year = 2000, + month = oct, +} + +@manual{footbib, + author = "Dommenjoud, {\'E}ric", + title = "The {\textbf{footbib}} package", + year = 1997, + month = mar, +} + +@manual{merlin, + author = "Daly, Patrick W.", + title = "A Master Bibliographic Style File", + year = 1999, + month = may, + } + +@manual{splitbib, + author = "Markey, Nicolas", + title = "The {\textbf{splitbib}} package", + year = 2005, + month = feb, +} + +@manual{jurabib, + author = "Berger, Jens", + title = "The {\textbf{jurabib}} package", + year = 2002, + month = sep, +} + +@manual{jmpl, + author = "Bayart, Benjamin", + title = "Joli Manuel pour {{\LaTeX}}", + year = 1995, + month = dec, +} + +@book{desg, + title = "{{\LaTeX}}~: Apprentissage, Guide et R{\'e}f{\'e}rences", + author = "Desgraupes, Bernard", + publisher = "Vuibert", + year = 2000, + month = nov, + } + +@manual{btxdoc, + author = "Patashnik, Oren", + title = "{\textsc{Bib}}{{\TeX}}ing", + year = 1988, + month = feb, +} + +@manual{btxhak, + author = "Patashnik, Oren", + title = "Designing {\textsc{Bib}}{{\TeX}} styles", + year = 1988, + month = feb, +} diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.pdf b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.pdf Binary files differnew file mode 100644 index 00000000000..a5a89966c1e --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.pdf diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.ps.gz b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.ps.gz Binary files differnew file mode 100644 index 00000000000..56748003dc0 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.ps.gz diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec1.tex b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec1.tex new file mode 100644 index 00000000000..6d40692260c --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec1.tex @@ -0,0 +1,570 @@ +%% ttb_en.sec1.tex +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + +\mypart{Basic bibliography with \LaTeX}\label{part1} +\parttoc +\mtcskip + +\bt is often seen as something magical, as well as \LaTeX +bibliography-related commands in general. Many users simply copy and paste +classical examples without trying to understand how it works. But in +fact, a bibliography in \LaTeX is nothing but a \emph{list} of +\emph{references} mentioned in a document. If we had to do it ``by +hand'', +without knowing anything about the \env{thebibliography} environment, +it could look like this: + +\medskip +\begin{verbatim} +This is the main matter of the document, mentioning +[\ref{doc1}] and [\ref{doc2}], for instance. +\section*{References} +\begin{enumerate} + \renewcommand\labelenumi{[\theenumi]} %% numbers are surronded with brackets + \item \label{doc1} Michel Goossens, Franck Mittelbach and Alexander + Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993. + \item \label{doc2} Leslie Lamport, \emph{\LaTeX: A Document Preparation + System}, Addison Wesley, 1997. +\end{enumerate} +\end{verbatim} +\noindent which, when compiled, gives +\begin{myex} +This is the main matter of the document, mentioning +[\ref{doc1}] and [\ref{doc2}], for instance. +\section*{References} +\begin{enumerate} + \renewcommand\labelenumi{[\theenumi]} %% numbers are between brackets + \item \label{doc1} Michel Goossens, Franck Mittelbach and Alexander + Samarin, \emph{The \LaTeX Companion}, Addison Wesley, 1993. + \item \label{doc2} Leslie Lamport, \emph{\LaTeX: A Document Preparation + System}, Addison Wesley, 1997. +\end{enumerate} +\end{myex} + +This is mostly what the \env{thebibliography} environment does (it +starts a \env{list} environment, similar to~\env{enumerate}), +\cmd{bibitem} corresponding +to the \cmd{item} commands. One major difference is that \cmd{bibitem} +allows for more general cross-references than \cmd{item} and +\cmd{label} (for example, one can cite~\cite{latex:lc}). + + +This is what this part deals with: ``Writing a bibliography +\emph{without} \bt''. This is not the main goal of this manual, but +it is a cornerstone for understanding the sequel. + + +\mysection{The \nienv{thebibliography} environment} + + +%% +%% Fin trad. +%% + +The \env{thebibliography} environment is not defined in \LaTeX +itself (neither is it in \TeX\footnote{\bt may be used with plain \TeX, +you'll simply have to input the \sty[tex]{btxmac} package}, of course). It has +to be defined by the +class file used in the document (\emph{e.g.} \cls{article} or +\cls{book}). As mentioned earlier, it is a \env{list}-like +environment inside a new \cmd{section} (or \cmd{chapter}, depending on +the document class\footnote{This is the reason why \env{thebibliography} +has to be defined in the class files. The +other bibliographic commands are defined in the standard \LaTeX format.}). +This list has to be set up carefully, however, in order to avoid indentation +problems. For instance, if we put ``alphanumerical'' labels in the previous +example, we would get: +\begin{myex} +\section*{References} +\begin{enumerate} +\renewcommand\labelenumi{[\theenumi]} +\item[{[GMS93]}] Michel Goossens, Franck Mittelbach, and Alexander +Samarin, \emph{The \LaTeX Companion}, Addison Wesley, 1993. +\item[{[Lam97]}] Leslie Lamport, \emph{\LaTeX: A Document Preparation +System}, Addison Wesley, 1997. +\end{enumerate} +\end{myex} + +In order to avoid this problem, \env{thebibliography} has a mandatory +argument, which should be the largest label occurring in the list. This will +allow to set up margins properly. + +\medskip +Let's now have a look at the precise definition of the +\env{thebibliography} environment (as defined in the \cls{article} +class, for instance): +\begin{listing}{1} +\newenvironment{thebibliography}[1] + {\section*{\refname + \@mkboth{\MakeUppercase\refname}{\MakeUppercase\refname}}% +\end{listing} +As mentioned earlier, \env{thebibliography} starts a new +section\footnote{It is in fact a \cmd{section*}, so that it won't + appear in the table of contents. In order to cleanly insert the + bibliography in your table of contents, use the \sty{tocbibind} + package. Other methods you can think of will probably lead to wrong + page numbers.}. The environment also sets the page headers\footnote{The + standard + \sty{apalike} package hard-codes the headers to ``REFERENCES'' or + ``BIBLIOGRAPHY'', depending on the class file. + But another package (with the same name, unfortunately) correctly sets + the headers to \cmd{refname} or \cmd{bibname}. Simply check in the sources if you have + problems for redefining the headers with that package.}. + +\begin{listingcont} + \list{\@biblabel{\@arabic\c@enumiv}}% + {\settowidth\labelwidth{\@biblabel{#1}}% +\end{listingcont} +This is not surprising either: We start a new \env{list} +environment\footnote{The \cmd{list} command is equivalent to a + \texttt{\bs begin\{list\}}, and has to be followed with a + \cmd{endlist}.}. It takes two mandatory arguments: +\begin{itemize} +\item the first one (\texttt{\bs\at biblabel\{...\}}) defines the format of +the default command for + generating labels. Here it is defined with the \verb+enumiv+ + counter, using \cmdat{biblabel}{}\footnote{\cmdat{biblabel} is + defined in \LaTeX. It outputs its argument surrounded with + brackets. The precise definition is: +\texttt{\bs def\bs\at biblabel\#1\{[\#1]\}}.}. + Thus we have [1], [2], ... Since \cmd{bibitem} is a sort of + \cmd{item}, it may have an optional argument for modifying this + default label. +\item The second argument(lines~5 above to~11 below) is a set of commands that + are run at the + beginning of the environment. They set the values + of different lengths and parameters of the \env{list} environment. + This is where we need the longest label (which the mandatory + argument of the \env{thebibliography} environment should be set to), + in order to correctly indent the whole list. + People often write \verb+\begin{thebibliography}{99}+, but this is + correct only if there are between $10$ and $99$ cited references + (assuming all digits have the same length, which is the case with + the \textsf{cmr} fonts). +\end{itemize} + + +The rest of the definition of \env{thebibliography} contains some +borderline definitions for the list environment and the use of the +\verb+enumiv+ counter: +\begin{listingcont} + \leftmargin\labelwidth + \advance\leftmargin\labelsep + \@openbib@code + \usecounter{enumiv}% + \let\p@enumiv\@empty + \renewcommand\theenumiv{\@arabic\c@enumiv}}% +\end{listingcont} +\cmdat{openbib\at code}, which is empty by default, allows +to modify some parameters if necessary. Option \texttt{openbib} of +classical style files uses this command for resetting some parameters. +Line~9 to~11 set the list counter. + +Last, within the reference list, spacing rules as well as some special +penalties are used: +\begin{listingcont} + \sloppy + \clubpenalty4000 + \@clubpenalty \clubpenalty + \widowpenalty4000% + \sfcode`\.\@m} +\end{listingcont} + + +That's it for the initialization of this environment. Ending the +\env{thebibliography} is much easier: +we just echo a warning if no reference has been included, and we close +the \env{list} environment: +\begin{listingcont} + {\def\@noitemerr + {\@latex@warning{Empty `thebibliography' environment}}% + \endlist} +\end{listingcont} + + + +\mysection{The \protect\nicmd{bibitem} command}\label{bibitem} + +Inside the \env{list} environment described above, we have to insert +\cmd{item}{}s, as is usual. It will be a special \cmd{item}, though, in +order to have a correct rendering of each bibliographical item. The +adequate command is named \cmd{bibitem}, and has two roles: Writing +the new entry in the list, and defining the cross-reference to be used +when citing this entry, which defaults to +\verb+\@biblabel{\@arabic\c@enumiv}+. The result is [1] for instance, +but of course can be modified into [GMS94], say, +with an optional argument, +exactly in the same way as for an \cmd{item}. +Here is the precise definition of \cmd{bibitem}: +\begin{listing}{1} +\def\bibitem{\@ifnextchar[\@lbibitem\@bibitem} +\end{listing} +\cmd{bibitem} calls \cmdat{lbibitem} if +there is an optional argument, and \cmdat{bibitem} otherwise. +Those auxiliary commands are defined as follows: +% +\begin{listing}{1} +\def\@lbibitem[#1]#2{\item[\@biblabel{#1}\hfill]\if@filesw + {\let\protect\noexpand + \immediate + \write\@auxout{\string\bibcite{#2}{#1}}}\fi\ignorespaces} +\end{listing} +% +Let's take an example in order to see how it works: Assume we wrote +\verb+\bibitem[GMS94]{companion}+. +The command first creates an item having the same optional argument, +which will be surrounded with brackets by \cmdat{biblabel} and flushed +to the left by \cmd{hfill}.\label{biblabel} +It then write a \cmd{bibcite} command, with two arguments, into the +\ext{aux} file\footnote{More precisely, the file pointed to by +the \cmdat{auxout} command, but this generally is the \ext{aux} +file.}. +\cmd{bibcite} is simply defined as follows: +\label{bibcite} +\begin{listing}{1} +\def\bibcite{\@newl@bel b} +\end{listing} + +The \cmdat{newl\at bel} command requires three arguments, \texttt{\#1}, + \texttt{\#2} and \texttt{\#3}, and defines a command named + \texttt{\#1\at\#2} (with of course \texttt{\#1} and \texttt{\#2} being + replaced by their values) whose value is the third argument \texttt{\#3}. + +This behavior is the same as when defining a cross reference (with +\cmd{label}) in the document: when the \ext{aux} file is read by +\LaTeX (namely at the \verb+\begin{document}+ and +\verb+\end{document}+), those \cmdat{newl\at bel} commands are +executed, and a \verb+\b@companion+ command is defined, containing, +in our case, \texttt{GMS93}. + +When there is no optional argument, it is quite similar: +% +\begin{listing}{1} +\def\@bibitem#1{\item\if@filesw \immediate\write\@auxout + {\string\bibcite{#1}{\the\value{\@listctr}}}\fi\ignorespaces} +\end{listing} +% +The new \cmd{item} is created, and the \cmd{bibcite} command is +output in the \ext{aux} file. The only new thing to know here is that +\cmdat{listctr} is the list counter, and points to \verb+enumiv+ as requested +by the \cmd{usecounter} command in the definition of \env{thebibliography}. +Everything after the \cmd{bibitem} (and its argument(s)) is +output in the document, within the recently created item of the +list, until the next \cmd{bibitem} or the end of the +\env{thebibliography} environment\footnote{Some packages redefine + \cmd{bibitem} and could not meet this last rule. See + section~\ref{redefbibitem} on this topic.}. + +\medskip +To conclude, here is a small example of a bibliography, having two +entries, as it could be defined in a document: + +\begin{verbatim} +\begin{thebibliography}{GMS93} %% GMS93 is the longest label. +\bibitem[GMS93]{companion} Michel Goossens, Franck Mittelbach and Alexander + Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993. +\bibitem[Lam97]{lamport} Leslie Lamport, \emph{\LaTeX: A Document Preparation + System}, Addison Wesley, 1997. +\end{thebibliography} +\end{verbatim} +And here is the result: + +\begin{myex} +\begin{thebibliography}{GMS93} +\bibitem[GMS93]{companion1} Michel Goossens, Franck Mittelbach and Alexander + Samarin, \emph{The \LaTeX Companion}, Addison Wesley, 1993. +\bibitem[Lam97]{lamport1} Leslie Lamport, \emph{\LaTeX: A Document Preparation + System}, Addison Wesley, 1997. +\end{thebibliography} +\end{myex} + + +\mysection{The \protect\nicmd{cite} command}\label{cite} + +When considering a bibliography as a list of cross-references, +\cmd{cite} is the equivalent for \cmd{ref}. It has one mandatory +argument, which is the internal label to be cited. It also has an +optional argument, that can be used to add some comments to the +reference. For instance, a good reference concerning \bt is +\cite[Chap.~13]{latex:lc}, which is obtained by entering +\verb+\cite[Chap.~13]{companion}+.\label{citeopt} + + +Here is how it is defined\footnote{Details about + \cmd{DeclareRobustCommand} are given at page~\pageref{DRC}. If you + don't know what it is, you can see it as a simple + \cmd{newcommand}.}: +% +\begin{listing}{1} +\DeclareRobustCommand\cite{% + \@ifnextchar [{\@tempswatrue\@citex}{\@tempswafalse\@citex[]}} +\end{listing} +% +If there is an optional argument, the boolean variable \cmdat{tempswa} +is set to true (we need to remember that an optional argument was provided), +and \cmdat{citex} is called. Otherwise, \cmdat{tempswa} is false, and +\cmdat{citex} is called with an empty optional argument. + + +Before explaining \cmdat{citex}, we first have a quick look at +\cmdat{cite}, which will be used by \cmdat{citex}. This will help +understand how \cmdat{tempswa} is used: +% +\begin{listing}{1} +\def\@cite#1#2{[{#1\if@tempswa , #2\fi}]} +\end{listing} +This is the command used for outputting the reference in the +document. The second argument is used only if \cmdat{tempswa} has been +set to true. Together with the first argument, they are put into +brackets, and output in the document. + +Now \cmdat{citex}~will be the ``bridge'' between \cmd{cite} and \cmdat{cite}: +\label{citex} +% +\begin{listing}{1} +\def\@citex[#1]#2{% + \let\@citea\@empty + \@cite{\@for\@citeb:=#2\do +\end{listing} + +This calls \cmdat{cite}. Its first argument will be computed by the +\cmdat{for} command, in case several references are cited at one +time.\index{latex}{citea@\texttt{\protect\bs\protect\at citea}} +% +\begin{listingcont} + {\@citea\def\@citea{,\penalty\@m\ }% +\end{listingcont} +% +Starting from the second run through the \cmdat{for}-loop, we add a +comma, and a penalty for a line break not to occur between references. +The default is to never have a line break inside a set of references. +% +\begin{listingcont} + \edef\@citeb{\expandafter\@firstofone\@citeb\@empty}% +\end{listingcont} +% +This redefines \cmdat{citeb}, the variable used in the loop. The +\cmdat{for} command successively sets \cmdat{citeb} to all the values +that have been cited, and \cmdat{citeb} is redefined here in order to +remove extra spaces. This is somewhat tricky, but it works. +\label{citation} + +\begin{listingcont} + \if@filesw\immediate\write\@auxout{\string\citation{\@citeb}}\fi +\end{listingcont} +% +This writes a \cmd{citation} command in the \ext{aux} file, indicating +that \cmdat{citeb} has been cited in the document. This is not useful +here, but will be crucial for \bt to generate the bibliography (see +section~\ref{bibtex}). + +\begin{listingcont} + \@ifundefined{b@\@citeb}{\mbox{\reset@font\bfseries ?}% + \G@refundefinedtrue + \@latex@warning + {Citation `\@citeb' on page \thepage \space undefined}}% +\end{listingcont} +% +This handles cases where the requested reference does not exist yet. In +that case, the reference is replaced by a boldface question mark. A +warning is also echoed in the \ext{log} file. + +\begin{listingcont} + {\@cite@ofmt{\csname b@\@citeb\endcsname}}}}{#1}} +\end{listingcont} +If the reference exists, it is written here, using the +\nicmd{b\at...} command created when reading the \ext{aux} file (\cf +page~\pageref{bibcite}). +\cmdat{cite\protect\at ofmt} is equivalent to~\cmd{hbox}\footnote{The +command~\cmdat{citex} is defined with \cmd{hbox} in old (before 2003) versions +of \LaTeX.}. +The loop is executed for all the requested +references, and the whole result is then passed to \cmdat{cite}, +together with the optional second argument, which is \verb+#1+ here. + +\medskip +This may look intricate, but it is really easy to use: You simply +enter \verb+\cite{companion, lamport}+ in order to get \cite{latex:lc, + latex:dps}, with the bibliographic items shown at the end of the previous + section. + + + +\mysection{Some more little tricks}\label{truc1} + +\mysubsection{What is \protect\nicmd{DeclareRobustCommand}?} +\label{DRC} + +A command having an optional argument, such as \cmd{cite}, is said to +be \emph{fragile}: Generally speaking, they cannot be directly used +in the argument of other commands (for instance, \cmd{cite} in the +argument of a \cmd{section}). These problems can be overcome by preceding +the fragile command by a \cmd{protect}, but this is annoying. The +other solution is to declare the command as robust, by defining it +with \cmd{DeclareRobustCommand} instead of \cmd{newcommand}. + + +\mysubsection{Changing the name of the bibliography} + +This is obvious from the definition of the \env{thebibliography} +environment: We simply have to redefine \cmd{refname}, which defaults +to \emph{\refname}. However, this +only works with the \cls{report} class. The \cls{book} and +\cls{article} classes use \cmd{bibname} instead, which defaults to +\emph{\bibname}. + +For instance, when using \cls{report}, you'll write: +\begin{verbatim} + \renewcommand{\refname}{Some references} +\end{verbatim} +while with \cls{book} or \cls{article}, it should be: +\begin{verbatim} + \renewcommand{\bibname}{Some references} +\end{verbatim} +As mentioned earlier, \sty{apalike} does not use \cmd{refname} and hard-codes +the reference name in the page headers. + +\mysubsection{Adding text before the first reference} + +Putting text just after the beginning of the \env{thebibliography} +environment raises an error, since the \env{list} environment demands +an \cmd{item} command. Thus we will put a real \cmd{item}, then add +some negative horizontal space back to the left margin, and write our +text within a \env{minipage} environment (in order to avoid +indentation due to the list): + +\begin{verbatim} +\begin{thebibliography}{GMS93} +\item[] +\hskip-\leftmargin +\begin{minipage}{\textwidth} +Here are some useful references about \LaTeX. They are +available in every worthy bookshop. Many other good documentations +might be found on the web (the FAQ of \textsf{comp.text.tex} for +instance). +\end{minipage} +\bigskip +\bibitem[GMS93]{companion} Michel Goossens, Franck Mittelbach and + Alexander + Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993. +\bibitem[Lam97]{lamport} Leslie Lamport, \emph{\LaTeX: A Document Preparation + System}, Addison Wesley, 1997. +\end{thebibliography} +\end{verbatim} +This code gives: + +\begin{myex} +\begin{thebibliography}{AAA00} +\item[] +\hskip-\leftmargin +\begin{minipage}{\textwidth} +Here are some useful references about \LaTeX. They are +available in every worthy bookshop. Many other good documentations +might be found on the web (the FAQ of \textsf{comp.text.tex} for +instance). +\end{minipage} + +\bigskip +\bibitem[GMS93]{companion2} Michel Goossens, Franck Mittelbach and + Alexander + Samarin, \emph{The \LaTeX{} Companion}, Addison Wesley, 1993. +\bibitem[Lam97]{lamport2} Leslie Lamport, \emph{\LaTeX: A Document Preparation + System}, Addison Wesley, 1997. +\end{thebibliography} +\end{myex} + + +\mysubsection{Redefining \protect\nicmd{bibitem}}\label{redefbibitem} + + +Some style files need redefining the \cmd{bibitem} command, or in +fact \cmdat{bibitem} and \cmdat{lbibitem}, so that an entry has to +end with a \cmd{par} command (or an empty line). \sty{backref} is an +example of such a style file. Some other will turn the optional +argument of \cmd{bibitem} into a mandatory one. \sty{apalike} does +so. + +I've nothing to add about that, but it is useful to know this to +avoid spending too much time on debugging... + + + +\mysubsection{Turning brackets into parentheses} + + +As we saw earlier, \cmd{biblabel} is in charge of adding brackets +around reference labels, in the reference list. It is easy +to redefine it in order to get parentheses: + +\begin{verbatim} +\makeatletter % @ is now a letter +\def\bibleftdelim{(} +\def\bibrightdelim{)} +\def\@biblabel#1{\bibleftdelim #1\bibrightdelim} +\makeatother % @ is a symbol +\end{verbatim} + +This does the trick, and it is now easy to change parentheses into +anything else, by redefining \nicmd{bibleftdelim} and +\nicmd{bibrightdelim}. + +However, this won't change the behavior of \cmdat{cite}, which will +still write brackets around cited reference labels. Thus we also have +to redefine \cmdat{cite}: +\begin{verbatim} +\makeatletter +\def\@cite#1#2{\bibleftdelim{#1\if@tempswatrue , #2\fi}\bibrightdelim} +\makeatother +\end{verbatim} + +\mysubsection{... and more} + +Several packages have been written for modifying the look +of bibliographies and citations. For instance, +the package \sty{cite} allows to modify the result of the +\cmd{cite} command: turning brackets into parentheses, but also +sorting and compressing a set of numeric references. +The package \sty{overcite} allows, moreover, to get references +displayed as superscript. + +The package \sty{splitbib} changes the output of the list of +references: it allows to split the bibliography into several +categories, and\slash or reordering that list. See the +documentation~\cite{splitbib} for more details. + +\mysubsection{Can the symbol \$ be used in an internal key?} + +Probably not, but I don't know exactly which character may or may not +be used. Obviously, any letter and digit can be used, and my opinion +is that it is quite enough. On the other hand, commas, curly brackets +and backslashes are clearly forbidden. For the other ones, I don't +know, just give it a try and you'll know. + + +\mysection*{Conclusion} + +Well... It could be over right now, since we know how to write a +bibliography. However, typesetting all references by hand is long and +annoying. Moreover, when writing several articles on related areas, +we often cite the same sets of references, but possibly with different styles. +It would be interesting to have a \emph{database} containing a large +set of references, some of which would be picked up, formatted and typeset by +\LaTeX. This does exist, and is described in the sequel. diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec2.tex b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec2.tex new file mode 100644 index 00000000000..ac324feb8ff --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec2.tex @@ -0,0 +1,672 @@ +%% ttb_en.sec2.tex +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + + +\mypart{How to use \bt?} +\parttoc +\mtcskip + +\mysection{How does it work?} \label{bibtex} + +As mentioned earlier, \bt can be seen as a general database manager: +It extracts items from a database, sorts them, and exports the +result, generally as a \LaTeX{}able \env{thebibliography} +environment. + +This description is a somewhat optimistic view, however, and reality +is a little more complex: In order to tell \bt which entries have to +be extracted, you have to first run \LaTeX on your document. And once +\bt has finished its job, you have to run \LaTeX anew in order to take +the resulting bibliography into account. Here are some more precisions: + +\begin{itemize} +\item At the very first stage, you run \LaTeX on your document. Since this is + the first time you compile it, no bibliographic + information is included, and references are left + empty. Nevertheless, each time \LaTeX encounters a bibliographic reference + in the document, it writes the key of the reference in the \ext{aux} + file\footnote{This is the role of the \cmd{citation} command issued + by the \cmd{cite} command (\cf page~\pageref{citation}).}. During + the compilation, \LaTeX also indicates in the \ext{aux} file which + databases have to be used, and which bibliography style has + to be applied for typesetting the bibliography; + +\item \bt can now be executed: It takes the \ext{aux} file as + argument, which contains all the relevant informations + for extracting the bibliography: The style (\ext{bst} file) to be + applied to the + bibliography, the database (\ext{bib} file) to be used, and the + entries to be extracted from the database. With this stuff, \bt + will then extract the \cmd{cite}{}d references + and write the bibliography in a \ext{bbl} + file. Logs of this operation are written in a \ext{blg} file; + +\item The next step is to rerun \LaTeX. The \ext{bbl} file will then + be included, and its \cmd{bibitem} commands executed. This writes + the necessary bibliographic cross references in the \ext{aux} + file. However, this does not define the cross references for the + current compilation, and bibliographic references still won't be + defined; + +\item We then run \LaTeX a third time: When reading the \ext{aux} file + at the beginning of the compilation, \LaTeX will store the + references of the bibliographic citations, and those references + will be correct in the document. +\end{itemize} + + +It follows that, in the best case, we need to compile the file three +times, and to run \bt once. There are some cases where this is still +not sufficient: If, for instance, a bibliographic entry cites another +one, another run of both \bt and \LaTeX is needed. And so on. +Finally, here is the global pattern to be applied: +\begin{center} +\LaTeX (\bt {} \LaTeX )$^+$ \LaTeX. +\end{center} + + +Everything else works as in part~\ref{part1}, since \bt generally creates the +complete \env{thebibliography} environments with all the \cmd{bibitem}{}s of +the references that are cited in your document. +There are two new \LaTeX commands, however: Those +defining the style file to consider and bibliographic database(s): +\begin{itemize} +\item \cmd{bibliographystyle} is the command to be used to declare the + bibliography style to be used by \bt. Here is how it is defined: +\begin{listing}{1} +\def\bibliographystyle#1{% + \ifx\@begindocumenthook\@undefined\else + \expandafter\AtBeginDocument + \fi + {\if@filesw + \immediate\write\@auxout{\string\bibstyle{#1}}% + \fi}} +\end{listing} + + +This simply writes a \cmd{bibstyle} command in the \ext{aux} file, +whose argument is the name of the style. \cmd{bibstyle} itself is a +command that has one argument, but does nothing. Indeed, the +name of the bibliography style is only needed by \bt, and \LaTeX doesn't +care about it. + +\item \cmd{bibliography} is the command for defining the bibliographic + database to be used. Contrary to the previous command, the argument + of \cmd{bibliography} might be a comma-separated list of + bibliographic databases. Note that ``comma-separated'' is strict + here: No space and no line break are allowed. Apart from this, the + behavior of this command is similar to the behavior of the previous + one: It writes its argument in the \ext{aux} file, as the + argument of + a command named \cmd{bibdata} (which is then read by \bt, + but does nothing in \LaTeX). Last, this + \cmd{bibliography} command includes the \ext{bbl} file, + which writes + the bibliography. Here is the precise definition: +\begin{listing}{1} +\def\bibliography#1{% + \if@filesw + \immediate\write\@auxout{\string\bibdata{#1}}% + \fi + \@input@{\jobname.bbl}} +\end{listing} + +You've probably already understood that \cmd{jobname} returns the name +of the file being compiled. +\end{itemize} + + +Last precision: The \ext{aux} file also contains the list of keys of +the entries to be extracted. This is achieved by the \cmd{citation} +commands echoed by \cmd{cite} in the \ext{aux} file. \cmd{citation} +does the same thing as \cmd{bibstyle} and \cmd{bibdata}: Nothing. + + +\mysection{Some bibliography styles...} + +There exist quite a bunch +of bibliography styles, since each publisher has his own +needs +and preferences. I'll present some generic styles here, together with their +specificities. + +\mysubsection{Classical bibliography styles} + +The following four styles were originally written by Oren +\textsc{Patashnik}, whom I forgot to introduce but is in fact the +author of \bt. The styles are named \bst{plain}, \bst{alpha}, +\bst{unsrt} and \bst{abbrv}. If you want to use the +\bst{plain}~style, you'll write \verb+\bibliographystyle{plain}+ +(anywhere) in your document. + + +Globally speaking, the bibliography style has to manage +everything. ``Everything'' here can be decomposed into three points: +Defining the available entry types, with their relevant +fields\footnote{I insist that entry types and field names depend +on the bibliography style, and are not fixed by \bt.}; +Extracting and sorting +bibliographic items; And typesetting the bibliography. + + +So the first role of the style file is to define entry types, such as +\ent{book}, \ent{article} or \ent{inproceedings} in classical styles, +and for each of them, the relevant fields that will be +either mandatory or optional or just ignored\footnote{The following + rule applies: A field that is neither mandatory nor optional, is + ignored. Thus you can add any comment or personal field in your + bibliography, even if they're not in the list below. Some other + fields might of course be used by other, non classical styles.}. +The table below describes the role of the fields that are used in +classical style files. Descriptions are short, but more details can be +easily found in any \LaTeX book.\label{champ} + +\begin{center} +%\centerline{% +\begin{longtable}{|>{\vrule height8pt depth0pt width 0pt\noindent\bgroup\bfseries}p{.17\textwidth}<{\egroup}>{\noindent}p{.77\textwidth}<{\vrule height0pt depth7pt width 0pt}|} +\hline\endfirsthead +\hline\endhead +\hline\endfoot +\hline\endlastfoot +address & Generally the city or complete address of the publisher. +\\ +author & For author names. The input format is quite special, since +\bt +has to be able to distinguish between the first and last +names. Section~\ref{author} and~\ref{noms-start} are completely +dedicated to this topic. +\\ +booktitle & For the title of a book one part of which is cited. +\\ +chapter & The number of the chapter (or any part) of a book being +cited. If not a chapter, the \texttt{type} field might be used for +precising the type of sectioning. +\\ +crossref & This one is quite peculiar. It's used to cross-reference +within the bibliography. For instance, you might cite a +document, and a part of it. In that case, the second one +can reference +the first one, or at least inherit some of its fields from the first +one. This deserves some more comments, see section~\ref{crossref}. +\label{cetaitla} \\ +edition & The edition number. Or in fact its ordinal, for instance +\texttt{edition = "First"}. This might raise +problems when trying to export a bibliography into another language. +\\ +editor & The name of the editor(s) of the entry. The format is the +same as for authors. +\\ +howpublished & Only used in rare cases where the document being cited +is not a classical type such as a \ent{book}, an \ent{article} or an +\ent{inproceedings} publication. +\\ +institution & For a technical report, the name of the institution that +published it. +\\ +journal & The name of the journal in which the cited article has +been published. +\\ +key & Used for defining the label, in case it cannot be computed by +\bt. It does not force the label, but defines the label when +\bt needs one but can't compute it. +\\ +month & Well... The month during which the document has been +published. This also raises the problem of the translation of the +bibliography: It's better having a numerical value, or an abbreviation, +instead of the +complete name of the month. Having the number would also allow \bt +to sort the entries more precisely (even though, as far as I know, no +bibliography style does this at the present time). +\\ +note & For any additional data you would want to add. Since classical +styles were written in 1985, they don't have a \texttt{url} field, and +\texttt{note} is often used for this purpose, together with the +\sty{url} package. +\\ +number & A number... Not whichever, but the number of a report. For +volume numbers, a special +\texttt{volume} field exists. +\\ +organization & The organizing institution of a conference. +\\ +pages & The relevant pages of the document. Useful for the reader when +you cite a huge book; Note that such a precision could be added +through the optional argument of \cmd{cite} (see +page~\pageref{citeopt}), in which case it would appear in the document +but not in the bibliography. +\\ +publisher & The institution that published the document. +\\ +school & For theses, the name of the school the thesis has been +prepared in. +\\ +series & The name of a collection of series or books. +\\ +title & The title of the document being cited. There are some rules to +be observed when entering this field, see section~\ref{title}. +\\ +type & The type. Which type? It depends... The type of publication, if +needed. For thesis, for instance, in order to distinguish between +a masters thesis and a PhD. Or the type of section being cited (see +\texttt{chapter} above). +\\ +volume & The volume number in a series or collection of books. +\\ +year & The publication year. +\\ +%\hline +%\caption{ }\label{chp} +\end{longtable} +\end{center} +\label{fin-champ} + + +The table below describes the different entry types. Once again, you +can find more details in any \LaTeX documentation, so I won't go deep +into the details. \label{type} +{% +\hfuzz=50pt% +\begin{longtable}{|>{\vrule height11pt depth0pt width 0pt}p{.45\textwidth} +%>{\noindent}p{.27\textwidth} +>{\noindent\raggedright\relax}p{.22\textwidth} +>{\noindent\raggedright\relax}p{.25\textwidth}<{\vrule height0pt depth9pt width 0pt}|} +\hline\endfoot +\hline\endlastfoot +\hline +\vrule depth7pt height 10pt width 0pt\normalfont Entry type & +Mandatory fields & Optional fields \tabularnewline\hline\endhead +\hline\vrule depth7pt height 10pt width 0pt\normalfont Entry type & +Mandatory fields & Optional fields \tabularnewline\hline\endfirsthead + +\ent{article} : An article published in a journal. & +\chp{author}, \chp{title}, \chp{year}, \chp{journal}. & +\chp{volume}, \chp{number}, \chp{pages}, \chp{month}, \chp{note}.\tabularnewline + +\ent{book} : Well... A book. & +\chp{author} or \chp{editor}, \chp{title}, \chp{publisher}, \chp{year}.& +\chp{volume} or \chp{number}, \chp{series}, \chp{address}, \chp{edition}, \chp{month}, \chp{note}.\tabularnewline + +\ent{booklet} : A \emph{small} book, that has no \chp{publisher} field.& +\chp{title}.& +\chp{author}, \chp{howpublished}, \chp{address}, \chp{address}, \chp{month}, \chp{year}, \chp{note}. \tabularnewline + +\ent{conference} : Article that appeared in the proceedings of a +conference, a meeting... & +\chp{author}, \chp{title}, \chp{booktitle}, \chp{year}.& +\chp{editor}, \chp{volume} or \chp{number}, \chp{series}, \chp{pages}, +\chp{address}, \chp{month}, \chp{organization}, \chp{publisher}, \chp{note}.\tabularnewline + +\ent{inbook} : Part (generally a chapter) of a book.& +\chp{author} or \chp{editor}, \chp{title}, \chp{chapter} or \chp{pages}.& +\chp{volume}, \chp{number}, \chp{series}, \chp{type}, \chp{address}, +\chp{edition}, \chp{month}, \chp{note}.\tabularnewline + +\ent{incollection} : Part of a book having its own title. & +\chp{author}, \chp{title}, \chp{booktitle}, \chp{publisher}, \chp{year}.& +\chp{editor}, \chp{volume} or \chp{number}, \chp{series}, \chp{type}, +\chp{chapter}, \chp{pages}, \chp{address}, +\chp{edition}, \chp{month}, \chp{note}. \tabularnewline + +\ent{inproceedings} & \multicolumn{2}{c|}{Same as \ent{conference}.} +\tabularnewline + +\ent{manual} : A little manual, such as this one for instance. & +\chp{title}.& +\chp{author}, \chp{organization}, \chp{year}, \chp{address}, +\chp{edition}, \chp{month}, \chp{note}.\tabularnewline + +\ent{mastersthesis} : Masters thesis, or something equivalent. & +\chp{author}, \chp{title}, \chp{school}, \chp{year}.& +\chp{type}, \chp{address}, \chp{month}, \chp{note}.\tabularnewline + +\ent{misc} : When nothing else fits...& +at least one of the optional fields. & +\chp{author}, \chp{title}, \chp{howpublished}, \chp{year}, \chp{month}, \chp{note}. +\tabularnewline + +\ent{phdthesis} : PhD dissertation, or similar. & +\chp{author}, \chp{title}, \chp{school}, \chp{year}.& +\chp{type}, \chp{address}, \chp{month}, \chp{note}.\tabularnewline + +\ent{proceedings} : Conference proceedings. & +\chp{title}, \chp{year}.& +\chp{editor}, \chp{volume} or \chp{number}, \chp{series}, +\chp{address}, \chp{month}, \chp{organization}, \chp{publisher}, \chp{note}. +\tabularnewline + +\ent{techreport} : Technical report, published by a laboratory, a +research center, ... & +\chp{author}, \chp{title}, \chp{institution}, \chp{year}.& +\chp{type}, \chp{address}, \chp{number}, \chp{month}, \chp{note}. +\tabularnewline + +\ent{unpublished} : A document that has not been published. Very +close to \ent{misc}, but \texttt{author} and \texttt{title} are needed +here. & +\chp{author}, \chp{title}, \chp{note}.& +\chp{month}, \chp{year}.\tabularnewline +%\hline +\end{longtable} +%\end{center} +} + + +Concerning the order and typesetting of all this stuff, it's similar +in all the classical style files. Of course it depends on the entry +type, but it generally begins with the author names and the +title. Then the references of the journal or of the proceedings... +The best thing to do if you need more details is to give it a try, or +have a look directly in the style files (but read Part~\ref{bst} before if +you don't know how \bt style files are built). +\medskip + + +Up to now, there are no differences between the four standard +style files. +The only possible difference now can only be related to labelling and +typesetting method to be used. + + +\begin{itemize} +\item the \bst{plain} style sorts the entries according to the name of + their authors (using the alphabetical order\footnote{The standard +alphabetical order with $26$~letters. Unfortunately, some language +have a different alphabet, for instance Swedish, in which +``\texttt{\aa}'' and~``\texttt{\"o}'' are considered as letters and placed +after~``\texttt{z}''.}, of course), and, for + papers by the same author(s), the year they have been published +(the + older first). The last criterion in case of equality is the title, + being a little bit modified. If two references can't be + distinguished with the above, the first one being cited in the + document appears first. Labels are numbers, + starting with $1$. + +\item the \bst{alpha} style file is named \emph{alpha} because it uses + alphanumerical labels: Those labels are computed by \bt using the + first three letters of the author name + (or initials of the author names + if multiple authors), followed by the last two digits of the + publication year. Sorting the entries is done according to the label + first, and then to the same criteria as for \bst{plain}, + in case several + publication have the same label\footnote{You certainly don't want + that several publications have the same labels. Thus computing the + labels is done in two phases: First computing the label with the + standard method, and then adding a supplementary letter (``a'', + ``b'',~...) for multiple labels. And sorting is done just between + those two phases...}; +\item you probably understood what \bst{unsrt} does: +It does not sort + its references, which appears in the order they are cited in the + document. Everything else is done as in \bst{plain}; +\item \bst{abbrv} abbreviates first names + of the authors and the names of predefined journal and month names. +I forgot to mention that bibliography styles historically + predefine some shorthands for computer science journal names (Oren + \textsc{Patashnik} is a computer scientist...). Those shorthands are + abbreviated journal names in this style file. These are the only + difference between \bst{abbrv} and \bst{plain}. +\end{itemize} + + +That's all for classical styles. Those styles suffer from several +problems, for instance not having a \texttt{url} field, or not being +multilingual, or sorting in a weird way... Moreover, publishers +often impose precise +typographic rules for bibliographies. This entails that many other +styles have been proposed. Let's have a look at some of them. + + + + +\mysubsection{Some other bibliography styles} + +%There are numerous other bibliography style files. I really can't +%describe all of them, just mentionning some of them together with +%their main characteristics. + +\mysubsubsection{The \protect\nibst{apalike} style} + +\bst{apalike} was (also) written by Oren \textsc{Patashnik}. It uses a +special construction for labels, generally called \emph{author-year}. +I think the best way to understand is with some examples: + +\begin{myex} +\makeatletter +\def\@cite#1#2{(#1\if@tempswa , #2\fi)} +\def\@biblabel#1{} +\makeatother + +On page~$384$ of \cite{latex:lcici}, you'll find a complete example of +what \bst{apalike} does. + +\begin{thebibliography}{} +\bibitem[Goossens et~al., 1993]{latex:lcici} +Goossens, M., Mittelbach, F., and Samarin, A. (1993). +\newblock {\em the \LaTeX{} Companion}. +\newblock Addison-Wesley. + +\bibitem[Lamport, 1997]{latex:dpsici} +Lamport, L. (1997). +\newblock {\em \LaTeX{}: A Document Preparation System}. +\newblock Addison-Wesley. +\end{thebibliography} +\end{myex} + +Don't forget to include the \sty{apalike} package when using +the \bst{apalike} style: Indeed, if you remember how \cmdat{biblabel} +and \cmd{cite} are defined, you should have seen why... +Moreover, labels created +by \bst{apalike} might be long, and you probably will accept that +\LaTeX hyphenates them if necessary, which the default +\cmd{cite} won't do (\cf section~\ref{cite}). + +%Last, I always like to quote the following comments +%written in the \bst{apalike} file: +%\begin{verbatim} +%% Many journals require a style like `apalike', but I recommend that you +%% not use it if you have a choice---use something like `plain' instead. +%\end{verbatim} + +Also: There are some other \emph{author-year} style files, named +\bst{authordate1}, \bst{authordate2}, \bst{authordate3}, +\bst{authordate4}, and that slightly differ from \bst{apalike}. +They must be used together with the +\sty{authordate1-4} package. + +Very last important thing: \sty{apalike} redefined \cmd{bibitem} +so that the optional argument becomes mandatory (but must still be +within square brackets). But you probably don't care since, of course, +the bibliography style file tells \bt to always output it. + + +\mysubsubsection{The \protect\nisty{natbib} package} + +The \sty{natbib} package, written by Patrick~W. \textsc{Daly}, +goes a bit further: It mainly redefines \cmd{cite} so that you can +get \emph{author-year} or numerical labels, in a very elegant way. + +Classical bibliography styles have been ported to \sty{natbib}, +except \bst{alpha} since it already was an \emph{author-year} +style. The names of the ports are +\bst{plainnat}, \bst{abbrvnat} et \bst{unsrtnat}. +Moreover, those styles have a \texttt{url} field for adding reference +to articles on the web. Also note that \sty{natbib} can be used with +\bst{apalike} or \bst{authordate1} to \bst{authordate4}. + +Last interesting remark: There is a very clean +documentation~\cite{natbib} for +\sty{natbib}, it's really worth reading. + +\mysubsubsection{The \protect\nisty{jurabib} package} + +The package \sty{jurabib}, by Jens Berger, is another +package for adapting +the output to the typographic rules used in legal studies. +It is associated to a bibliography style \bst{jurabib}, and +rests on a very special format for the optional argument +of~\cmd{bibitem}. It also redefines \cmd{cite}, and defines +many flavors of that command. +See~\cite{jurabib} for detailed comments on \sty{jurabib}. + +\mysubsubsection{\textsf{custom-bib}} + +Since there are many possible criteria for defining a bibliographic +style, +Patrick~W. \textsc{Daly} decided to write a little piece of software +for automatically generating customized bibliography styles. It asks +you about $20$~questions and produces a pretty ready-to-use +bibliography style file. + +As usual with Patrick~\textsc{Daly}, +the documentation~\cite{merlin} is excellent, and I +won't go any further in the details. I just mention how to create your +\ext{bst}-file: +Simply type +\verb+latex makebst.tex+, and answer the questions. All along the +execution, the style file is being created. It's really easy and +intuitive. + + + +\mysection{Questions and answers} + +This section ends the \LaTeX part of this manual with some +frequently asked questions. We'll then tackle the \bt part, which was +intended to be the central topic... + + + +\mysubsection{How to get several bibliographies?} + +I did not insist on that, but it is of course recommended that you +only have one occurrence of each +\cmd{bibliography} and \cmd{bibliographystyle} commands. +\LaTeX won't mind if it is not the case, but \bt won't appreciate, +since it can't choose which style or bibliographic file to use. + + +Thus the only possible thing is to write several \ext{aux} files, each +of them containing a complete set of data for one bibliography. +This is precisely what +\sty{multibib}, \sty{chapterbib} and \sty{bibunit} do. +\begin{itemize} +\item \sty{multibib}, written by +Thorsten \textsc{Hansen}, +allows for precising in which bibliography a document lies. +This is achieved by using different \cmd{cite} commands, one for each +bibliography. +For this manual, I could have used \sty{multibib} to define special +\nicmd{citelatex} and \nicmd{citebibtex} commands defining two +separate bibliographies\footnote{For those who know the \sty{multind} + package for getting multiple indexes, the idea is similar.}. +Of course, this requires that you run \bt against each of the +\ext{aux} files created. For more details, refer to the +documentation~\cite{multibib}, which (also) is really worth +reading. The doc also mentions the main issue with such a method: The +same label could be used in several bibliographies for different +references. And you can't easily avoid this problem... + +\item The \sty{chapterbib} package, mainly written by +Donald \textsc{Arseneau}, provides a way to get +one bibliography for each +chapter or part of a (long) document (short documents won't need +several bibliographies). Indeed, a long document will be +made of several files \cmd{include}{}d by a main file. +\sty{chapterbib} creates one \ext{aux} file for each of those included +files, each of which being intended to contain the +necessary \cmd{bibstyle}, \cmd{bibdata} and +\cmd{citation} commands. +Documentation for this package may be found at the end of the package +file itself. + +\item The \sty{bibunit} package, also written by +Thorsten \textsc{Hansen}, is pretty similar to \sty{chapterbib}: +it allows to create one bibliography for each ``unit'', a unit +being any part of the document beginning with +\verb+\begin{bibunit}+ and ending with +\verb+\end{bibunit}+. + + +Inside such a unit, all occurrences of \cmd{cite} refer to the +bibliography of the current unit. \cite{bibunit} gives many +details of how it works. +\end{itemize} + + +There are some other packages for creating several bibliographies: +\sty{camel}, \sty{bibtopic}... I can't detail everything since it is +not the aim of this manual. + + +\mysubsection{How to have references closer to where they are cited?} + +There are two solutions to this problem, depending on what you +precisely want: The first solution consists in putting references in +footnotes. This might be practical for the reader, since he has the +complete references without always going back and forth to the end of +the book. There is a package just designed to this purpose: +\sty{footbib}. It's quite well documented~\cite{footbib}. + + +The second solution is to write the complete references in the +text. Instead of citing~\cite{latex:lc}, you cite +Michel Goossens, Franck Mittelbach et Alexander + Samarin, \emph{The \LaTeX Companion}, Addison Wesley, 1993. +This may enhance your document, but can sometimes become +annoying for the reader. However, just have a look a the package \sty{bibentry}, and +its documentation~\cite{bibentry}, if you want some more details. + + +Note that both of these packages might conflict with some other ones, +such as \sty{hyperref}. This is due to the fact that each of them +wants to impose its own definition of the \env{thebibliography} +environment or of the \cmd{bibitem} command. The last one being included +will win, but the other ones will eventually complain. There is no +simple solution to avoid this, the only way, if any, is to merge all +the definitions by hand. + + +\mysubsection{How to add entries in the reference list without + citing them in the document?} + +This is achieved by the \cmd{nocite} command. It works exactly like +\cmd{cite}, but writes nothing in the document. It just includes the +\cmd{citation} command in the \ext{aux} file. + + +A variant of this command is \verb+\nocite{*}+: it +amounts to \cmd{nocite}-ing the whole bibliography at one time. +Those references are included in the same order as they appear in the +\ext{bib} file, except for those having been cited earlier. +Note that \verb+\cite{*}+ is also correct, but I'm not sure it has +any interest... + + +\bigskip + + +Well... That's all for this part. +We now forget \LaTeX, and go closer to the core of the problem. The +next section explains how to create a clean \ext{bib} file. + + diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec3.tex b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec3.tex new file mode 100644 index 00000000000..d1459a7616a --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec3.tex @@ -0,0 +1,749 @@ +%% ttb_en.sec3.tex +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + + +\mypart{The \protect\niext{bib} file}\label{part3} +\parttoc +\mtcskip + +The \ext{bib} file is the database. Its contents heavily +depends on the style being applied to it, even though +bibliography styles are generally ``compatible'' with each w.r.t.\ the +database. I will only describe here +the case of standard styles\footnote{Thus using entry types +and fields as described at pages~\pageref{champ} +to~\pageref{fin-champ}.}. +But remember that +\bt can do many other things, we'll see some examples in +section~\ref{autres}. + +\mysection{Structure of the \protect\niext{bib} file} + +We start with an example: + +\begin{verbatimtab} +@book{companion, + author = "Goossens, Michel and Mittelbach, Franck and Samarin, Alexander", + title = "The {{\LaTeX}} {C}ompanion", + publisher = "Addison-Wesley", + year = 1993, +} +\end{verbatimtab} +We just consider the structure of this entry for the moment, not its +contents. The general form is the following\footnote{The +outermost braces can be replaced by parentheses: + \texttt{\at{\itshape entry\_type}({\itshape internal\_key}, ...)}.}: +\bigskip + +\noindent\begin{minipage}{\textwidth} +\obeylines +\ttfamily \at{\itshape entry\_type}\{internal\_key, +\ \ {\bfseries field\_1}\ \ \ \ \ \ \ = "value\_1", +\ \ {\bfseries field\_2}\ \ \ \ \ \ \ = "value\_2", +\ \ ... +\ \ {\bfseries field\_n}\ \ \ \ \ \ \ = "value\_n" +\} +\end{minipage} + +\bigskip + +\noindent Some basic remarks: +\begin{itemize} +\item New entries always start with \texttt\at. Anything outside + the ``argument'' of a ``command'' starting with an \texttt\at{} is + considered as a comment. This gives an easy way to comment a given + entry: just remove the initial \texttt\at. + As usual when a language allows comments: Don't hesitate to use + them, so that you have a clean, ordered, and easy-to-maintain + database. Conversely, anything starting with an \texttt\at{} is + considered as being a new entry\footnote{There is a special entry + type named \ent{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~\texttt{\at}.}. + +\item \bt does not distinguish between normal and capital + letters in entry and field names. \bt will complain if two entries + have the same internal key, even if they aren't capitalized in the + same way. For instance, you cannot have two entries named + \texttt{Example} and \texttt{example}. + + In the same way, if you cite both \texttt{example} and + \texttt{Example}, \bt will complain. Indeed, it would have to + include the same entry twice, which probably is not what you want; + + +\item Spaces and line breaks are not important, except for + readability. On the contrary, commas are compulsory between any two + fields; + + +\item Values (\emph{i.e.} right hand sides of each assignment) can be either + between curly braces or between double quotes. The main difference + is that you can write double quotes in the first case, and not in + the second case. For citing + \emph{Comments on ``Filenames and Fonts''} by Franck +\textsc{Mittelbach}, you can use one of the following solutions: +\begin{verbatimtab} + title = "Comments on {"}Filenames and Fonts{"}", + title = {Comments on "Filenames and Fonts"}, +\end{verbatimtab} + +Curly braces have to match, since they will appear in the output to be +compiled by \LaTeX. +A problem occurs if you need to write a (left-, say) brace in an entry. You +could of course write \verb+\{+, but the entry will have to also include the +corresponding right brace. To include a left brace without its +corresponding right brace, you'll have use a \LaTeX~function having no +brace in its name. \cmd{leftbrace} is the right choice here. Another solution +is to add an extra \cmd{bgroup} in the entry, so that both \LaTeX and \bt will +find the correct number of ``braces''. + +\item For numerical values, curly braces and double quotes can be + omitted. +\end{itemize} + + +As I already mentioned, you can define fields even if they aren't +used by the style being applied. For instance, the following can be +used for the \LaTeX Companion: +\begin{verbatimtab} +@book{companion, + author = "Goossens, Michel and Mittelbach, Franck and Samarin, Alexander", + title = "The {{\LaTeX}} {C}ompanion", + booktitle = "The {{\LaTeX}} {C}ompanion", + publisher = "Addison-Wesley", + year = 1993, + month = "December", + ISBN = "0-201-54199-8", + library = "Yes", +} +\end{verbatimtab} +It gives complementary information about the book\footnote{Filling + both \nichp{title} and \nichp{booktitle} for a book may be of real + interest, as we will see in the section dedicated to cross + references (see section~\ref{crossref} for some more details).}, +for + instance the fact that it is available in your local library. +You really + should not hesitate to use auxiliary, personal fields, giving them + explicit names in order to be sure that no bibliography style +will + use them incidentally\footnote{You'll ask ``Is it really + useful?''. First of all, it is not that long to add those + informations each time you add a new entry, and it is much longer +to + add a field to several entries. Moreover, we'll see later how to + design bibliography styles, and you'll be able to write styles + that take those new fields into account.}. + + +\mysection{The \protect\nient{string} and \protect\nient{preamble} + entries}\label{strpre} + +These are not really entry types: \ent{string} +entries can be used in order to define abbreviations. For instance, +we've cited two books published by Addison-Wesley. It might be useful +to define a shortcut for this publisher. Thus we write: +\begin{verbatimtab} +@string{AW = "Addison-Wesley"} + +@book{companion, + author = "Goossens, Michel and Mittelbach, Franck and Samarin, Alexander", + title = "The {{\LaTeX}} {C}ompanion", + booktitle = "The {{\LaTeX}} {C}ompanion", + publisher = AW, + year = 1993, + month = "December", + ISBN = "0-201-54199-8", + library = "Yes", +} +\end{verbatimtab} + +This does not only spare some time, but most importantly, it ensures that +you won't misspell it, and helps you maintain an homogeneous database. +I find this really interesting for author names, so that you're sure +to always write them correctly (or always incorrectly, but it would +be easy to detect and correct a global mistake anyway). + + +As regards \ent{preamble}, it may be used for inserting commands or +text in the file created by \bt. Anything declared in a \ent{preamble} +command will be concatenated and put in a variable named +\fn{preamble}, for being used in the bibliography style and, +generally, inserted at the beginning of the \ext{bbl} file, just +before the \env{thebibliography} environment. This is useful for +defining new commands used in the bibliography. Here is a small +example: +\begin{verbatimtab} +@preamble{ "\makeatletter" } +@preamble{ "\@ifundefined{url}{\def\url#1{\texttt{#1}}}{}" } +@preamble{ "\makeatother" } +\end{verbatimtab} +This way, you may safely use the \nicmd{url} command in your +entries. If it is not defined at the beginning of the bibliography, the +default command defined in the \ent{preamble} will be used. + +Please note that you should never define style settings +in the \ent{preamble} of a bibliography database, +since it would be applied to +any bibliography built from this database. + + + + + + +\mysection{The \nichp{title} field}\label{title} + +Let's see how to fill the ``title'' field. We start by studying how I entered +the title field for the +\emph{\LaTeX Companion} : +\begin{verbatimtab} + title = "The {{\LaTeX}} {C}ompanion" +\end{verbatimtab} + +We'll need several definitions before going further. +The \emph{brace depth} of an item is the number of braces surrounding +it. This is not a very formal definition, but for instance, in +the title above, \verb+\LaTeX+ has brace depth $2$, the \verb+C+ has +brace depth $1$, and everything else has depth $0$\footnote{Of course, +surrounding the field with braces instead of quotes does not modify +the brace depth.}. +A~\emph{special character} is a part of a field starting with a left +brace +being at brace depth $0$ immediately +followed with a backslash, and ending +with the corresponding right brace. +For instance, in the above example, there is +no special character, since \verb+\LaTeX+ is at depth~$2$. It should +be noticed that anything in a special character is considered as being at +brace depth~$0$, even if it is placed between another pair of braces. + +That's it for the definitions. +Generally speaking, several modifications can be applied to the +title by the bibliography style: +\begin{itemize} +\item first of all, the title might be used for sorting. When sorting, + \bt computes a string, named \fn{sort.key}, for each + entry. The \fn{sort.key} string is an (often long) + string defining the order in which + entries will be sorted. To avoid any ambiguity, \fn{sort.key} should + only contain alphanumeric characters. Classical non-alphanumeric + characters\footnote{Except hyphens and tildes + that are replaced + by spaces. Spaces are preserved. The precise behavior of + \fn{purify} is explain on page~\pageref{purify}.}, + except special characters, will be removed by + a \bt function named \fn{purify}. For special characters, \fn{purify} + removes spaces and + \LaTeX commands (strings beginning with a backslash), even those + placed between brace pairs. Everything else is left unmodified. For + instance, + \verb+t\^ete+, \verb+t{\^e}te+ and \verb+t{\^{e}}te+ +are transformed into \verb+tete+, +while \texttt{t\^ete} gives \texttt{t\^ete}; +\verb+Bib{\TeX}+ gives \verb+Bib+ and +\verb+Bib\TeX+ becomes \verb+BibTeX+. +There are thirteen \LaTeX commands that won't follow the above rules: +\verb+\OE+, \verb+\ae+, \verb+\AE+, \verb+\aa+, \verb+\AA+, +\verb+\o+, \verb+\O+, \verb+\l+, \verb+\L+, \verb+\ss+. +Those commands correspond to \i, \j, \oe, +\OE, \ae, \AE, \aa, \AA, \o, \O, +\l, \L, \ss, and \fn{purify} transforms them (if they are in a special +character, +in \verb+i+, \verb+j+, + \verb+oe+, +\verb+OE+, \verb+ae+, \verb+AE+, \verb+aa+, \verb+AA+, \verb+o+, + \verb+O+, +\verb+l+, \verb+L+, \verb+ss+, respectively. + + +\item the second transformation applied to a title is to be turned to + lower case (except the first character). + The function named + \fn{change.case} does this job. But it only applies to letters that + are a brace depth~$0$, except within a special character. In a + special character, brace depth is always $0$, and letters are + switched to lower case, except \LaTeX commands, that + are left unmodified. +\end{itemize} +Both transformations might be applied to the \chp{title} field by +standard styles, and you must ensure that your title will be treated correctly +in all cases. + +Let's try to apply it now, +for instance to \emph{the \LaTeX Companion}. +Several solutions might be tried: +\begin{itemize} +\item \verb+ title = "The \LaTeX Companion"+: This won't work, since + turning it to lower case will produce \verb+The \latex companion+, + and + \LaTeX won't accept this... +\item \verb+ title = "The {\LaTeX} {C}ompanion"+ : This ensures that + switching to lower case will be correct. However, applying + \fn{purify} gives \verb+The Companion+. Thus sorting could be + wrong; +\item \verb+ title = "The {\csname LaTeX\endcsname} {C}ompanion"+: + This won't work since \texttt{LaTeX} will be turned to \texttt{latex}; +\item \verb+ title = "The { \LaTeX} {C}ompanion"+ : In this case, + \verb+{ \LaTeX}+ is \emph{not} a special character, but a set of + letters at depth~$1$. It won't be modified by + \fn{change.case}. However, \fn{purify} will leave both spaces, and + produce \verb+The LaTeX Companion+, which could result in wrong + sorting; +\item \verb+ title = "The{ \LaTeX} {C}ompanion"+: This solution also + works, but is not as elegant as the next one; +\item \verb+ title = "The {{\LaTeX}} {C}ompanion"+ : This is the + solution I used. It solves the problems mentioned above. +\end{itemize} + +For encoding an accent in a title, say \emph{\'E} (in upper case) as +in the French word \emph{\'Ecole}, we'll write +\verb+{\'{E}}cole+, \verb+{\'E}cole+ or \verb+{{\'E}}cole+, +depending on whether we want it to be turned to lower case (the first +two solutions) or not (the last one). \fn{purify} will give the same +result in the three cases. +However, it should be noticed that the third one is not a special +character. If you ask \bt to extract the first character of each +string using \fn{text.prefix}, you'll get \verb+{\'{E}}+ in the first case, +\verb+{\'E}+ in the second case and +\verb+{{\}}+ in the third case. + + +That's all for subtleties of titles. Let's have a look at author +names, which is even more tricky. + + +\mysection{The \nichp{author} field}\label{author} + + +We still begin with the entry for the \emph{\LaTeX Companion}: +\begin{verbatim} + author = "Goossens, Michel and Mittelbach, Franck and Samarin, Alexander" +\end{verbatim} +The first point to notice is that two authors are separated with the +keyword \texttt{and}\index{bibtex}{and}. The format of the names is +the second important point: The last name first, then the first name, +with a separating comma. In fact, \bt understands other formats. + +Before going further, we remark an important point: \bt will have to +\emph{guess} which part is the first name and which part is the last +name. It also has to distinguish a possible ``von'' part (as in John +von Neumann) and a possible ``Jr'' part. + +The following explanation is somewhat technical. The first name will +be called \verb+First+, the last name is denoted by \verb+Last+, the +``von'' with \verb+von+ and the ``Jr'' part, \verb+Jr+. + + +So, \bt must be able to distinguish between the different parts of the +\chp{author} field. To that aim, \bt recognizes three +possible formats: +\begin{itemize} +\item \verb+First von Last+; +\item \verb+von Last, First+; +\item \verb+von Last, Jr, First+. +\end{itemize} + +The format to be considered is obtained by counting the number of +commas in the name. + Here are the characteristics of these formats: + +\begin{itemize} +\item \verb+First von Last+: Suppose you entered +\verb+Jean de La Fontaine+. There is no comma, hence the format is +\verb+First von Last+. The \verb+Last+ name cannot be empty, unless +the whole field is. It should then contain at least \verb+Fontaine+. +\bt then looks at the first character\footnote{In the sequel, the + first character means ``the first non-brace character that at brace depth + $0$, if + any, characters of a special character being + at depth $0$, even if there are $15$ braces around.'' If there is + no + character at depth $0$, then the item will go with its neighbour, + first and foremost with the \texttt{First}, then with the \texttt{Last}. It + will be in the \texttt{von} if, and only if, it is surrounded with + two \texttt{von} items. Moreover, two words in the same group + (in \LaTeX sense) will go to the same place. Last, for a + \LaTeX command outside a special character, the backslash is removed + and \bt considers the remaining word. If you did not understand, + please take a while for reading this note anew, since it will be + used + in the sequel.} of each remaining word. If some +of them are lower cases alphabetic letters, +anything between the first and the last ones +(beginning with lower cases) is considered as being in the +\verb+von+. Anything before the +\verb+von+ is in the \verb+First+, anything after is in the +\verb+Last+. If no first letter is in lower case, then everything +(except the part already put in the \verb+Last+) is put in the +\verb+First+. + +\verb+Jean de La Fontaine+ will then give \verb+La Fontaine+ as the +\verb+Last+, \verb+Jean+ for the \verb+First+ and \verb+de+ for the +\verb+von+. + +Here is what it gives for several other combinations. This is for you +to check if you understood: +\begin{center} +\begin{longtable}{|>{\vrule height 4mm depth 2mm width 0pt}p{.3\textwidth}|p{.15\textwidth}|p{.15\textwidth}|p{.18\textwidth}|} +\hline +Name & \verb+First+ & \verb+von+ & \verb+Last+ \endfirsthead +\hline +Name & \verb+First+ & \verb+von+ & \verb+Last+ \endhead +\hline +\verb+jean de la fontaine+ & \verb++ & \verb+jean de la+ & \verb+fontaine+ \\ +\hline +\verb+Jean de la fontaine+ & \verb+Jean+ & \verb+de la+ & \verb+fontaine+ \\ +\hline +\verb+Jean {de} la fontaine+ & \verb+Jean de+ & \verb+la+ & \verb+fontaine+ \\ +\hline +\verb+jean {de} {la} fontaine+ & \verb++ & \verb+jean+ & \verb+de la fontaine+ \\ +\hline +\verb+Jean {de} {la} fontaine+ & \verb+Jean de la+ & \verb++ & \verb+fontaine+ \\ +\hline +\verb+Jean De La Fontaine+ & \verb+Jean De La+ & \verb++ & \verb+Fontaine+ \\ +\hline +\verb+jean De la Fontaine+ & \verb++ & \verb+jean De la+ & \verb+Fontaine+ \\ +\hline +\verb+Jean de La Fontaine+ & \verb+Jean+ & \verb+de+ & \verb+La Fontaine+ \\ +\hline +\end{longtable} +\end{center} +The last line is the only one (in this table) that is correct. +Of course, some of you will have a counter example where the +\verb+von+ has to begin with an upper case letter. We'll see this at section~\ref{trucsbib}. + +\item \verb+von Last, First+: The idea is similar, but identifying + the \verb+First+ is easier: It's everything after the comma. Before + the comma, the last word is put in the \verb+Last+ (even if it + starts with a lower case). If any other word begins with a lower + case, anything from the first word to the last one starting with a + lower case is in the \verb+von+, and what remains is in the + \verb+Last+. +Once again, an example should make everything clear: + +\begin{center} +\begin{longtable}{|>{\vrule height 4mm depth 2mm width 0pt}p{.3\textwidth}|p{.15\textwidth}|p{.15\textwidth}|p{.18\textwidth}|} +\hline +Name & \verb+First+ & \verb+von+ & \verb+Last+ \endfirsthead +\hline +Name & \verb+First+ & \verb+von+ & \verb+Last+ \endhead +\hline +\verb+jean de la fontaine,+\footnotemark & \verb++ & \verb+jean de la+ & \verb+fontaine+ \\ +\noalign{\footnotetext{This case raises an error message from \bt, complaining + that a name ends with a comma. +It is a common error to separate names with commas instead of ``\texttt{and}''.}}% +\hline +\verb+de la fontaine, Jean + & \verb+Jean+ & \verb+de la+ & \verb+fontaine+ \\ +\hline +\verb+De La Fontaine, Jean+ & \verb+Jean+ & \verb++ & \verb+De La Fontaine+ \\ +\hline +\verb+De la Fontaine, Jean+ & \verb+Jean+ & \verb+De la+ & \verb+fontaine+ \\ +\hline +\verb+de La Fontaine, Jean+ & \verb+Jean+ & \verb+de+ & \verb+La Fontaine+ \\ +\hline +\end{longtable} +\end{center} +%\medskip + +\item \verb+von Last, Jr, First+: Well... It's still the same, except + that anything between the commas is put in the \verb+Jr+. +\end{itemize} + +Names are separated by spaces above, but it may occur that two +first names are separated by a hyphen, as in ``Jean-Fran\c cois'' +for instance. \bt splits that string, and if both parts are in the +\verb+First+, the abbreviated surnames is ``J.-F.'' as (generally) +wanted. A tilde is also seen as a string separator. This all boils +down to the fact that, if you enter \verb+Jean-baptiste Poquelin+, +the string \verb+baptiste+ will be in the \verb+von+ part of the +name, since it erroneously begins with a lower case letter. +\medskip + +I think it's a good place for coming back to abbreviations: You probably agree +that names are something not that easy to enter, and are +error-prone. I personally advise defining an abbreviation for each +author. You'll then concatenate them with \verb+``and''+ using +\verb+#+\index{bibtex}{\#@\texttt{\#}(concatenation)}\index{bibtex}{concatenation@concatenation (\texttt{\#})}. + +For instance, I always include a \ext{bib} file containing the +following lines: +\begin{verbatimtab} +@string{goossens = "Goossens, Michel"} +@string{mittelbach = "Mittelbach, Franck"} +@string{samarin = "Samarin, Alexander"} +\end{verbatimtab} +another one containing: +\begin{verbatimtab} +@string{AW = "Addison-Wesley"} +\end{verbatimtab} +and my main bibliographic file contains\footnote{This is not quite + true, since \texttt{September} still depends on the language, and I + prefer using \texttt{9} and letting the style file translate that + into the corresponding month in the correct language.}: +\begin{verbatimtab} +@book{companion, + author = goossens #" and "# mittelbach #" and "# samarin, + title = "The {{\LaTeX}} {C}ompanion", + booktitle = "The {{\LaTeX}} {C}ompanion", + year = 1993, + publisher = AW, + month = "December", + ISBN = "0-201-54199-8", + library = "Yes", +} +\end{verbatimtab} +This makes adding an entry much easier when you're used to such an +encoding. Moreover, you can easily recover self-contained entries by using +\texttt{bibexport.sh}~tool (see section~\ref{bibexport}). + + + +\mysection{Cross-references (\protect\nichp{crossref})}\label{crossref} +As mentioned earlier (can't remember where... Oh, yes, on +page~\pageref{cetaitla}), \bt allows for cross-referencing. This is +very useful, for instance, when citing a part of a book, or an article +in conference proceedings. For instance, for citing chapter~$13$ of +the \LaTeX~Companion: +\begin{verbatimtab} +@incollection{companion-bib, + crossref = "companion", + title = "Bibliography Generation", + chapter = 13, + pages = "371-420", +} +\end{verbatimtab} +This shows why having defined the \chp{booktitle} field +of the \verb+companion+~entry is useful: It is not used in the \ent{book} entry, +but +it is inherited in the above \ent{incollection} entry. We could of +course have added it by hand, but we should have added it in each +chapter we cite. + +The other possible interesting feature is that, when cross-referencing +several times an entry that is not cited by itself, \bt can +``factor'' it, \emph{i.e.} add it in the list of references and +explicitly \cmd{cite} it in each entry. On the other hand, if the cross +reference appears only once, it inherits from the fields of the +reference, which is not included in the bibliography. +Here is an example of both behaviours: + +\medskip +\begin{myex} +\begin{thebibliography}{1} + +\bibitem{bib} +Michel Goossens, Franck Mittelbach, and Alexander Samarin. +\newblock Bibliography generation. +\newblock In {\em The {{\LaTeX}} {C}ompanion\/} \cite{companion4}, chapter~13, + pages 371--420. + +\bibitem{math} +Michel Goossens, Franck Mittelbach, and Alexander Samarin. +\newblock Higher mathematics. +\newblock In {\em The {{\LaTeX}} {C}ompanion\/} \cite{companion4}, chapter~8, + pages 215--258. + +\bibitem{ind} +Michel Goossens, Franck Mittelbach, and Alexander Samarin. +\newblock Index generation. +\newblock In {\em The {{\LaTeX}} {C}ompanion\/} \cite{companion4}, chapter~12, + pages 345--370. + +\bibitem{companion4} +Michel Goossens, Franck Mittelbach, and Alexander Samarin. +\newblock {\em The {{\LaTeX}} {C}ompanion}. +\newblock Addison-Wesley, December 1993. + +\end{thebibliography} +\end{myex} + +\medskip \noindent or\medskip + +\begin{myex} +\begin{thebibliography}{1} + +\bibitem{bib2} +Michel Goossens, Franck Mittelbach, and Alexander Samarin. +\newblock Bibliography generation. +\newblock In {\em The {{\LaTeX}} {C}ompanion}, chapter~13, pages 371--420. + Addison-Wesley, December 1993. + +\bibitem{math2} +Michel Goossens, Franck Mittelbach, and Alexander Samarin. +\newblock Higher mathematics. +\newblock In {\em The {{\LaTeX}} {C}ompanion}, chapter~8, pages 215--258. + Addison-Wesley, December 1993. + +\bibitem{ind2} +Michel Goossens, Franck Mittelbach, and Alexander Samarin. +\newblock Index generation. +\newblock In {\em The {{\LaTeX}} {C}ompanion}, chapter~12, pages 345--370. + Addison-Wesley, December 1993. + +\end{thebibliography} +\end{myex} + +In order to have one presentation or the other, we can tell \bt the +number of cross-references needed for an entry to be explicitly +\cmd{cite}{}'d. We use the \verb+-min-crossrefs+ command line argument +of \bt for that. +For the first example above, I used +\verb+bibtex biblio+, +while the second example was obtained with +\verb+bibtex -min-crossrefs=5 biblio+. + + +One other important remark is that cross-referenced entries must be +defined \emph{after} entries containing the corresponding +\chp{crossref} field. And you can't embed +cross-references, that is, you cannot \chp{crossref} an entry that +already contains a \chp{crossref}. + + +Last, the \chp{crossref} field has a particular behaviour: it always +exists, whatever the bibliography style. If a \chp{crossref}{}'ed entry +is included (either by a \cmd{cite} command or by \bt if there are +sufficiently many \chp{crossref}{}s), then the entries cross-referencing +it have their original \chp{crossref} field. Otherwise, that field is +empty. + + + +\mysection{Quick tricks}\label{trucsbib} + +\mysubsection{How to get \emph{Christopher} abbreviated as \emph{Ch.}?} + +First names abbreviation is done when extracting names from the \chp{author} +field. If the function is asked to abbreviate the first name (or any other part +of it), it will return the first character of each ``word'' in that part. +Thus \emph{Christopher} gets abbreviated into \emph{C.} Special characters + provide a solution against this problem: If you enter + \verb+{\relax Ch}ristopher+, the abbreviated version would be + \verb+{\relax Ch}.+, which gives \emph{Ch.}, while the long version is + \verb+{\relax Ch}ristopher+, \emph{i.e.} \emph{{Ch}ristopher}. + +\mysubsection{How to get caps in \texttt{von}?} + +Note: This part is somewhat technical. You should probably read and understand +how \bt extracts names, which is explained at pages~\pageref{noms-start} +and~\pageref{noms-end}. + +It may occur that the \verb+von+ part of a name begins with a capital letter. +For some reason, the standard example is \emph{Maria De La Cruz}. + +The basic solution is to write +\verb+"{\uppercase{d}e La} Cruz, Maria"+. When analyzing this name, \bt will +place \verb+Cruz+ in the +\verb+Last+ part, then \verb+Maria+ as the \verb+First+ name. Then +\verb+{\uppercase{d}e La}+ is a special character, +whose first letter is \verb+d+, and is thus placed in the \verb+von+ part. + +In that case, however, if you use an ``alphanumeric'' style such as +\bst{alpha}, \bt will use the first character of the +\verb+von+ part in the label\footnote{It could be argued \texttt{von} parts +should not be used when computing the label, but classical style file do use +it.}. But the first character here is +\verb+{\uppercase{d}e La}+, and the label would be +\verb+{\uppercase{d}e La}C+, and you'll get \texttt{[{\uppercase{d}e La}C]}. +You'd probably prefer \texttt{[DLC]} or \texttt{[Cru]}. The second solution +would then be +\begin{verbatimtab} + author = {\uppercase{d}}e {\uppercase{l}}a Cruz, Maria. +\end{verbatimtab} +The label would be \verb+{\uppercase{d}}{\uppercase{l}}C+, which is correct. +Another (easier) proposal would be +\begin{verbatimtab} + author = {D}e {L}a Cruz, Maria. +\end{verbatimtab} +This also solves the problem, because \bt only considers characters at level~0 when +determining which part a word belongs to, but takes all letters into account +when extracting the first letter. + + +\mysubsection{How to get lowercase letters in the \texttt{Last}?} + +This is precisely the reverse problem, but the solution will be different. +Assume you cite a paper by the famous Spanish scientist +\emph{Juan de la Cierva y Codorn\'\i u}. The basic ideas are +\begin{verbatimtab} + author = de la Cierva {\lowercase{Y}} Codorn{\'\i}u, Juan +\end{verbatimtab} +or +\begin{verbatimtab} + author = de la Cierva {y} Codorn{\'\i}u, Juan +\end{verbatimtab} +However, these solutions yields labels such as \verb+CYC+ or \verb+CyC+, where +we would prefer \verb+CC+. + +Several solutions are possible: +\begin{verbatimtab} + author = de la Cierva{ }y Cordon{\'\i}u, Juan +\end{verbatimtab} +or +\begin{verbatimtab} + author = de la {Cierva y} Cordon{\'\i}u, Juan +\end{verbatimtab} +Both solutions work: In the first case, \bt won't see the space, and +considers that the \verb+y+ belongs to the previous word. In the second case, +\verb+Cierva y+ is at brace-level~$1$, and thus goes into the \verb+Last+ part, +which has priority over the \verb+von+ part. + +\mysubsection{How to remove space between \texttt{von} and \texttt{Last}?} + +Here the example will be \emph{Jean d'Ormesson}. +The best way to encode this appears to be +\begin{verbatimtab} + author = "d'\relax Ormesson, Jean" +\end{verbatimtab} +Indeed, the \nicmd{relax} commands will gobble spaces until the next +non-space character. + +\mysubsection{How to get \emph{et al.} in the author list?} + +Some special bibliography styles will automatically replace long lists of +authors with the name of the first author, followed by \emph{et al.} +However, standard \bt styles won't. You can however get the same result by +using the special name \verb+others+. For instance, if you enter +\begin{verbatimtab} + author = "Dupont, Jean and others" +\end{verbatimtab} +you get "Jean Dupont \emph{et al.}" in the resulting bibliography. + +\mysubsection{The \protect\nichp{key} field} + +It may happen that no author is given for a document. In that case, +bibliography styles such as \bst{alpha}, when computing the ``label'' of such +an entry, will use the \chp{key} field (the first three letters for +\bst{alpha}, but the entire field for \bst{apalike}, for instance). +When no \texttt{key} is given, the first three letters of the internal +citation key are used. + +\bigskip + +Is it ok with everyone? Yes ?! +Right, we can go to the next, most exciting part of +this doc: How to create or modify a bibliography style... + + diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec4.tex b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec4.tex new file mode 100644 index 00000000000..c6d81e4d574 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec4.tex @@ -0,0 +1,841 @@ +%% ttb_en.sec4.tex +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + + +\mypart{Bibliography style (\protect\niext{bst}) files}\label{bst} +\parttoc +\mtcskip + +\mysection{What's that?} + +The \ext{bst} file is responsible for building the reference list. It is +crucial to distinguish between the role of \bt and the role of \LaTeX, and, +inside the role of \bt, +between what is done by the style file and what should be done in the +\ext{bib} file. + +Roughly speaking, \bt reads three files, in the following order: The \ext{aux} +file first, where it finds the name of the style file to be used, the name of +the database(s), and the list of cited entries. The \ext{bst} file is read +next, and the \ext{bib} file last. + +The \ext{bst} file tell \bt what to do with each cited entry. Namely: +\begin{itemize} +\item Which entry-type are defined; +\item Which fields are mandatory, or just allowed, depending on the entry; +\item And, mainly, how to handle all that stuff in order to produce a clean, + \LaTeX-able bibliography. +\end{itemize} + +In view of this, \bt uses a language with two types of instructions: The +so-called \emph{commands}\index{bibtex}{command}, first, and the +\emph{internal functions}\index{bibtex}{internal function}. The following section +deals with commands, and the other ones with internal functions. + + +\mysection{The structure of a \protect\niext{bst} file} + +Here is, roughly speaking, the structure of a \ext{bst} file: + +\begin{myexv} +\begin{verbatimtab} +ENTRY + { ... } + { ... } + { ... } + +INTEGERS { ... } +STRINGS { ... } + +MACRO { ... }{ ... } +FUNCTION { ... }{ ... } + +READ +EXECUTE { ... } +ITERATE { ... } +SORT +ITERATE { ... } +REVERSE { ... } +EXECUTE { ... } +\end{verbatimtab} +\end{myexv} + +This example shows all the +commands\index{bibtex}{command} understood by \bt. +Here is their meaning: +\begin{description} +\item[\texttt{ENTRY}]\index{bibtex}{entry@\texttt{ENTRY}}: This command defines + the list of all possible fields. More precisely, it takes three arguments + (between braces), defining the list of possible ``external'' (string) + entries\footnote{Except the \chp{crossref} field, which is added + automatically by \bt.}, the list of ``internal'' integer variables, and a + list of ``internal'' string variables. Those variables are used for internal + computations of \bt, for instance when building the label with the + \bst{alpha} style. + + Inside braces, variable names are + separated with spaces. I shall also mention that \bt does not distinguish + between upper- and lowercase in the names of functions and variables. I will + generally write command names in uppercase, and everything else in lowercase. + + For instance, \bst{plain} starts with: +\begin{myexv} +\begin{verbatimtab} +ENTRY + { address + author + booktitle + ... + volume + year + } + {} + { label } +\end{verbatimtab} +\end{myexv} +\noindent This defines the classical fields, plus an internal +string variable for the label. In fact, \bst{plain} uses numbers as labels, +but remember that the length of the longest label has to be evaluated and +given as argument to the \env{thebibliography} environment. This is the only +reason why this \verb+label+ variable is defined. + +Note that \texttt{ENTRY} must appear once and only once in each style file. + +\item[\texttt{INTEGERS}]\index{bibtex}{integers@\texttt{INTEGERS}}: This command + declares integer variables\footnote{Those variables are not linked with any + entry, contrary to variables defined in the second argument of + \texttt{ENTRY}.}. The argument of this command is a space-separated + list of names. + +\item[\texttt{STRINGS}]\index{bibtex}{strings@\texttt{STRINGS}}: This commands + defines string variables in the same way as \texttt{INTEGERS} defines + integer variables. Contrary to integer variables, string variables are very + ``expensive'', and \bt limits the number of such variables to twenty. You + should really spare string variables if you plan to develop a large style + file. + +\item[\texttt{MACRO}]\index{bibtex}{macro@\texttt{MACRO}}: This command defines + abbreviations, in the same way as \ent{string} does\footnote{Note that + \ent{string} has nothing to do with + \texttt{STRINGS}\index{bibtex}{strings@\texttt{STRINGS}}...}. + If an abbreviation is defined in both the \ext{bst} and in the + \ext{bib} file, the definition in the \ext{bib} file is used. Also note that + you can define \ent{string} definitions involving \texttt{MACRO} + definitions. But this is probably not a good advice... + + As regards the syntax, \texttt{MACRO} requires two arguments, the first one + being the name of the abbreviation to be defined, the second one being the + definition itself. It must be a string surrounded with double-quotes. + As an example, standard style files define the following: +\begin{myexv} +\begin{verbatimtab} +MACRO {jan} {"January"} +MACRO {feb} {"February"} +MACRO {mar} {"March"} +... +\end{verbatimtab} +\end{myexv} +\item[\texttt{FUNCTION}]\index{bibtex}{function@\texttt{FUNCTION}}: The most useful + command: It allows to define macro functions that will be executed later on. + The first argument is the name of the function, the second one is its + definition. No example for the moment since there will be numerous ones in + the following. +\item[\texttt{READ}]\index{bibtex}{read@\texttt{READ}}: As for \texttt{ENTRY}, + this command must occur exactly once in any \ext{bst} style file. This is + not surprising since it tells \bt to read the \ext{bib} file: Reading it + several time would not change anything, and not reading it would seriously limit the + interest of the bibliography style. So, that command extracts from the + \ext{bib}-file the entries that are cited in the \ext{aux} file. Commands + \texttt{ENTRY} and \texttt{MACRO} should appear before \texttt{READ}, while + \texttt{ITERATE} and \texttt{REVERSE} may only appear after. +\item[\texttt{EXECUTE}]\index{bibtex}{execute@\texttt{EXECUTE}}: This executes + the function whose name is given as argument. Note that the function must + have been defined earlier. The argument could also be a sequence of \bt + internal functions. For some more comments, see the + description of \texttt{ITERATE} below. +\item[\texttt{ITERATE}]\index{bibtex}{iterate@\texttt{ITERATE}}: +This commands also execute the function given in the argument, but contrary to +\texttt{EXECUTE}, the function is executed as many times as the number of +entries imported by \texttt{READ}. The function may use the fields of +each entry. \texttt{EXECUTE} only executes its argument once, and it can not +use any field of any entry. +\item[\texttt{SORT}]\index{bibtex}{sort@\texttt{SORT}}: +This command sorts the entries according to the variable \fn{sort.key}. That +special variable is a string variable, implicitly declared for each entry, +and that can be set by \texttt{ITERATE}{}ing a function. The entries are then +sorted alphabetically according to that string. Of course, some styles won't +sort the entries, in which case they will appear in the same order as in the +document. +\item[\texttt{REVERSE}]\index{bibtex}{reverse@\texttt{REVERSE}}: +Like \texttt{ITERATE}, but from the last entry to the first one. +\end{description} + +That's all for the list of commands. You probably can imagine how this will be +set up. It remains to define the relevant \texttt{FUNCTION}{}s... This is the +subject of the next two sections: We will first see the notation used by \bt, +and then how to define functions. + +\mysection{Reverse Polish Notation} + +\bt uses the so-called Reverse Polish Notation. This is the main reason why +people say that \bt language is hard to understand. It is a stack-based +language: You put arguments on a stack (think of a stack of plates), and each +function takes as many arguments as necessary on the top of the stack, and +replace them with its result. Addition, for instance, will take the first two +elements on the stack, add them, and put the result on the top of the stack. +Another example\footnote{This part is crucial, that's why I insist on it. + But if you really understood how it works, + you can skip the explanation.}: \verb/ 1 3 5 + 2 3 * - / is executed as +follows: +\begin{itemize} +\item \verb+1+ is put on the stack. Assuming the stack was initially empty, it + now contains \verb+1+; +\item \verb+3+ is then put on the stack, which now contains +\verb+1+ and \verb+3+ (\verb+3+ being on the top of the stack); +\item \verb+5+ is added on the stack, which now contains \verb+1+, \verb+3+ + and \verb+5+; +\item \verb/+/ is a binary operator: it reads (and removes) the topmost two + elements on the + stack, which are \verb+5+ and \verb+3+, adds them, and put the resulting + value, \verb+8+, on the top of the stack. The stack is now \verb+1+, + \verb+8+, with \verb+8+ being on the top; +\item \verb+2+ is put on the top of the stack; +\item \verb+3+ is put on the stack. It now contains \verb+1+, \verb+8+, + \verb+2+ and \verb+3+. +\item \verb+*+ is applied to the topmost two elements, which are removed. +The resulting value\footnote{We assume that $\mathtt *$ is the + multiplication in that example, but it is not the case in \bt. In fact, + there is no multiplication operator in \bt, as we will see later, and + $\mathtt{*}$ is the concatenation on strings.}~$3\times 2=6$ +is put on top of the stack, which is now made of \verb+1+, \verb+8+ and +\verb+6+. +\item \verb+-+ is now applied to \verb+6+ and \verb+8+. As defined in + \bt\footnote{This operator is not commutative, and it could have been + defined in the other way.}, the + first value, \verb+6+, is subtracted to the second one, \verb+8+. + Finally, the stack contains \verb+1+ and \verb+2+. +\end{itemize} + +If you did not understand this example, you'd better re-read it, or try to +find more informations somewhere. This is really the core of \bt language, and +you'll probably won't understand anything below if you did not understand +this example. + +But for most of you, it should be ok, and we can tackle the most exciting part. + + +\mysection{Internal functions} + +The table below describes all internal functions\index{bibtex}{internal function}. +For each of them, I give +\begin{itemize} +\item on the left, the items it requires to be present on the top of the +stack, the rightmost item being the uppermost on the stack; +\item on the right, what the function puts on the top of the stack. +\end{itemize} +I will use the following conventions: \el I represents an integer, \el S is a +string, \el F is a function, \el N is a variable name\footnote{A variable name + is a name that has been declared with \texttt{STRINGS} or \texttt{INTEGERS}, + or with \texttt{ENTRY}. + Moreover, it must be preceded with a single quote, so that \bt understands + that you mean the name of the variable and not its value. For instance, + \texttt{'label}.}, \el C is the name of a field declared with +\texttt{ENTRY}\footnote{It could also be \chp{crossref}, which is implicitly + declared by \bt.}, and \el E is an item that can be either a string or an integer.. + +\begin{longtable}{|>{\vrule height9pt depth5pt width0pt}rlr|p{.58\textwidth}<{\vrule height5pt depth7pt width0pt}|} +\hline\endhead +\hline\endfirsthead +\hline\endfoot +\hline\endlastfoot +\eli I1 \eli I2 & \texttt+ & (\eli I1$+$\el I2) & +integer addition\footnotemark; \\ +\noalign{\footnotetext{Integers must be preceded with a +\texttt\#. For instance, if you want to compute $2+5$, you'll enter +\texttt{\#2 \#5 +}. Negative numbers are entered with \texttt{\#-3}, for +instance. }} +\eli I1 \eli I2 & \texttt- & (\eli I1$-$\eli I2) & +integer subtraction; \\ +\eli I1 \eli I2 & \texttt> & \el I & +returns $1$ if \eli I1 is strictly greater than \eli I2, and~$0$ +otherwise\footnotemark;\\ +\noalign{\footnotetext{There is no boolean type in \bt, because integers are + sufficient. Negative numbers (including $0$) mean \texttt{false}, and + strictly positive mean \texttt{true}.}} +\eli I1 \eli I2 & \texttt< & \el I & returns $1$ if \eli I2 is strictly +greater than \eli I1, and $0$ otherwise; \\ +\eli I1 \eli I2 & \texttt= & \el I & returns $1$ if both integers are equal, +and $0$ otherwise;\\ +\eli S1 \eli S2 & \texttt = & \el I & returns $1$ if both strings are equal, +and $0$ otherwise;\\ +\eli S1 \eli S2 & \texttt* & (\eli S1\eli S2) & concatenates both strings\footnotemark; \\ +\noalign{\footnotetext{As mentioned earlier, there is not multiplication in + \bt{}\footnotemark.}}% +\noalign{\footnotetext{We will define one later, since it may be useful.}} +\el E \el N & \texttt{:=} & & assignment operation. Provided that variable \el +N has the same type as item \el E, it is set to that value; \\ +\el S & \fn{add.period} & \el S & adds a period at the end of string \el S, +except if \el S already ends with a period, or an exclamation or question +mark (after removing right braces); \\ +& \fn{call.type} && executes the function whose name is the type of the +current entry. For instance, for an entry \nient{book}, it runs the function +\texttt{book}. Of course, this command cannot be executed through an +\texttt{EXECUTE} command, it can only be called with \texttt{ITERATE} or +\texttt{REVERSE}. +This explains how to add new entry-types: you simply have to define a function +whose name is the entry-type. If an entry-type is used and the +corresponding function has not been defined before the \texttt{READ} command, + \bt will complain; \\ +\el S \texttt{"t"} & \fn{change.case} & \el S & +turns \el S to lower case, except for the first letter and for letters that +appear at brace-depth strictly positive. Remember that special characters are +at depth~0; \\ +\el S \texttt{"l"} & \fn{change.case} & \el S & +turns \el S to lower case, except parts that are at strictly positive +brace-depth; \\ +\el S \texttt{"u"} & \fn{change.case} & \el S & +turns \el S to upper case, except... \\ +\el S & \fn{chr.to.int} & \el I & +if \el S contains only one character (in the classical sense, \emph{i.e.} not +considering special characters), returns its ASCII code; \\ +& \fn{cite} & \el S & puts on the stack the internal key of the current entry. +Only meant to be used with \texttt{ITERATE} or \texttt{REVERSE}, of course;\\ +\el E & \fn{duplicate} & \el E \el E & +adds a copy of the first item on the top of the stack;\\ +\el E & \fn{empty} & \el I & adds $1$ on the top of the stack if \el E is an +empty string or an empty (but defined) field, and $0$ otherwise; \\ +\eli S1 \el I \eli S2 & \fn{format.name} & \el S & +extract the \el I-th name of string \eli S1 (in which names are separated by +\texttt{and}), and formats it according to specification given by string \eli +S2. I can't explain all that here, see the next section for more details; \\ +& \fn{global.max} & \el I & +put on the stack the maximal length allowed for strings. This is useful to +ensure that a string obtained by concatenation is not too long, but the value +is generally quite high (5000~characters); \\ +\el I \eli F1 \eli F2 & \fn{if} && execute \eli F1 if \el I is strictly +positive, and \eli F2 otherwise; \\ +\el I & \fn{int.to.chr} & \el S & turns \el I to its corresponding character +in the ASCII table. \el I must be between $0$ and $127$; \\ +\el I & \fn{int.to.str} & \el S & turns an integer to the equivalent +string\footnotemark; \\ +\noalign{\footnotetext{Scientists would remark that I did not define the + equivalence relation I deal with. I think an example will be sufficient: + if \el I is 147, the equivalent string is \texttt{"147"}.}} +\el C & \fn{missing} & \el I & returns $1$ if field \el C has been defined in +the current entry, and $0$ otherwise;\\ +& \fn{newline} & & flushes the output buffer to the \ext{bbl} file, and + starts a new line; \\ +\el S & \fn{num.names} & \el I & returns the number of names in string \el S. +This is done by counting the number of occurrences of \texttt{and}, surrounded +with spaces and at level~$0$, and adding~$1$; \\ +\el E & \fn{pop} & & removes the topmost item on the stack; \\ +& \fn{preamble} & \el S & puts on the stack a string made of the concatenation +of all \chp{preamble} declarations found in the \ext{bib} file; \\ +\el S & \fn{purify} & \el S & +removes all non-alphanumeric characters of string~\el S. More precisely, this +functions preserves letters and numbers and spaces, replaces each tabulation, +hyphen and tilde with a space, and removes other standard characters, namely +characters not listed above and appearing in the table given in appendix~C of +the \TeX{}book. Special characters are an exception: \LaTeX commands are +removed, as well as spaces, tabulations, hyphens and tildes. Only numbers and +letters appearing outside \LaTeX command names are preserved.% +\label{purify} + +Practically, this commands is used for cleaning strings before comparing them, +when sorting entries. This is why it is important to keep only ``known'' +characters. I insists on the fact that ``\texttt{\bs'e}'' and ``\texttt{\'e}'' +are different, from this point of view, since the first one will be +transformed into an \texttt e, while the second one will be unchanged, but, +when sorting, will be put after the standard 26~letters. \\ +& \fn{quote} & \el S & adds the 1-character string + \verb+"+ on the stack;\\ +& \fn{skip} && does nothing; \\ +& \fn{sort.key} & \el S & this function is in fact a string variable, +implicitly declared for each entry, and that is used by \texttt{SORT}. It +must therefore be defined accordingly before sorting; \\ +... \el E \el E& \fn{stack} && clears the stack, and prints its contents on +standard output (not in the output file); \\ +\el S \eli I1 \eli I2 & \fn{substring} & \el S & extracts from \el S the +string of length \eli I2 starting at position~\eli I1. By convention, the +first character is at position~$1$. Note that special characters and braces +are not considered here, so that the substring of \verb+{\LaTeX}+ of length~3 +starting at position~2 is \verb+\LaT+; \\ +\eli E1 \eli E2 & \fn{swap} & \eli E2 \eli E1 & +swaps both topmost items on the stack; \\ +\el S & \fn{text.length} & \el I & returns the number of characters of \el S, +special characters being considered as only one character, and braces being +omitted; \label{textlength} \\ +\el S \el I & \fn{text.prefix} & \el S & +returns the first \el I characters of \el S, still considering special +characters as only one character, and omitting braces. Braces are output, +however. For instance, the prefix of length~3 of \verb+{{\LaTeX}}1234+ is +\verb+{{\LaT}}+, while it is \verb+{\LaTeX}12+ for \verb+{\LaTeX}1234+; \\ +\el E & \fn{top} && echoes the first item of the stack on standard output (not +in the output file) and removes it from the stack; \\ +& \fn{type} & \el S & adds on the stack the type of the current entry; \\ +\el S & \fn{warning} && writes \el S in a warning message on the standard +output; \\ +\eli F1 \eli F2 & \fn{while} & & +successively executes \eli F1 and \eli F2 while \eli F1 returns a strictly +positive value. \eli F1 has to return an integer; \\ +\el S & \fn{width} &\el I& returns the length of string \el S, in hundredths +of a point, when written using font \emph{cmr}10 of June 1987. You probably +don't mind the details... This function is used for comparing widths of +labels, the longest label being passed as the argument of the +\env{thebibliography} environment; \\ +\el S & \fn{write} && write \el S in the output \ext{bbl} file. +\end{longtable} + +We're done. This should be sufficient for defining plenty of functions for +managing entries, sorting them, label them and typeset them. Before using +them, I promised to explain how \fn{format.name} works. + + +\mysection{The \protect\nifn{format.name} function}\label{noms-start} + +This function is quite complicated. The syntax is as follows: +\begin{center} +\begin{minipage}{.8\textwidth} +\eli S1 \el I \eli S2 \ \fn{format.name}\ \el S +\end{minipage} +\end{center} + +The first argument \eli S1 is generally the content of fields \chp{author} or +\chp{editor}. It is a list of names separated +with \verb+and+. If names are in one of the three formats recognized by \bt +(see section~\ref{author}), \bt will be able to detect the last name, first +name, ``von'' and ``complement''. String \eli S2 defines the output format. +Here is an example: +\begin{center} +\begin{minipage}{.8\textwidth} +\begin{verbatimtab} +"{ff }{vv }{ll}{, jj}" +\end{verbatimtab} +\end{minipage} +\end{center} +The format of such a specification is defined as follows: +\begin{itemize} +\item globally, it is a list of strings, each one being surrounded with + braces; +\item \verb+ff+ represents the \verb+First+ part, \emph{i.e.} the first name; + \verb+ll+ is the \verb+Last+ part, \emph{i.e.} the last name, and \verb+vv+ and + \verb+jj+ are the \verb+von+ and \verb+jr+ part of the name; +\item \fn{format.name} replaces, in each string of list \el S2, strings + \verb+ff+, \verb+ll+, \verb+vv+ and \verb+jj+, with their respective values. + If a value is empty, the complete string is removed. Otherwise, the other + characters in the string are output. In the example above, for instance, if + the \verb+jr+ part is empty, the comma won't be output, and if the + \verb+First+ part is not empty, it will be followed with a space. +\end{itemize} + +This should be almost clear, now. I just mention, but you've probably already +understood, that the integer \el I indicates that we are working on the \el +I-th name of \eli S1. + +Last, there exists abbreviated forms for name formats. They are used to +extract the first letter of first names, for instance. It suffices to replace +\verb+{ff }+ with \verb+{f }+. For multiple names in one part +(several first names, for instance), the first +letter of each name is written, followed with a period. Different names must +be separated with a space, a tabulation, a tilde or an hyphen. Tabulations +are turned to spaces, tildes and hyphens are preserved. Note that there is no +period at the end, and it must be specified by hand by writing \verb+{f. }+. +For instance +\begin{myexv} +\begin{verbatimtab} +"Goossens, Michel and Mittelbach, Franck and Samarin, Alexander" +#2 "{f. }{vv }{ll}{, jj}" format.name$ +\end{verbatimtab} +\end{myexv} %$ +\noindent returns \textit{F. Mittelbach}. +Let's have a look at several other interesting examples: +\begin{myexv} +\begin{verbatimtab} +"Charles Jean Gustave Nicolas de La Vall{\'e}e Poussin" +#1 "{vv }{ll}{, f}" format.name$ +\end{verbatimtab} +\end{myexv} %$ +\noindent +yields \emph{de La Vall\'ee Poussin, C.J.G.N} +without the final period, since we did not ask for it. +\begin{myexv} +\begin{verbatimtab} +"Doppler, {\relax Ch}ristian Andreas" +#1 "{f. }{vv }{ll}" format.name$ +\end{verbatimtab} +\end{myexv} %$ +\noindent gives \emph{Ch.~A. Doppler}. +Last, +\begin{myexv} +\begin{verbatimtab} +"Jean-Baptiste Poquelin" #1 "{f. }{vv }{ll}" format.name$ +\end{verbatimtab} +\end{myexv} %$ +\noindent outputs \emph{J.-B. Poquelin}. + +You probably remarked that one problem is still unsolved: For creating +labels from author names, we will of course use \fn{format.name}, and we'd +like to get \verb+LVP+, say, for a book by +La Vall\'ee Poussin. The first idea, of course, is: +\begin{myexv} +\begin{verbatimtab} +"Charles Jean Gustave Nicolas de La Vall{\'e}e Poussin" +#1 "{l}" format.name$ +\end{verbatimtab} +\end{myexv} %$ +\noindent +which unfortunately gives \emph{L. V. P}, which would look awful as a label. +But in fact, the period added between names is a default value, but can be +explicitly given. In our case, we would like to replace the period with empty strings: +\begin{myexv} +\begin{verbatimtab} +"Charles Jean Gustave Nicolas de La Vall{\'e}e Poussin" +#1 "{l{}}" format.name$ +\end{verbatimtab} +\end{myexv} %$ +\noindent +which gives the expected \emph{LVP}. +Braces following \verb+l+ mean that nothing should be put between names or +letters. It is also possible to add some text only once, before or after +the names. Spaces can be entered directly, while text and commands should be +put between braces, so that \bt distinguished them with \verb+ff+, +\verb+ll+,~... specifications. An example should make this clear: +\begin{myexv} +\begin{verbatimtab} +"Charles Jean Gustave Nicolas de La Vall{\'e}e Poussin" +#1 "{{\scshape\bgroup}ff{ }{\egroup}" format.name$ +\end{verbatimtab} +\end{myexv} %$ +\noindent gives +\verb+{\scshape\bgroup}Charles Jean Gustave Nicolas{\egroup}+, and thus +<<~{\scshape\bgroup}Charles Jean Gustave Nicolas{\egroup}~>>. +Note that we had to trick \bt and \LaTeX regarding the \cmd{bgroup}: braces, +which are necessary in \bt name specifications, are copied verbatim in the +output... +\label{noms-end} + +\medskip +Well... Once again, I could stop here, since you know everything, at least +from the theoretical point of view. But this would not be a good +idea. So the next sections are devoted to some examples and tricks that could +be useful. + +\clearpage +\mysection{Some practical tricks} + +In fact, the main trick to know is how to build a minimal file, in order to +test \bt{}'s behavior, for instance for testing the encoding of a name. This +basic style file will simply output its result on the standard output. +Assume you want to see how \bt cuts the following name: +%\begin{myexv} +\begin{center} +\begin{minipage}{.8\textwidth} +\begin{verbatimtab} +de la Cierva y Codorn{\'\i}u, Juan +\end{verbatimtab} +\end{minipage} +\end{center} +%\end{myexv} %$ + +The minimal \ext{bst} file must contain +\texttt{ENTRY}\index{bibtex}{entry@\texttt{ENTRY}} and +\texttt{READ}\index{bibtex}{read@\texttt{READ}} +commands, even if we won't use any entry. It must also compute the desired +result. Our style file, \verb+min.bst+, will be: +\begin{myexv} +\begin{verbatimtab} +ENTRY {}{}{} + +FUNCTION {test} +{"de la Cierva y Codorn{\'\i}u, Juan" +#1 "{ff - }{vv - }{ll}" format.name$ top$} + +READ + +EXECUTE{test} +\end{verbatimtab} +\end{myexv} +\noindent This will split the name and write the different parts, separated +with hyphens. + +The \ext{aux} file now: it will simply define the style file to be used: +\begin{myexv} +\begin{verbatimtab} +\bibstyle{min} +\end{verbatimtab} +\end{myexv} + +This file, called \verb+min.aux+, contains neither the \cmd{bibdata} +precising the \ext{bib} file to use, nor the \cmd{citation}{}s declaring the +entries to be extracted. \bt will, of course, complain about that, but will +continue the execution anyway. + +The result is as follows: +\begin{myexv} +\begin{verbatimtab} +% bibtex min +This is BibTeX, Version 0.99c (Web2C 7.4.5) +The top-level auxiliary file: min.aux +The style file: min.bst +I found no \citation commands---while reading file min.aux +I found no \bibdata command---while reading file min.aux +Warning--I didn't find any fields--line 1 of file min.bst +Juan - de~la Cierva~y - Codorn{\'\i}u +(There were 2 error messages) +\end{verbatimtab} +\end{myexv} + +We get the error messages, but also the result, showing that our encoding is +not correct (since the \verb+von+ part should only contain \verb+de la+). +As regards unbreakable spaces: \bt automatically adds unbreakable spaces +instead of the first and last spaces. + +This provides you with a way to test all your future \bt functions, which can +be quite useful since \bt error messages are generally difficult to understand. +You can also try to test if \fn{purify} behaves as I said previously. + + +\mysection{Some small simple functions} + +\mysubsection{Boolean functions} + +As you know, \bt does not know about booleans. In particular, there is no +negation, conjunction or disjunction, while it would be quite useful. +Those operations are defined on figure~\ref{fig1}. + +\begin{figure}[!htbp] +\begin{myexv} +\begin{verbatimtab} +FUNCTION {not} +{ { #0 } + { #1 } + if$ +} + +FUNCTION {and} +{ 'skip$ + { pop$ #0 } + if$ +} + +FUNCTION {or} +{ { pop$ #1 } + 'skip$ + if$ +} +\end{verbatimtab} +\end{myexv} %$ +\caption{Basic boolean functions}\label{fig1} +\end{figure} +Let me just explain the first two: For negation, you assume there is a boolean +(\emph{i.e.} an integer) on the top of the stack. Function \fn{if} will test that +boolean. If it evaluates to \verb+true+, the function returns \verb+#0+ (\emph{i.e.} +\verb+false+), and otherwise it returns \verb+#1+ (\emph{i.e.} \verb+true+). +This is precisely what we wanted. + +For the conjunction: we have two booleans on the stack. Function \fn{if} tests +the first one. If it is \verb+true+, then we do nothing (thus leaving the +second boolean on the top of the stack, it's value being the result of the +conjunction). If it is \verb+false+, the conjunction is false: We remove the +second argument and put \verb+#0+ on the top of the stack. + +\mysubsection{Multiplication} + +Figure~\ref{fig2} shows how to compute the multiplication of two integers. +I won't enter into the details, comments should be sufficient. In the same +way, you can try to define integer division, gcd, primality testing,~... +But I'm not sure if it is useful. Multiplication can be, as you'll see below. + +\begin{figure}[!htbp] +\begin{myexv} +\begin{verbatimtab} +INTEGERS { a b } + +FUNCTION {mult} +{ + 'a := %% we store the first value + 'b := %% we store the second value + + b #0 < %% We remember the sign of b, and + {#-1 #0 b - 'b :=} %% then consider its absolute value. + {#1} %% + if$ %% + + #0 %% Put 0 on the stack. + {b #0 >} %% While b is strictly positive, + { %% we add a to the value on the stack + a + %% and decrement b. + b #1 - 'b := %% + } %% + while$ %% + + swap$ %% Last, we take the opposite + 'skip$ %% if b was negative. + {#0 swap$ -} %% + if$ %% +} +\end{verbatimtab} +\end{myexv} +\caption{The ``multiplication'' function}\label{fig2} +\end{figure} + + +\mysubsection{Converting a string to an integer} + +There is no direct way for converting a string (made of digits) to the +corresponding integer. We will define a function achieving this, and returning +an error message whenever the string is not a number. +This is done recursively, as shown on figure~\ref{fig3}. + +\begin{figure}[!htbp] +\begin{myexv} +\begin{verbatimtab} +FUNCTION {chr.to.value} %% The ASCII code of a character +{ + chr.to.int$ #48 - %% ASCII value of "0" -> 48 + duplicate$ duplicate$ %% "1" -> 49 + #0 < swap$ #9 > or %% ... + { %% "9" -> 57 + #48 + int.to.chr$ + " is not a number..." * + warning$ %% Return 0 if it is not a number + pop$ #0 %% + } + {} + if$ +} + +FUNCTION {str.to.int.aux} %% The auxiliary function +{ + {duplicate$ empty$ not} %% While the string is not empty + { %% consider its first char + swap$ #10 mult 'a := %% and ``add'' it at the end of + duplicate$ #1 #1 substring$ %% the result. + chr.to.value a + + swap$ + #2 global.max$ substring$ + } + while$ + pop$ +} + +FUNCTION {str.to.int} +{ %% Handling negative values + duplicate$ #1 #1 substring$ "-" = + {#1 swap$ #2 global.max$ substring$} + {#0 swap$} + if$ + %% Initialization, and then + #0 swap$ str.to.int.aux %% call to the aux. funtion + swap$ + {#0 swap$ -} %% And handle the sign. + {} + if$ +} +\end{verbatimtab} +\end{myexv} %$ +\caption{Converting a string to an integer}\label{fig3} +\end{figure} + +There are several interesting points: first, it requires boolean functions, +and multiplications. Those functions must thus be added before the above +definitions. Moreover, function \verb+chr.to.value+ emphasizes an important +rule of thumb: A function must always behave in the same way as regards the +stack: Same type and numbers of inputs, same type and number of outputs. For +instance, here, if the character is not an integer, we complain, but we return +an integer, as if everything was ok. This rule is very important unless you +want to spend some time in debugging. + + +\mysubsection{Counting the number of characters in a string} + +As we saw on page~\pageref{textlength}, \fn{text.length} counts the number of +characters in a string, but assuming \bt's meaning of ``character''. +In fact, the only function that assumes the standard definition of a character +is \fn{substring}. We will use it repeatedly for counting the number of +characters of a string, by computing the successive prefixes until they equal +the original string. + +\begin{figure}[!htbp] +\begin{myexv} +\begin{verbatimtab} +INTEGERS{ l } +FUNCTION{ string.length } +{ + #1 'l := + {duplicate$ duplicate$ #1 l substring$ = not} + {l #1 + 'l :=} + while$ + pop$ l +} +\end{verbatimtab} +\end{myexv} %$ +\caption{A function for counting the \emph{real} number of characters}\label{fig4} +\end{figure} + +As an exercise, the reader can try to implement another algorithm: removing +one after the other the first characters of the string until the resulting +string is empty. + +\mysubsection{A ``search-and-replace'' function} + +With the function above, we can now design an algorithm for searching and +replacing the occurrences of a string in a given text. Once again, we cannot +use \fn{text.length} and \fn{text.prefix} since they assume a special +definition of a character. We only use the function \verb+string.length+ and +\fn{substring}. The idea is to successively extract the first $n$ characters +of the text, compare them with the pattern, and replace it or drop the first +character, depending on the result of the comparison. + +\begin{figure}[!htbp] +\begin{myexv} +\begin{verbatimtab} +STRINGS{replace find text} +INTEGERS{find_length} +FUNCTION{find.replace} +{ 'replace := + 'find := + 'text := + find string.length 'find_length := + "" + { text empty$ not } + { text #1 find_length substring$ find = + { + replace * + text #1 find_length + global.max$ substring$ 'text := + } + { text #1 #1 substring$ * + text #2 global.max$ substring$ 'text := + } + if$ + } + while$ +} +\end{verbatimtab} +\end{myexv} %$ +\caption{Search-and-replacing with \bt}\label{fig5} +\end{figure} + +This function replaces all the occurrences of the pattern, but it can easily be +adapted for replacing only the first occurrence. As an exercise, the reader can +try to implement the same algorithm using only two string +variables\footnote{Hint: try to leave \texttt{find} on the stack.} (it may be +important to spare string variables since their number is very limited). diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec5.tex b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec5.tex new file mode 100644 index 00000000000..83bc4f6e3eb --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec5.tex @@ -0,0 +1,179 @@ +%% ttb_en.sec5.tex +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + + +\mypart{Other use of \bt}\label{autres} +\parttoc +\mtcskip + +Here are some general extensions, showing how to use \bt for other purposes. +I'm developing some of those extensions, and you can get the latest news on my web +page: +\begin{center} +\url{http://www.lsv.ens-cachan.fr/~markey/bibla.php}. +\end{center} +Don't hesitate to give me your comments and ideas. + +\mysection{A publication list} + +This is not really a wide extension of the use of \bt, since it still deals +with bibliography. In this example, we use classical \ext{bib} files in order +to extract only publications by one single person, indicating the names of the +possible other authors. This gives, for instance: +\begin{myex} +\def\refname{Books by Michel \textsc{Goossens}} +\begin{thebibliography}{9} +\bibitem{companion} +{\em the \LaTeX{} Companion}. +Addison-Wesley, 1993. +Joint work with Frank Mittelbach and Alexander Samarin. + +\bibitem{graphics} +{\em the \LaTeX{} Graphics Companion}. +Addison-Wesley, 1999. +Joint work with Sebastian Rahtz and Frank Mittelbach. + +\bibitem{webc} +{\em the \LaTeX{} Web Companion}. +Addison-Wesley, 1999. +Joint work with Sebastian Rahtz. + +\end{thebibliography} +\end{myex} + +There are three important points here: +\begin{itemize} +\item In this case, the entries to be cited are extracted by the style file; +\item Typesetting of names is a little bit different. +\end{itemize} + +The third difference consists in the way the style is configured: Instead of +asking the user to modify the \ext{bst} file, which is rarely desirable, we +add a new entry-type, named \nient{config}. A \nient{config} entry will define +the name of the author whose publications are to be extracted, as well as some +other configuration variables. + +\mysection{An addressbook} + +A list of addresses is a database, that has to be sorted, grouped and typeset. +\bt should be able to do that... + +To that aim, we have to completely redefine the fields, entry-types, and +functions. Fields include names, addresses, phone numbers, e-mail +addresses,~... Here is an example of the output: + +\bigskip +\makeatletter +\font\lettre=cmssdc10 at 20pt +\def\at{@} +\ifx\sautepage\@undefined% +\def\sautepage{\null\cleardoublepage}\fi +\ifx\ecritlettre\@undefined% +\def\ecritlettre#1#2#3#4#5{ +\vbox to 0pt{ +\vspace{#3mm}\hspace{#1mm} +\smash{\colorbox[rgb]{.8,.8,.8}{\lettre \ \ +\vrule height #2mm depth #2mm width 0pt% +\vrule height 8mm depth 0mm width 0pt% +\hbox to #4mm{#5\hfil\null}% +}} +\vspace{-#3mm}\hspace{-#1mm}}}\fi +\small +\makeatother +\ecritlettre{157}{5}{10}{20}{mn} +\noindent +\begin{center} +\begin{tabular}{|p{.30\textwidth}|p{.4\textwidth}p{.18\textwidth}|} +\hline +{\vrule height 5mm width 0mm +{\normalsize \textsc{Markey} Nicolas +}} \vrule height 0mm depth 5mm width 0mm & +\vrule height 5mm width 0mm +LSV -- ENS Cachan\endgraf +61, avenue du Pr\'esident Wilson\endgraf +94235 \textsc{Cachan} C\'edex\vrule depth 3mm width 0mm +& \vrule height 5mm width 0mm +\Telefon \hfill01.47.40.75.32\endgraf +\Faxmachine \hfill01.47.40.24.64\endgraf +\\ & +\multicolumn{2}{l|}{\texttt{markey\at lsv.ens-cachan.fr}} \vrule depth 2mm + width 0mm +\\ \hline +\end{tabular} +\end{center} + +As in the previous example, I defined a \nient{config} entry-type in order to +define how letters should be grouped together,~... + +\mysection{Exporting, extracting and cleaning bibliographic entries} +\label{bibexport} + +It sometimes occurs that you have to extract a part of your bibliographic +database, for instance for sending it together with a \LaTeX~document. Several +tools already exist for doing this, but they generally can't handle crossrefs, +macros, string abbreviations,~... If fact, \bt can do this on its own: You +simply have to ask the bibliography style to format its output as a +\ext{bib} database (The result will be named \ext{bbl}, since there is no way +to tell \bt to write somewhere else). This technique has many advantages: It +ensures that the fields are treated exactly as \bt would treat them with +another style file; abbreviations are automatically expanded; It is easy to +extract all the references by one author (remember that names could be encoded +in many different manners inside a \ext{bib} database),~... +The package \verb+bibexport+ implements these techniques: +\url{http://www.ctan.org/tex-archive/biblio/bibtex/contrib/bibexport/} + +\mysection{Using several languages in one bibliography} + +Classical bibliography style only handle one language, generally English. +Handling several languages is quite tricky: First, when filling the \ext{bib} +file, you must ensure not to write language-dependant data. Namely, for +instance, months should be entered numerically. Moreover, \bt adds some words +while processing the entries, such as the ``and'' before the last author name. + +There are several solution for handling several languages: +\begin{itemize} +\item Designing one style file per language. This is somewhat tiring to do, + but not really complicated, and many such translations already exist. + + French styles are available on + \url{http://www.ctan.org/tex-archive/biblio/bibtex/contrib/bib-fr/}. In + those styles, I put every translated word at the beginning of the file, so + that it is easy to adapt the translation. + +\item Another solution is to replace language-dependant words with a \LaTeX + command. This is done in \textsf{babelbib} + (\url{http://www.ctan.org/tex-archive/biblio/bibtex/contrib/babelbib/}), + developed by Harald Harders. + Those style files require that you use the package \sty{babel}, and allows + you to define one language for each entry (and thus to use the right + hyphenation patterns). +\end{itemize} + + +\mysection{A glossary} + +A glossary is a dictionary defining technical terms that appear in a +document. Glossaries are generally made using the index mechanisms of \LaTeX. +But \bt can also do that (and even better than with \nicmd{index}, since it +could extract definitions from a general dictionary). Moreover, it is +possible to add reference to pages where the term is used by using the +\sty{backref} package. See for instance the package \sty{gloss}, developed by +Jose Luis Diaz de Arriba and Javier Bezos. diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.tex b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.tex new file mode 100644 index 00000000000..e7a7feac9b9 --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.tex @@ -0,0 +1,145 @@ +%% ttb_en.tex +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + +\def\ttbversion{1.3} +\def\ttbdate{16/10/2005} + +\documentclass{article} +\usepackage[T1]{fontenc} +\usepackage{ifpdf} +\ifpdf + \usepackage{lmodern} +\fi +\usepackage[latin1]{inputenc} +\usepackage[english]{babel} +\usepackage{moreverb} +\usepackage{url} +\usepackage[margin=3cm,bottom=2.5cm,top=3cm]{geometry} +\usepackage{multind} +\usepackage{array} +\usepackage{longtable} +\usepackage{marvosym} +\usepackage{color} +\usepackage{ttb_style} +\usepackage{xcolor} +\usepackage[colorlinks,breaklinks]{hyperref} +\makeatletter +\def\@citecolor{green!50!black} +\def\@linkcolor{red!80!black} +\makeatother +\usepackage{advdate} +\makeatletter +\let\save@ssect\@ssect +\usepackage{minitoc} +\expandafter\ifx\csname mtcskip\endcsname\relax + \def\mtcskip{} + \message{WARNING -- Please update your minitoc package.} +\fi + +\makeindex{latex} +\makeindex{bibtex} + + + +\begin{document} +\SetDate[\ttbdate] +\setcounter{parttocdepth}{3} +\doparttoc + +%% Title page +\begin{center} +{\Huge\bfseries Tame the BeaST} +\par\bigskip +{\large The B to X of \bt} +\par\bigskip +Nicolas \textsc{Markey} +\par +\url{markey@lsv.ens-cachan.fr} +\end{center} +\widowpenalty10000 +\vfil\vfil +\begin{center} +\fbox{Version \ttbversion{} -- \today} +\vfil +\begin{minipage}{.8\textwidth} +This \pageref{lastpage}-page tutorial presents and explains, as clearly and +exhaustively as possible, what \bt can do. +Indeed, \bt manuals, essentially two documents by its +author~\cite{btxdoc,btxhak} and chapters in some \LaTeX +books~\cite[...]{latex:dps,latex:lc,latex:lc2}, are often +short and incomplete. + +The capital letters ``BST'' in the title represent the standard extension of +\bt style files. ``B~to~X'' means that I tried to be as complete as +possible. Don't hesitate to e-mail me you \TeX{}nical as well as +(mis)spelling remarks. +\end{minipage} +\end{center} +\vfil\vfil +\begin{center} +\begin{minipage}{.8\textwidth} +\tableofcontents +\end{minipage} +\end{center} +\vfil + +\include{ttb_en.sec1} +\include{ttb_en.sec2} +\include{ttb_en.sec3} +\include{ttb_en.sec4} +\include{ttb_en.sec5} + + +%\nocite{merlin} +\def\addcontentsline#1#2#3{} +\cleardoublepage +\bibliographystyle{alpha} +\bibliography{local} +\printindex{latex}{\LaTeX} +\clearpage +\let\oldendindex\endtheindex +\def\copyright{\vfill +\null\hfill\begin{minipage}{.5\textwidth} +\setlength\parindent{0pt} +\obeyspaces +Copyright \textcopyright{} 2003-\the\year{} Nicolas \textsc{Markey} + +This work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3 +of this license or (at your option) any later version. +The latest version of this license is in\par +\hfil\url{http://www.latex-project.org/lppl.txt}\par +and version 1.3 or later is part of all distributions of LaTeX +version 2003/12/01 or later. + +This work has the LPPL status "maintained".\par +The current maintainer of this work is Nicolas \textsc{Markey}. + \end{minipage}} + + +\def\endtheindex{\label{lastpage}\copyright\oldendindex} +\printindex{bibtex}{\bt} +%\leavevmode\label{lastpage} + + + +\end{document} + diff --git a/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_style.sty b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_style.sty new file mode 100644 index 00000000000..7f9eef5356b --- /dev/null +++ b/Master/texmf-dist/doc/bibtex/tamethebeast/ttb_style.sty @@ -0,0 +1,130 @@ +%% ttb_style.sty +%% Copyright 2003-2005 Nicolas Markey +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2003/12/01 or later. +% +% This work has the LPPL maintenance status "maintained". +% The Current Maintainer of this work is Nicolas Markey +% +% This work consists of the files +% ttb_en.tex +% ttb_en.sec1.tex ttb_en.sec2.tex ttb_en.sec3.tex +% ttb_en.sec4.tex ttb_en.sec5.tex ttb_style.sty +% local.bib idxstyle.ist Makefile +% and the derived ttb_en.dvi, ttb_en.ps and ttb_en.pdf + + +\RequirePackage{xspace} +\RequirePackage{boxedminipage} + +%\let\nospaceTeX\TeX +%\def\TeX{\nospaceTeX\xspace} +\def\bt{Bib\TeX\xspace} +\let\nospaceLaTeX\LaTeX +\def\LaTeX{\nospaceLaTeX\xspace} +\def\gomo{\emph{grosso modo}\xspace} +\def\ie{ie.\xspace} +\def\cf{cf. } +\catcode`\*=0 +*catcode`*\=11 +*def*bs{\} +*catcode`*\=0 +\catcode`\*=12 +\def\at{@} +\catcode`\$=11 +\def\dol{$} +\catcode`\$=3 %$ +\def\cmd#1{\index{latex}{#1@\texttt{\protect\bs #1}}{\ttfamily \bs #1}\xspace} +\def\cmdat#1{\index{latex}{#1@\texttt{\protect\bs\protect\at #1}}{\ttfamily \bs\at #1}\xspace} +\def\env#1{\index{latex}{#1@\texttt{#1}}{\ttfamily #1}\xspace} +\def\ext#1{{\ttfamily .#1}\xspace} + +\def\sty{\@ifnextchar[{\@sty}{\@sty[sty]}} +\def\@sty[#1]#2{\index{latex}{#2@\textsf{#2.#1}}{\sffamily #2.#1}\xspace} + +\def\cls#1{\index{latex}{#1@\textsf{#1.cls}}{\sffamily #1.cls}\xspace} +\def\bst#1{\index{bibtex}{#1@\textsf{#1.bst}}{\sffamily #1.bst}\xspace} +\def\chp#1{\index{bibtex}{#1@\texttt{#1}}{\ttfamily #1}\xspace} +\def\ent#1{\index{bibtex}{#1@\protect\at #1}{\bfseries \at #1}\xspace} +\def\fn#1{\index{bibtex}{#1@\texttt{#1\protect\dol}}{\ttfamily #1\dol}\xspace} + +\def\el#1{$\cal #1$} +\def\eli#1#2{$\mathcal{#1}_{#2}$} + +\def\nicmd#1{{\ttfamily \bs #1}\xspace} +\def\nienv#1{{\ttfamily #1}\xspace} +\def\niext#1{{\ttfamily .#1}\xspace} +\def\nisty#1{{\sffamily #1.sty}\xspace} +\def\nicls#1{{\sffamily #1.cls}\xspace} +\def\nibst#1{{\sffamily #1.bst}\xspace} +\def\nichp#1{{\ttfamily #1}\xspace} +\def\nient#1{{\bfseries \at #1}\xspace} +\def\nifn#1{{\ttfamily #1\dol}\xspace} + +\newenvironment{myex}{\bigskip\par + \noindent\begin{boxedminipage}{\textwidth}}{% + \end{boxedminipage}\bigskip\par} +\newenvironment{myexv}{\bigskip\par + \noindent\begin{center}\begin{boxedminipage}{.8\textwidth}}{% + \end{boxedminipage}\end{center} + \bigskip\par} + +%\AtBeginDocument{% +\setcounter{tocdepth}{0}% +\def\thepart{\arabic{part}}% +\def\mypart{\clearpage\part}% +\def\@part[#1]#2{ \ifnum\c@secnumdepth>\m@ne\relax + \refstepcounter{part}% + \addcontentsline{toc}{part}{\thepart\hspace{1em}#1}% + \else + \addcontentsline{toc}{part}{#1}% + \fi + {\parindent \z@ \raggedleft + \interlinepenalty \@M + \normalfont + \ifnum \c@secnumdepth >\m@ne\relax + \Large\sffamily\bfseries \partname\nobreakspace\thepart + \par\nobreak + \fi + \huge \sffamily \bfseries #2% + \markboth{}{}\par}% + \nobreak + \vskip 12ex% + \@afterheading}% +\renewcommand*\l@part[2]{% + \ifnum \c@tocdepth >-2\relax + \addpenalty\@secpenalty + \addvspace{2.25em \@plus\p@}% + \setlength\@tempdima{3em}% + \begingroup + \parindent \z@ \rightskip \@pnumwidth + \parfillskip -\@pnumwidth + {\leavevmode + \large \sffamily #1 + \leaders\hbox{$\m@th + \mkern 2mu\hbox{\small.}\mkern 2mu$}\hfill + \hb@xt@\@pnumwidth{\hss #2}}\par + \nobreak + \if@compatibility + \global\@nobreaktrue + \everypar{\global\@nobreakfalse\everypar{}}% + \fi + \endgroup + \fi} +\let\mysection\section +\def\mysubsection{\subsection} +\def\mysubsubsection{\subsubsection} +\def\floatpagefraction{.8} + +\def\section{\let\@ssect\save@ssect\@startsection {section}{1}{\z@}% + {-3.5ex \@plus -1ex \@minus -.2ex}% + {2.3ex \@plus.2ex}% + {\normalfont\Large\bfseries}} +%} + |