.TH REFER2BIBTEX 1 "1993 May 14" "" \" -*- nroff -*- .SH NAME refer2bibtex \- convert refer bibliographies to BibTeX format .SH SYNOPSIS .B r2b [\-n] [\-ibm] [\-eqn] [\-q] [\-qq] [\-tib] [\-deroff-only] [\-overstrike] [\-noname-conversion] [\-reverse-author] [\-nocap-protect] [\-cap-protect] [\-ignore-label] [\-noprotect] [ .I files ] .SH DESCRIPTION .BR refer2bibtex converts bibliographies in UNIX refer format to BibTeX format. It will also convert bibliographies in tib format to BibTeX. It can also be used to convert general text with refer character commands into text with TeX commands (it cannot handle all of the troff formatting commands, so cannot be used as a general purpose troff to TeX converter), or to remove IBM graphic characters from text. .PP All options can be specified with the first three characters (i.e. specifying .I \-der is the same as .I \-deroff-only ). .SS OPTIONS .TP .I "\-n" Do not convert troff characters to TeX. All backslash-escaped characters will be passed through. This is implied by using the .I \-tib option. .TP .I "\-ibm" Convert IBM graphics characters. IBM graphics characters are characters with ASCII codes above 128. They are first converted to refer, so if the .I \-n or .I \-tib option is selected, they are converted to refer, and to TeX otherwise. .TP .I "\-eqn" Certain eqn constructs are handled. It is assumed that "@" will be used for the eqn delimiters. The eqn support is very minimal. .TP .I "\-q" Warnings are not printed to the standard error. .TP .I "\-qq" As with the .I \-q option, warnings are not printed to the standard error. In addition, only one line of summary information will be printed. .TP .I "\-tib" Instead of converting refer format, convert tib format. Tib format is essentially refer syle bibliography layout, but using TeX for special characters instead of troff. tib also defines more fields (some of the more exotic of which will not be converted), defines some fonts, and has a macro system. Some macros are built-in, but most will not be converted. The .I \-tib option implies .I \-n \-noprotect .TP .I "\-deroff-only" This option lets the program be used for doing character conversions rather than bibliography format conversions. No attempt is made to understand fields. For each line, IBM graphics conversion is done if requested, then troff to TeX (or tib macros to TeX) conversion is done. .TP .I "\-overstrike" European style troff characters are allowed. This is sometimes used as a shortcut or "dead-key" method for specifying umlauts. troff codes such as "\\:o" are accepted as if they were "\\(:o". .TP .I "\-noname-conversion" By default, the program will attempt to parse name strings. It uses a rather involved heuristic to determine if it has been passed one name or many, and to split the name(s) it has been passed into parts. These parts are then assembled into correct BibTeX name format. The name parsing routine is actually fairly robust, but if your names are already in BibTeX format (watch out for trailers such as Jr, Sr, III, etc) or the name-parsing routine is failing, this option can be used to make the program leave name fields alone. .TP .I "\-reverse-author" Author names are assumed to be in the format .I "Last, First, Jr." and will be converted to .I "First Last, Jr." format before conversion to BibTeX name format begins. .TP .I "\-nocap-protect" By default, the program protects sequences of multiple capital letters, and single captical letters (not part of a word). BibTeX uses a style file to determine the "correct" capitalization for the type of entry, which usually means that titles will be in lower case. Protecting capitals will make BibTeX leave the capitalization alone, which is what is usually desired for words like "NASA", "U.S.A.", "GIS", etc. This option turns off all protection. Protection only occurs in "%T" fields. .TP .I "\-cap-protect" This option protects all capital letters. Capitalization in the final TeX document should match the capitalization in the refer title. This option is not recommended, as it defeats the purpose of having BibTeX styles be smart. Protection only occurs in "%T" fields. .TP .I "\-ignore-label" By default, if a "%L" field is present, it will be used as the key for the BibTeX entry. If this option is specified, the "%L" field will be ignored, and labels will be made from the author and year. .TP .I "\-noprotect" By default, special TeX characters such as "%", "&", "#", etc. are converted to their literal equivalents. This guarantees that the resulting BibTeX file will be able to pass through TeX without problems, and is normally what is desired. If your text uses these characters in valid TeX fashion, this option will stop the program from making them into literal characters. .SH EXAMPLES To do a standard conversion of refer to BibTeX: .PP .RS 0.5i r2b example.ref > example.bib .RE .PP To convert tib to BibTeX: .PP .RS 0.5i r2b example.tib > example.bib .RE .PP To convert refer to tib: .PP .RS 0.5i r2b \-der example.ref > example.tib .RE .PP To convert all IBM graphics characters in a file to troff characters: .PP .RS 0.5i r2b \-n \-der \-ibm example > example.ref .RE .SH HEURISTICS Entry type .PP Names .PP Dates .PP TeX to Troff .SH "SEE ALSO" ref2bib, refer-to-bibtex.el, refconvert, r2bib, ref2bib.p, ttb .PP tex2refer, bib2refer .SH INCOMPATIBILITIES Point size changing less than -4 or more than +4 will not work. Changes of this magnitude are extremely rare however. .PP Complex font changes can confuse the program. If \\fP is used to return to the previous font, it has a much better chance of success. Overall the algorithm is fairly robust and handles a variety of situations. .PP Some of the IBM graphics characters are missing: 221, 222, 236, and 237. .PP tib macro conversion is skimpy, but full conversion requires reading multiple very large databases. .PP While label fields will be unique within any one run of refer2bibtex, there is no way to make it not use labels defined in a previous run. This means that if files are split up, there can be duplicate keys created in different files, which will create problems if both files are used in TeX at the same time. .PP eqn support is very minimal and uses hard-coded macros. .PP Some troff specials are not finished. "\\(L=", "\\(bs", "\\(ho", "\\(lh" are not done. .PP Some troff specials are defined as different characters in different implementations of troff. When this happened, I chose one at random. .SH BUGS The above "incompatibilities" can be considered bugs by anyone who needs to do something that isn't supported. .SH "FUTURE WORK" A flag to handle names in "last, first" format. EndNote Plus exports refer format with names like this. Strange, since refer doesn't like names in this format! .SH AUTHOR Dana Jacobsen wrote the program. He can be reached at "jacobsd@solar.cor2.epa.gov" or "jacobsd@cs.orst.edu". .PP The latest version of refer2bibtex can be retrieved by anonymous ftp to cerberus.cor.epa.gov in /pub/bibtools/r2b. .