diff options
Diffstat (limited to 'Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec4.tex')
| -rw-r--r-- | Master/texmf-dist/doc/bibtex/tamethebeast/ttb_en.sec4.tex | 841 |
1 files changed, 841 insertions, 0 deletions
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). |