Basics - MWRuszczycky/btx GitHub Wiki

The Basics

Setting up the tutorial

The first thing we need is a BibTeX bibliography file that we can mess around with. Working in the cloned btx/ repository directory, run the following command:

$ cp res/tutorial/testBib.bib .

This will copy the test BibTeX file testBib.bib to the current working directory. First, open the newly copied testBib.bib file using your favor editor (e.g., Vim) to have a look. Inspection shows that this is a syntactically correct .bib file; however, the formatting is really bad. Now close your editor, and we'll start working on the file using btx.

Loading and creating a working bibliography

First, run the following command:

$ btx

Now open the testBib.bib file again in your editor. You will see that the file has been neatly formatted. What happend is that btx read the testBib.bib file and then just wrote it back again, because we didn't tell it to do anything else. How did btx know which file to read? Try creating another .bib file with

$ cp res/tutorial/testBib.bib tutorial.bib

and run the above btx command again. Now you will get an error, because unless you specify which .bib file to open, btx will look for a unique .bib file in the current working directory and open that one. If there is no such unique file, then you must specify it using the in command. For example, try

$ btx in tutorial.bib

You will not get an error this time, but nothing happend other than the file being read and written back again nicely reformatted. We can now delete the extra BibTeX file with

$ rm -i testBib.bib

We can also use the in command to create a new BibTeX bibliography that does not already exist. For example, if you run

$ btx in myBib.bib

you find a new, empty BibTeX file called myBib.bib in the current working directory.

Viewing the contents of a bibliography

We can view the contents of a BibTeX file using the get and view commands. For example,

$ btx in tutorial.bib and get all and view

will pretty-print each entry in tutorial.bib to standard output. Once the command finishes, the bibliography is saved back to tutorial.bib; however, because we have not made any changes, its contents will be unchanged. Most btx commands can take arguments that modulate their behavior. For example, instead of getting all the references to view, we could have just viewed the references Cats2016 and Cleland1975 using

$ btx in tutorial.bib and get Cats2016 Cleland1975 and view

The view command can also take arguments. For example, to print a one-line summary of each entry in the current context try:

$ btx in tutorial.bib and get all and view list

To see all of the argument options available to view run btx help view.

Separating commands

In the previous examples we used the keyword and to separate the in, get and view commands. As this can get a little verbose, the and keyword can also be replaced with a comma. Therefore, all of the following will have exactly the same effect:

$ btx in tutorial.bib and get all and view
$ btx in tutorial.bib, get all, view
$ btx in tutorial.bib, get all and view
$ btx in tutorial.bib, get all, and view

Next: Working with bibliography entries