Context - MWRuszczycky/btx GitHub Wiki
Working with Bibliography Entries
The btx context
The basic idea behind btx is that it helps you to query and edit the entries of a BibTeX bibliography. You specify the working bibliography using the in command. To get entries to work on in the working bibliography, you first need to isolate them from the rest of the bibliography entries by placing them in the btx context. So, when we run the command
$ btx in tutorial.bib, get Cats2016 Cleland1975 and view
what we are doing is loading tutorial.bib as our working bibliography, populating the context with just the entries Cats2016 and Cleland1975 and then viewing all the entries currently in the context, which are just these two.
Note that if you try and populate the context with an entry that does not exist, then btx won't do anything other than keep track of your mistake in case you try to do something with it. For example, try running:
$ btx in tutorial.bib, get Cats2016 Dogs1986 and view
You will see that Dogs1986 has been managed as a 'missing' entry.
When a btx command sequence (i.e., script) finishes, the context is saved back to the working bibliography before the bibliography is written back to disk. If any entries in the working bibliography have the same BibTeX key as an entry in the context when it is saved back, then you will be presented with the option of replacing it. Otherwise the entry in the context is saved back as a new entry in the bibliography. This is how we add, delete and change entries in the working bibliography.
Populating the context and creating a new entry
There are several commands that can be used to populate the context with reference entries. The most important two are get and copy. The get command moves entries from the working bibliography to the context thereby deleting it from the working bibliography. In contrast, the copy command copies entries from the working bibliography to the context thereby leaving the working bibliography unchanged. For example, try the following two commands
$ btx in tutorial.bib, get Cats2016 and view
$ btx in tutorial.bib, copy Cats2016 and view
The first command will just dislay the Cats2016 entry and quit. The second command will do the same but then ask if you want to replace the Cats2016 entry with its copy in the context. Going ahead with the replacement will leave the bibliography unchanged since they are the same entry. When viewing and editing entries, the get command is what we need; however, if we want to export entries, then we will typically use the copy command as described later on.
Another useful command for populating the context is new. For example, if we want to create a new article and book entry, we could use
$ btx in tutorial.bib, new article book and view list
Running this script with the final view list command should produce the following output
new_key_0: article, <empty title field>
new_key_1: book, <empty title field>
Here the new command created the two requested blank references of the specified types in the context, which was then viewed using the view list command before finally being saved back to the working bibliography.
Modifying entries
In the above example, the two new entries were created with generic keys to avoid conflict with any existing references already in the working bibliography. First, look at all the current references in the testBib.bib with
$ btx in tutorial.bib, get all and view list
which should display the following:
Atkins2005: book, Molecular Quantum Mechanics
Cats2016: article, Synthesis of 4a$\alpha$,7$\alpha$,7a$\alpha$-Nepetalactone
Cleland1975: article, Partition analysis and concept of net rate constants as ..
Durbin1998: book, Biological sequence analysis: Probabilistic models of protei..
Watson1953: article, Molecular Structure of Nucleic Acids: A Structure for Deo..
new_key_0: article, <empty title field>
new_key_1: book, <empty title field>
We can rename new_key_0 as anArticle2000 and new_key_1 as aBook2018, with the following script
$ btx in tutorial.bib, get new_key_0 new_key_1 and name AnArticle2000 SomeBook2018
Again running
$ btx in tutorial.bib, get all and view list
we should see that the keys have been updated:
AnArticle2000: article, <empty title field>
Atkins2005: book, Molecular Quantum Mechanics
Cats2016: article, Synthesis of 4a$\alpha$,7$\alpha$,7a$\alpha$-Nepetalactone
Cleland1975: article, Partition analysis and concept of net rate constants as ..
Durbin1998: book, Biological sequence analysis: Probabilistic models of protei..
SomeBook2018: book, <empty title field>
Watson1953: article, Molecular Structure of Nucleic Acids: A Structure for Deo..
Here new_key_0 and new_key_1 were deleted from the bibliography and replaced with their renamed counterparts. Suppose we now try doing something similar with copy instead of get,
$ btx in tutorial.bib, copy SomeBook2018 and name AnotherBook2018
$ btx in tutorial.bib, get all and view list
Now we should see the following output:
AnArticle2000: article, <empty title field>
AnotherBook2018: book, <empty title field>
Atkins2005: book, Molecular Quantum Mechanics
Cats2016: article, Synthesis of 4a$\alpha$,7$\alpha$,7a$\alpha$-Nepetalactone
Cleland1975: article, Partition analysis and concept of net rate constants as ..
Durbin1998: book, Biological sequence analysis: Probabilistic models of protei..
SomeBook2018: book, <empty title field>
Watson1953: article, Molecular Structure of Nucleic Acids: A Structure for Deo..
In contrast to the get command, the copy command resulted in a copy of SomeBook2018 renamed as AnotherBook2018, because the original was never deleted from the working directory when it was copied to the context. After its key was changed, it was saved back as a new entry keeping the original.
Finally, we could have combined the new and name commands together in a single script. For example, try the following:
$ btx in tutorial.bib, new article article and name Frogs1956 Chickens1972
If you look at the contents of tutorial.bib using get all and view list, you will see that the two new article templates have been added with the proper names.
Other ways to populate the context
There are several other ways to populate the context beyond get, copy and new. For example doi will attempt to download a BibTeX bibliography based on its digital-object identifier. For example, try the following script
$ btx in tutorial.bib, doi 10.1021/bi00289a003 and name Ray1983
You can see the newly downloaded reference with
$ btx in tutorial.bib, get Ray1983 and view
You will probably also notice that the pages field has the value 4625[?]4637 instead of the expected 4625-4637. This is because the entry was downloaded with a non-ascii dash rather than an ascii hyphen to denote the page number range. This can cause problems with LaTeX rendering, so btx will replace non-ascii characters with [?] whenever they are found in downloaded entries.
You can also search the working bibliography with a search string and poplate the context with the matches using the find command. For example, try
$ btx in tutorial.bib, find analysis and view list
which will return
Cleland1975: article, Partition analysis and concept of net rate constants as ..
Durbin1998: book, Biological sequence analysis: Probabilistic models of protei..
which are all the entries that contain the matiching string analysis. You can learn more about how the find command works by running
$ btx help find
Another useful tool for populating the context is the take command, which gives us access to entries in import bibliographies. We will go over this later in the tutorial.