BibTool Manual Reference Manual Command Line Usage and Resource Files

Command Line Usage and Resource Files

BibTool can be controlled either by arguments given in the command line or by commands given in a file (or both). Those command files are called resource files. If BibTool is installed correctly you should have the executable command bibtool (maybe with an additional extension). Depending on your computer and operating system you can start BibTool in different ways. This can be done either by issuing a command in a command line interpreter (shell), by clicking an icon, or by selecting a menu item. In the following description we will concentrate on the use in a UN*X like shell. There you can type simply

bibtool

Now BibTool is waiting for your input. As you type BibTool reads what you type. This input is interpreted as data conforming to BibTeX file rules. The result is printed when BibTool is finished. You can terminate the reading phase with your End-Of-File character (e.g. Control-D on UN*X, or Control-Z on MS-D*S).

This application in itself is rather uninteresting. Thus we come to the possibility to give arguments to BibTool. The simplest argument is -h as in

bibtool -h

This command should print the version number and a short description of the command line arguments to the screen.

The next application is the specification of resources. Resource files can be given in the command line after the flag -r.

bibtool -r resource_file

In this way an arbitrary number of resource files can be given. Those resource files are read in turn and the commands contained are evaluated. If no resource file is given in the command line BibTool tries to find one in standard places. First of all the environment variable BIBTOOLRSC is searched. If it is defined then the value is taken as a list of resource file names separated by colon (UNIX), semicolon (DOS), or comma (Amiga). All of them are tried in turn and loaded if they exist.

If the environment variable is not set or no file could be loaded successfully then the default resource file (named .bibtoolrsc, .bibtoolrc, bibtool.rsc, or .bibtool) is tried to be read in the home directory (determined by the environment variable HOME) or the current directory. Only the first such file is considered.

The resource files are searched similar to the searching mechanism for BibTeX files (see section Input File Specification and Search Path). The extension .rsc is tried and a search path can be used. This search path is initialized from the environment variable BIBTOOL. Initially only the current directory is on the search path. The search path can also be set in a resource file (for following resource file reading). This can be achieved by setting the resource resource.search.path.

resource.search.path = path

When an explicit resource file is given in the command line the defaults are not used. To incorporate the default resource searching mechanism the command line option -R can be used:

bibtool -R

Now let us consider some examples. Suppose that the current directory contains a default resource file (named .bibtoolrsc) and an additional resource file my_rsc.

The following invocation of BibTool uses only the resource file my_rsc:

bibtool -r my_rsc -i sample

If you want to initialize the resources from the default resource file before you can use the -R before the inclusion of the resource file:

bibtool -R -r my_rsc -i sample

If you add the -R argument after the resource specification then the default resource is evaluated after your resource file. Thus settings are potentially overwritten:

bibtool -r my_rsc -R -i sample

Additionally note that resource files are evaluated at once whereas input files are read in one chunk at the end. Thus you can not specify one set of parameters to be used for one file and another set of parameters for the next file. This is impossible within one invocation of BibTool¹

As a consequence of this behavior the last example is equivalent to the following invocations:

bibtool -r my_rsc -i sample -R

bibtool -i sample -r my_rsc -R

Now we have to describe the commands allowed in a resource file. The general form of a resource command is of the form

name = value

name is the resource name which conforms the rules of BibTeX reference keys. Thus name can be composed of all characters but whitespace characters and

    "  #  %  '  (  )  ,  =  {  }

Resource names are currently composed of letters and the period. The next component is an optional equality sign (=). The equality sign is recommended as it helps detecting syntax problems. Whitespace characters surrounding the equality sign or separating resource name and resource value are ignored. The resource value can be of the following kind:

• A number composed of digits only.
• A string conforming the rules of resource names, i.e. made up of all but the forbidden characters described above.
• A string containing arbitrary characters delimited by double quotes (") not containing double quotes. Parentheses and curly brackets have to come in matching pairs.
• A string containing arbitrary characters delimited by curly brackets ({}). Parentheses and curly brackets have to come in matching pairs.

You can think of resource names as variables or functions in a programming language. Resource commands simply set the variables to the given value, add the value to the old value, or initiate a action. There are different types of resources

• Boolean resources can take only the values on and off. The values on, t, true, 1, and yes are interpreted as the same. Everything else is interpreted as off.
• Numeric resources can take numeric values only.
• String resources can take arbitrary strings.

Usually whitespace characters are ignored. There is one exception. The characters % and # act as comment start characters if given between resource commands. All characters to the end of the line are ignored afterwards.

Now we come the description of the first resource available. To read in additional resource files the resource file may contain the resource

resource = {additional/resource/file}

Thus the resource given above has the same functionality as the command line option -r described above. Path names should be specified in the normal manner for your operating system.

One resource command useful for debugging is the print resource. The resource value is immediately written to the error stream. The output is terminated by a newline character. Certain translations are performed during the reading of a resource which can be observed when printing. Each sequence of whitespace characters is translated into a single space.

To end this subsection we give an example of the print resource. In this sample we also see the possibility to omit the equality sign and use quotes as delimiters.

print "This is a stupid message."

Finally we can note that the commands given in a resource file can also be specified on the command line. This can be achieved with the command line option -- The next command line argument is taken as a resource command.

bibtool -- resource_command

This can be used to issue resource commands which do not have a command line counterpart. One example we have already seen. The print instruction can be used from the command line with the following

bibtool -- print{hello_world}

Be aware that command line interpreters have different ideas about what to do with a command line before passing the arguments to a program. Thus it might be necessary to carefully quote the arguments. Especially if the command contains spaces it is very likely that quoting is needed.

E.g. in UN*X shells it is in general a good strategy to enclose command line arguments in single quotes (') if they contain whitespace or special characters like \, $, &, !, or #.

Summary

BibTool Manual Reference Manual Command Line Usage and Resource Files