


BIBLABEL(1)		  User Commands		      BIBLABEL(1)



NAME
     biblabel -	generated standardized BibTeX citation labels

SYNOPSIS
     biblabel [	  - f  in-use-file  ]  [   - i	ignore-file  ]	[
     BibTeXfile(s) ]  >outfile

DESCRIPTION
     biblabel filters  a  BibTeX  bibliography,	 or  bibliography
     fragment,	on  its	standard input,	or one or more bibliogra-
     phies named on the	command	line, and prints on standard out-
     put  lines	 containing pairs of old and new citation labels,
     suitable for input	to the companion program, citesub(1).

     The citation label	is formed by these rules, easily applica-
     ble by a human, or	by a computer program like this	one:

	  (1)  Take the	first author's last name, dropping  apos-
	       trophes,	Jr/Sr/generation numbers, and eliminating
	       accents	 (e.g.	 J{\"a}nsch   ->   Jaensch,   and
	       Jind\v{r}ich   ->  Jindrich),  using  multi-letter
	       transliterations	  if   that   is    conventional.
	       Hyphenated  names, like Baeza-Yates, are	preserved
	       in full.

	  (2)  Append a	colon.

	  (3)  Append the four-digit year of publication.

	  (4)  Append another colon.

	  (5)  Pick the	first 3	important words	in the title that
	       begin with a letter, excluding articles and prepo-
	       sitions and TeX math mode (e.g.	On ${C}^1$ inter-
	       polating	 hierarchical  spline  bases  reduces  to
	       IHS), and append	that.  If there	are fewer than	3
	       important words,	then use a shorter string.

	  (6)  If the resulting	citation label is already in use,
	       add a letter a, b, c,

     This will produce a label like Smith:1994:ABC.

     The reason	for including a	four-digit year	is that	the  mil-
     lenium change is near, and	we expect bibliographies to be in
     use for many years	hence.	Also, some bibliographies may  be
     historical,  with	entries	 dating	 back  hundreds	of years.
     Using a four-digit	year will keep sorts of	otherwise identi-
     cal keys in chronological order, and putting the year before
     the key derived from the title will  facilitate  sorting  by
     year.




Version	0.02	  Last change: 16 October 1996			1






BIBLABEL(1)		  User Commands		      BIBLABEL(1)



     Because any change	in citation labels must	be accompanied by
     a change in citations in all documents that use the bibliog-
     raphy, it is not sufficient to just produce a new bibliogra-
     phy  file	with changed labels.  Consequently, the	output of
     biblabel is expected to be	saved, and subsequently	used with
     citesub(1)	 to  actually  carry  out the substitutions effi-
     ciently.  If no documents other than the  bibliography  file
     itself  need to be	changed, then a	simple UNIX or IBM PC DOS
     pipeline of the form

     biblabel <foo.bib | citesub -f - >foo.bib-new

     will produce a new	bibliography file with all of  the  cita-
     tion labels changed to the	new standardized form.

     To	avoid confusion	between	labels with common prefixes, such
     as	 Smith80  and Smith80a,	citesub(1) will	check for leading
     context of	a left brace, quote, comma, whitespace,	or begin-
     ning  of  line and	trailing context of a right brace, comma,
     quote, percent, whitespace, or end	of line	so  as	to  match
     these styles:

	  @Book{Smith:1980:ABC,

	  crossref = "Smith:1980:ABC",

	  crossref = {Smith:1980:ABC},

	  \cite{Smith:1980:ABC}

	  \cite{Smith:1980:ABC,Jones:1994:DEF}

	  \cite{%
		 Smith:1980:ABC,%
		 Jones:1994:DEF%
	  }

OPTIONS
     Except for	the options  described	below,	all  command-line
     words are assumed to be input files.  Should such a filename
     begin with	a hyphen, it must be disguised by a leading abso-
     lute  or relative directory path, e.g.  /tmp/-foo.bib or ./-
     foo.bib.

     -f	labels-in-use-file   This option specifies the name of	a
			    file   containing	citation   labels
			    already in use, one	label  per  line.
			    This  can  be  used	 in  a multi-file
			    bibliography collection to	guarantee
			    unique  citation  labels  across  the
			    entire collection.




Version	0.02	  Last change: 16 October 1996			2






BIBLABEL(1)		  User Commands		      BIBLABEL(1)



     -i	ignore-file	     This option specifies the name of	a
			    file  containing  additional words to
			    be added to	the internal ignore list.
			    Such  words	 are ignored when the up-
			    to-three-letter title abbreviation is
			    constructed.

WARNING	AND ERROR MESSAGES
     biblabel will issue warning messages in the following cases:

     o	Duplicate citation labels in the input file(s).	This con-
       dition  will definitely cause erroneous substitutions when
       citesub(1) is used, so the error	 must  be  corrected  and
       biblabel	run again on the corrected file.

     o	Incomplete accent removal. biblabel contains many heuris-
       tic reductions of accented letters to unaccented	ones, but
       occasionally an accent combination is met that  it  cannot
       recognize,  and the result is that the generated	label may
       not be exactly what was intended.  Only rarely will manual
       editing of the output substitution file be necessary.

     o	Year out of the	range 1000 ...	2099.  A  valid	 year  is
       required	 for  generation  of a citation	label; an out-of-
       range, or omitted, year will be represented by 19xx in the
       generated citation label.

CAVEATS
     BibTeX has	loose syntactical requirements that  the  current
     simple implementation of biblabel does not	support.  In par-
     ticular, outer parentheses	may  not  be  used  in	place  of
     braces  following ``@keyword'' patterns.  If you have such	a
     file, you can use bibclean(1) to prettyprint it into a  form
     that biblabel can handle successfully.

SEE ALSO
     bibcheck(1),   bibclean(1),    bibextract(1),    bibjoin(1),
     biblex(1),	 biborder(1), bibparse(1), bibsort(1), bibtex(1),
     bibunlex(1), citesub(1).

AUTHOR
     Nelson H. F. Beebe, Ph.D.
     Center for	Scientific Computing
     Department	of Mathematics
     University	of Utah
     Salt Lake City, UT	84112
     Tel: +1 801 581 5254
     FAX: +1 801 581 4148
     Email: <beebe@math.utah.edu>






Version	0.02	  Last change: 16 October 1996			3



