diff options
author | Denis Bitouzé <dbitouze@wanadoo.fr> | 2021-02-25 18:23:07 +0000 |
---|---|---|
committer | Denis Bitouzé <dbitouze@wanadoo.fr> | 2021-02-25 18:23:07 +0000 |
commit | c6101f91d071883b48b1b4b51e5eba0f36d9a78d (patch) | |
tree | 1bf7f5a881d7a4f5c5bf59d0b2821943dd822372 /Build/extra/bibtex/btxhak.tex | |
parent | 07ee7222e389b0777456b427a55c22d0e6ffd267 (diff) |
French translation for tlmgr updated
git-svn-id: svn://tug.org/texlive/trunk@57912 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/extra/bibtex/btxhak.tex')
-rw-r--r-- | Build/extra/bibtex/btxhak.tex | 626 |
1 files changed, 0 insertions, 626 deletions
diff --git a/Build/extra/bibtex/btxhak.tex b/Build/extra/bibtex/btxhak.tex deleted file mode 100644 index e91c8a81ab4..00000000000 --- a/Build/extra/bibtex/btxhak.tex +++ /dev/null @@ -1,626 +0,0 @@ -% Copyright (C) 1988, 2010 Oren Patashnik. -% Unlimited copying and redistribution of this file are permitted if it -% is unmodified. Modifications (and their redistribution) are also -% permitted, as long as the resulting file is renamed. - -\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em - T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} - -\title{Designing B\kern-.05em{\large I}\kern-.025em{\large B}\kern-.08em\TeX\ - Styles} -\author{Oren Patashnik} -\date{February 8, 1988} - -\documentstyle{article} -\begin{document} - -\maketitle - -\setcounter{section}{4} -\section{Bibliography-style hacking} -\label{style} - -This document starts (and ends) with Section~\ref{style}, -because in reality it is the final section of ``\BibTeX ing''~\cite{btxdoc}, -the general documentation for \BibTeX. -But that document was meant for all \BibTeX\ users, -while this one is just for style designers, -so the two are physically separate. -Still, you should be completely familiar with ``\BibTeX ing''$\!$, -and all references in this document -to sections and section numbers -assume that the two documents are one. - -This section, -along with the standard-style documentation file \hbox{\tt btxbst.doc}, -should explain how to modify -existing style files and to produce new ones. -If you're a serious style hacker you should be familiar -with van~Leunen~\cite{van-leunen} for points of style, -with Lamport~\cite{latex} and Knuth~\cite{texbook} for formatting matters, -and perhaps with {\em Scribe\/}~\cite{scribe} for compatibility details. -And while you're at it, if you don't read the great little book by Strunk and -White~\cite{strunk-and-white}, you should at least look at its -entries in the database and the reference list -to see how \BibTeX\ handles multiple names. - -To create a new style, -it's best to start with an existing style that's close to yours, -and then modify that. -This is true even if you're simply updating an old style -for \BibTeX\ version 0.99 -(I've updated four nonstandard styles, -so I say this with some experience). -If you want to insert into a new style -some function you'd written for an old (version 0.98i) style, -keep in mind that the order of the arguments to -the assignment ({\tt :=}) function has been reversed. -When you're finished with your style, -you may want to try running it on the entire \hbox{\tt XAMPL.BIB} database -to make sure it handles all the standard entry types. - -If you find any bugs in the standard styles, -or if there are things you'd like to do -with bibliography-style files but can't, -please complain to Oren Patashnik. - - -\subsection{General description} - -You write bibliography styles in a postfix stack language. It's -not too hard to figure out how by looking at the standard-style documentation, -but this description fills in a few details (it will fill in more -details if there's a demand for it). - -Basically the style file is a program, written in an unnamed language, that -tells \BibTeX\ how to format the entries that will go in the reference list -(henceforth ``the entries'' will be ``the entry list'' -or simply ``the list''$\!$, context permitting). -This programming language has ten commands, described in the next subsection. -These commands manipulate the language's objects: -constants, variables, functions, the stack, and the entry list. -(Warning: The terminology in this documentation, -chosen for ease of explanation, is slightly different from \BibTeX's. -For example, this documentation's ``variables'' and ``functions'' -are both ``functions'' to \BibTeX. -Keep this in mind when interpreting \BibTeX's error messages.) - -There are two types of functions: {\it built-in\/} ones that \BibTeX\ provides -(these are described in Section~\ref{built-in-fns}), and ones you define -using either the \hbox{\tt MACRO} or \hbox{\tt FUNCTION} command. - -Your most time-consuming task, as a style designer, -will be creating or modifying functions -using the \hbox{\tt FUNCTION} command -(actually, becoming familiar with the references listed above will be -more time consuming, but assume for the moment that that's done). - -Let's look at a sample function fragment. -Suppose you have a string variable named \hbox{\tt label} -and an integer variable named \hbox{\tt lab.width}, -and suppose you want to append the character `{\tt a}' to \hbox{\tt label} -and to increment \hbox{\tt lab.width}: -\begin{verbatim} - . . . - label "a" * 'label := % label := label * "a" - lab.width #1 + 'lab.width := % lab.width := lab.width + 1 - . . . -\end{verbatim} -In the first line, -\hbox{\tt label} pushes that variable's value onto the stack. -Next, the {\tt "a"} pushes the string constant `{\tt a}' onto the stack. -Then the built-in function {\tt *} pops the top two strings and -pushes their concatenation. -The \hbox{\tt 'label} pushes that variable's name onto the stack. -And finally, the built-in function {\tt :=} pops -the variable name and the concatenation and performs the assignment. -\BibTeX\ treats the stuff following the {\tt \%} as a comment -in the style file. -The second line is similar except that it uses {\tt \#1}, -with no spaces intervening between the `{\tt \#}' and the `{\tt 1}'$\!$, -to push this integer constant. - -The nonnull spacing here is arbitrary: multiple spaces, tabs, or newlines -are equivalent to a single one (except that you're probably better off -not having blank lines within commands, as explained shortly). - -For string constants, absolutely any printing character -is legal between two consecutive double quotes, but \BibTeX\ here -(and only here) treats upper- and lower-case equivalents as different. -Furthermore, spacing {\em is\/} relevant within a string constant, -and you mustn't split a string constant across lines -(that is, the beginning and ending double quotes must be on the same line). - -Variable and function names may not begin with a numeral and -may not contain any of the ten restricted characters -on page~143 of the \LaTeX\ book, -but may otherwise contain any printing characters. -Also, \BibTeX\ considers upper- and lower-case equivalents to be the same. - -Integers and strings are the only value types for constants and variables -(booleans are implemented simply as 0-or-1 integers). -There are three kinds of variables: -\begin{description} - -\item[global variables\hfill] These are either integer- or string-valued, -declared using an \hbox{\tt INTEGERS} or \hbox{\tt STRINGS} command. - -\item[entry variables\hfill] These are either integer- or string-valued, -declared using the \hbox{\tt ENTRY} command. -Each has a value for each entry on the list -(example: a variable \hbox{\tt label} might store -the label string you'll use for the entry). - -\item[fields\hfill] These are string-valued, read-only variables -that store the information from the database file; -their values are set by the \hbox{\tt READ} command. -As with entry variables, each has a value for each entry. -\end{description} - - -\subsection{Commands} - -There are ten style-file commands: -Five (\hbox{\tt ENTRY}, \hbox{\tt FUNCTION}, \hbox{\tt INTEGERS}, -\hbox{\tt MACRO}, and \hbox{\tt STRINGS}) -declare and define variables and functions; -one (\hbox{\tt READ}) reads in the database information; -and four (\hbox{\tt EXECUTE}, \hbox{\tt ITERATE}, \hbox{\tt REVERSE}, -and \hbox{\tt SORT}) manipulate the entries and produce output. -Although the command names appear here in upper case, -\BibTeX\ ignores case differences. - -Some restrictions: -There must be exactly one \hbox{\tt ENTRY} and one \hbox{\tt READ} command; -the \hbox{\tt ENTRY} command, all \hbox{\tt MACRO} commands, -and certain \hbox{\tt FUNCTION} commands -(see next subsection's description of \hbox{\tt call.type\$}) -must precede the \hbox{\tt READ} command; -and the \hbox{\tt READ} command must precede the four that -manipulate the entries and produce output. - -Also it's best (but not essential) to leave at least one blank line -between commands and to leave no blank lines within a command; -this helps \BibTeX\ recover from any syntax errors you make. - -You must enclose each argument of every command in braces. -Look at the standard-style documentation -for syntactic issues not described in this section. -Here are the ten commands: -\begin{description} - -\item[\hbox{\tt ENTRY}\hfill] -Declares the fields and entry variables. -It has three arguments, each a (possibly empty) list of variable names. -The three lists are of: -fields, integer entry variables, and string entry variables. -There is an additional field that \BibTeX\ automatically -declares, \hbox{\tt crossref}, used for cross referencing. -And there is an additional string entry variable automatically declared, -\hbox{\tt sort.key\$}, used by the \hbox{\tt SORT} command. -Each of these variables has a value for each entry on the list. - -\item[\hbox{\tt EXECUTE}\hfill] -Executes a single function. -It has one argument, the function name. - -\item[\hbox{\tt FUNCTION}\hfill] -Defines a new function. -It has two arguments; the first is the function's name and the -second is its definition. -You must define a function before using it; -recursive functions are thus illegal. - -\item[\hbox{\tt INTEGERS}\hfill] -Declares global integer variables. -It has one argument, a list of variable names. -There are two such automatically-declared variables, -\hbox{\tt entry.max\$} and \hbox{\tt global.max\$}, -used for limiting the lengths of string variables. -You may have any number of these commands, but a variable's declaration -must precede its use. - -\item[\hbox{\tt ITERATE}\hfill] -Executes a single function, once -for each entry in the list, in the list's current order -(initially the list is in citation order, but the \hbox{\tt SORT} -command may change this). -It has one argument, the function name. - -\item[\hbox{\tt MACRO}\hfill] -Defines a string macro. -It has two arguments; the first is the macro's name, which is treated like -any other variable or function name, -and the second is its definition, which must be double-quote-delimited. -You must have one for each three-letter month abbreviation; -in addition, you should have one for common journal names. -The user's database may override any definition you define using this command. -If you want to define a string the user can't touch, -use the \hbox{\tt FUNCTION} command, which has a compatible syntax. - -\item[\hbox{\tt READ}\hfill] -Dredges up from the database file -the field values for each entry in the list. -It has no arguments. -If a database entry doesn't have a value for a field -(and probably no database entry will have a value for every field), -that field variable is marked as missing for the entry. - -\item[\hbox{\tt REVERSE}\hfill] -Exactly the same as the -\hbox{\tt ITERATE} command except that it executes the function -on the entry list in reverse order. - -\item[\hbox{\tt SORT}\hfill] -Sorts the entry list using -the values of the string entry variable \hbox{\tt sort.key\$}. -It has no arguments. - -\item[\hbox{\tt STRINGS}\hfill] -Declares global string variables. -It has one argument, a list of variable names. -You may have any number of these commands, but a variable's declaration -must precede its use. -\end{description} - - -\subsection{The built-in functions} -\label{built-in-fns} - -Before we get to the built-in functions, -a few words about some other built-in objects. -There is one built-in string entry variable, \hbox{\tt sort.key\$}, -which the style program must set if the style is to do sorting. -There is one built-in field, \hbox{\tt crossref}, -used for the cross referencing feature -described in Section~4. -And there are two built-in integer global variables, -\hbox{\tt entry.max\$} and \hbox{\tt global.max\$}, -which are set by default to some internal \BibTeX\ constants; -you should truncate strings to these lengths before -you assign to string variables, -so as to not generate any \BibTeX\ warning messages. - -There are currently 37 built-in functions. -Every built-in function with a letter in its name ends with a `{\tt \$}'$\!$. -In what follows, ``first''$\!$, ``second''$\!$, -and so on refer to the order popped. -A ``literal'' is an element on the stack, and it will be either -an integer value, a string value, a variable or function name, -or a special value denoting a missing field. -If any popped literal has an incorrect type, \BibTeX\ complains and pushes -the integer 0 or the null string, depending on whether the function -was supposed to push an integer or string. -\begin{description} - -\item[\hbox{\tt >}\hfill] -Pops the top two (integer) literals, -compares them, and pushes the integer 1 if the second is greater than -the first, 0 otherwise. - -\item[\hbox{\tt <}\hfill] -Analogous. - -\item[\hbox{\tt =}\hfill] -Pops the top two (both integer or both string) literals, -compares them, -and pushes the integer 1 if they're equal, 0 otherwise. - -\item[\hbox{\tt +}\hfill] -Pops the top two (integer) literals and pushes their sum. - -\item[\hbox{\tt -}\hfill] -Pops the top two (integer) literals and pushes their difference -(the first subtracted from the second). - -\item[\hbox{\tt *}\hfill] -Pops the top two (string) literals, -concatenates them (in reverse order, that is, the order in which -pushed), and pushes the resulting string. - -\item[\hbox{\tt :=}\hfill] -Pops the top two literals and assigns -to the first (which must be a global or entry variable) -the value of the second. - -\item[\hbox{\tt add.period\$}\hfill] -Pops the top (string) literal, -adds a `{\tt .}' to it if the last non`{\tt \}}' character -isn't a `{\tt .}'$\!$, `{\tt ?}', or `{\tt !}'$\!$, -and pushes this resulting string. - -\item[\hbox{\tt call.type\$}\hfill] -Executes the function whose name is the entry type of an entry. -For example if an entry is of type {\tt book}, this function executes -the {\tt book} function. -When given as an argument to the \hbox{\tt ITERATE} command, -\hbox{\tt call.type\$} actually produces the output for the entries. -For an entry with an unknown type, -it executes the function \hbox{\tt default.type}. -Thus you should define (before the \hbox{\tt READ} command) one function -for each standard entry type as well as a \hbox{\tt default.type} function. - -\item[\hbox{\tt change.case\$}\hfill] -Pops the top two (string) literals; -it changes the case of the second according to the -specifications of the first, as follows. (Note: The word `letters' in -the next sentence refers only to those at brace-level~0, the top-most -brace level; no other characters are changed, except perhaps for -``special characters''$\!$, described in Section~4.) -If the first literal is the -string~`{\tt t}'$\!$, it converts to lower case all letters except the very -first character in the string, which it leaves alone, and except the -first character following any colon and then nonnull white space, -which it also leaves alone; if it's the string~`{\tt l}'$\!$, it converts all -letters to lower case; and if it's the string~`{\tt u}'$\!$, it converts all -letters to upper case. -It then pushes this resulting string. If either -type is incorrect, it complains and pushes the null string; however, -if both types are correct but the specification string (i.e., the -first string) isn't one of the legal ones, it merely pushes the second -back onto the stack, after complaining. (Another note: It ignores -case differences in the specification string; for example, the strings -{\tt t} and {\tt T} are equivalent for the purposes of this built-in -function.) - -\item[\hbox{\tt chr.to.int\$}\hfill] -Pops the top (string) literal, -makes sure it's a single character, converts it to the -corresponding ASCII integer, and pushes this integer. - -\item[\hbox{\tt cite\$}\hfill] -Pushes the string that was the -\hbox{\verb|\cite|}-command argument for this entry. - -\item[\hbox{\tt duplicate\$}\hfill] -Pops the top literal from the stack and pushes two copies of it. - -\item[\hbox{\tt empty\$}\hfill] -Pops the top literal and pushes -the integer 1 if it's a missing field or a string having no -non-white-space characters, 0 otherwise. - -\item[\hbox{\tt format.name\$}\hfill] -Pops the top three literals -(they are a string, an integer, and a string literal). -The last string literal represents a name list (each name -corresponding to a person), the integer literal specifies which name -to pick from this list, and the first string literal specifies how to -format this name, as explained in the next subsection. -Finally, this function pushes the formatted name. - -\item[\hbox{\tt if\$}\hfill] -Pops the top three literals (they -are two function literals and an integer literal, in that order); -if the integer is greater than 0, it executes the second literal, -else it executes the first. - -\item[\hbox{\tt int.to.chr\$}\hfill] -Pops the top (integer) literal, -interpreted as the ASCII integer value of a single character, -converts it to the corresponding single-character string, and pushes -this string. - -\item[\hbox{\tt int.to.str\$}\hfill] -Pops the top (integer) literal, -converts it to its (unique) string equivalent, and pushes this string. - -\item[\hbox{\tt missing\$}\hfill] -Pops the top literal and -pushes the integer 1 if it's a missing field, 0~otherwise. - -\item[\hbox{\tt newline\$}\hfill] -Writes onto the {\tt bbl} file -what's accumulated in the output buffer. -It writes a blank line if and only if the output buffer is empty. -Since \hbox{\tt write\$} does reasonable line breaking, you should use -this function only when you want a blank line or an explicit line break. - -\item[\hbox{\tt num.names\$}\hfill] -Pops the top (string) literal -and pushes the number of names the string represents---one plus -the number of occurrences of the substring ``and'' (ignoring case differences) -surrounded by nonnull white-space at the top brace level. - -\item[\hbox{\tt pop\$}\hfill] -Pops the top of the stack but -doesn't print it; this gets rid of an unwanted stack literal. - -\item[\hbox{\tt preamble\$}\hfill] -Pushes onto the stack the concatenation of all the -\hbox{\tt @PREAMBLE} strings read from the database files. - -\item[\hbox{\tt purify\$}\hfill] -Pops the top (string) literal, -removes nonalphanumeric characters except for white-space characters and -hyphens and ties (these all get converted to a space), removes -certain alphabetic characters contained in the control sequences -associated with a ``special character''$\!$, and pushes the resulting string. - -\item[\hbox{\tt quote\$}\hfill] -Pushes the string consisting of the double-quote character. - -\item[\hbox{\tt skip\$}\hfill] -Is a no-op. - -\item[\hbox{\tt stack\$}\hfill] -Pops and prints the whole stack; -it's meant to be used for style designers while debugging. - -\item[\hbox{\tt substring\$}\hfill] -Pops the top three literals -(they are the two integers literals {\it len\/} and {\it start}, and a -string literal, in that order). -It pushes the substring of the (at most) {\it len\/} consecutive characters -starting at the {\it start\/}th character (assuming 1-based indexing) -if {\it start\/} is positive, and ending at the $-${\it start\/}th character -from the end if {\it start\/} is negative -(where the first character from the end is the last character). - -\item[\hbox{\tt swap\$}\hfill] -Swaps the top two literals on the stack. - -\item[\hbox{\tt text.length\$}\hfill] -Pops the top (string) literal, -and pushes the number of text characters it contains, where an -accented character (more precisely, a ``special character''$\!$, -defined in Section~4) -counts as a single text character, even if it's missing -its matching right brace, and where braces don't count as -text characters. - -\item[\hbox{\tt text.prefix\$}\hfill] -Pops the top two literals -(the integer literal {\it len\/} and a string literal, in that order). -It pushes the substring of the (at most) {\it len\/} consecutive text -characters starting from the beginning of the string. This function -is similar to \hbox{\tt substring\$}, but this one considers -a ``special character''$\!$, even if -it's missing its matching right brace, to be a single text character -(rather than however many ASCII characters it actually comprises), -and this function doesn't consider braces to be text characters; -furthermore, this function appends any needed matching right braces. - -\item[\hbox{\tt top\$}\hfill] -Pops and prints the top of the stack on the terminal and log file. -It's useful for debugging. - -\item[\hbox{\tt type\$}\hfill] -Pushes the current entry's type (book, article, etc.), -but pushes the null string -if the type is either unknown or undefined. - -\item[\hbox{\tt warning\$}\hfill] -Pops the top (string) literal -and prints it following a warning message. -This also increments a count of the number of warning messages issued. - -\item[\hbox{\tt while\$}\hfill] -Pops the top two (function) literals, -and keeps executing the second as long as the (integer) -literal left on the stack by executing the first is greater than 0. - -\item[\hbox{\tt width\$}\hfill] -Pops the top (string) literal -and pushes the integer that represents its width in some relative units -(currently, hundredths of a point, as specified by the June 1987 version -of the $cmr10$ font; the only white-space character with nonzero width -is the space). -This function takes the literal literally; -that is, it assumes each character in the string is to be printed as -is, regardless of whether the character has a special meaning to \TeX, -except that ``special characters'' (even without their right braces) are -handled specially. -This is meant to be used for comparing widths of label strings. - -\item[\hbox{\tt write\$}\hfill] -Pops the top (string) literal -and writes it on the output buffer (which will result in -stuff being written onto the {\tt bbl} file when the buffer fills up). - -\end{description} - -Note that the built-in functions \hbox{\tt while\$} and \hbox{\tt if\$} -require two function literals on the stack. -You get them there either by immediately preceding the name of a function -by a single quote, or, if you don't feel like defining a new function with -the \hbox{\tt FUNCTION} command, -by simply giving its definition (that is, giving what would be the second -argument to the \hbox{\tt FUNCTION} command, including the surrounding braces). -For example the following function fragment appends the character `{\tt a}' -if the string variable named \hbox{\tt label} is nonnull: -\begin{verbatim} - . . . - label "" = - 'skip$ - { label "a" * 'label := } - if$ - . . . -\end{verbatim} -A function whose name you quote needn't be built in -like \hbox{\tt skip\$} above---it may, for example, -be a field name or a function you've defined earlier. - - -\subsection{Name formatting} - -What's in a name? -Section~4 pretty much describes this. -Each name consists of four parts: First, von, Last, and Jr; -each consists of a list of name-tokens, -and any list but Last's may be empty for a nonnull name. -This subsection describes the format string you must supply to -the built-in function \hbox{\tt format.name\$}. - -Let's look at an example of a very long name. -Suppose a database entry~\cite{prime-number-theorem} has the field -\begin{verbatim} - author = "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin" -\end{verbatim} -and suppose you want this formatted ``last name comma initials''$\!$. -If you use the format string -\begin{verbatim} - "{vv~}{ll}{, jj}{, f}?" -\end{verbatim} -\BibTeX\ will produce -\begin{verbatim} - de~la Vall{\'e}e~Poussin, C.~L. X.~J? -\end{verbatim} -as the formatted string. - -Let's look at this example in detail. -There are four brace-level~1 {\em pieces\/} to this format string, -one for each part of a name. -If the corresponding part of a name isn't present (the Jr part for this name), -everything in that piece is ignored. -Anything at brace-level~0 is output verbatim -(the presumed typo `{\tt ?}' for this name is at brace-level~0), -but you probably won't use this feature much. - -Within each piece a double letter tells \BibTeX\ to use whole tokens, and -a single letter, to abbreviate them (these letters must be at brace-level~1); -everything else within the piece is used verbatim -(well, almost everything---read on). -The tie at the end of the von part (in \hbox{\verb|{vv~}|}) -is a discretionary tie---\BibTeX\ will output a tie at that point -if it thinks there's a need for one; -otherwise it will output a space. -If you really, really, want a tie there, -regardless of what \BibTeX\ thinks, use two of them -(only one will be output); that is, use \hbox{\verb|{vv~~}|}. -A tie is discretionary only if it's the last character of the piece; -anywhere else it's treated as an ordinary character. - -\BibTeX\ puts default strings {\em between\/} tokens of a name part: -For whole tokens it uses either a space or a tie, -depending on which one it thinks is best, -and for abbreviated tokens it uses a period followed by -either a space or a tie. -However it doesn't use this default string after the last token in a list; -hence there's no period following the `J' for our example. -You should have used -\begin{verbatim} - "{vv~}{ll}{, jj}{, f.}" -\end{verbatim} -to get \BibTeX\ to produce the same formatted string but with the question -mark replaced by a period. -Note that the period should go inside the First-name piece, -rather than where the question mark was, in case a name has no First part. - -If you want to override \BibTeX's default between-token strings, you -must explicitly specify a string. -For example suppose you want a label to contain the first letter from each -token in the von and Last parts, with no spaces; -you should use the format string -\begin{verbatim} - "{v{}}{l{}}" -\end{verbatim} -so that \BibTeX\ will produce `{\tt dlVP}' as the formatted string. -You must give a string for each piece whose default you want overridden -(the example here uses the null string for both pieces), and this string -must immediately follow either the single or double letter for the piece. -You may not have any other letters at brace-level~1 in the format string. - -\bibliography{btxdoc} -\bibliographystyle{plain} -\end{document} |