ImportExport - MWRuszczycky/btx GitHub Wiki

Import and Export Bibliographies

When we started this tutorial, we created an empty BibTeX bibliography called myBib.bib using the in command. If you do not have this file, then you can create it now with

$ btx in myBib.bib

What we want to do now is start building this BibTeX file up by adding entries to it from the tutorial.bib file. There are two ways to this by using import and export bibliographies.

Import bibliographies

An import bibliography is a source of BibTeX entries that you can use to populate your working bibliography. The import bibliography never gets changed by btx and is set using the from command. An import bibliography can thus be thought of as a central repository of BibTeX reference entries that you can use build other bibliographies.

For example, if we wanted to add the Cats2016 and Ray1983 entries to our myBib.bib file, we could run the following script:

$ btx in myBib.bib, from tutorial.bib, take Cats2016 Ray1983

Here we set myBib.bib as the working bibliography using in (this has to come first). Next we set tutorial.bib as the import bibliography using from. The final take command is just like copy but applies to the import bibliography rather than the working bibliography. Therefore, the context gets populated with copies of the Cats2016 and Ray1983 entries from tutorial.bib. When the script finishes, all the entries in the context are automatically saved to the working bibliography, so myBib.bib gets updated with Cats2016 and Ray1983 in this example.

Each time the from command is envoked, it has no effect other than to simply reset the import bibliography leaving the context unchanged. However, if you try to use from on the same file used for the working bibliography, then the effect is to simply unset the import bibliography. In other words, the working and import bibliographies can never reference the same file. Likewise, if you use the from command without a file path argument, then it will again just unset the import bibliography and do nothing else.

Export bibliographies

An export bibliography serves as a target to which you can send entries from the working bibliography. Therefore, an export bibilography is essentially the opposite of an import bibliography, such that your working bibliography becomes the central repository that you can use to build other BibTeX bibliographies.

You designate an export bibliography using the to command. The to command works similar to in such that if the designated export bibliography file does not exist, then it will be created. For example, suppose we want to add the Watson1953 reference to myBib.bib from tutorial.bib, but this time tutorial.bib will be the working bibliography. We could do this with

$ btx in tutorial.bib, copy Watson1953 and to myBib.bib, send

Here we designate tutorial.bib as the working bibliography and populate the context with Watson1953 using copy. We then designate the export bibliography with the to command and modify it by adding all the entries in the context (i.e., just Watson1953 here) using send. This also clears the context, so if we had used get Watson1953 instead of copy Watson1953, then the effect would have been to move the entry from tutorial.bib to myBib.bib rather than copying it over. Finally, the send and to commands can be combined into a single send to command. For example, try the following

$ btx in tutorial.bib, copy Cleland1975 and send to myBib.bib

Each time the to command is envoked, the current export bibliography gets saved and the new export bibliography gets loaded. If the file path supplied to to is the same as that for the current working bibliography, then the current export bibliography gets saved and then unset. In other words, the export and working bibliographies can never reference the same file. You will get the same effect by using to with no arguments.

Going further

That's the end of the tutorial; however, you can do more with btx than what was just decribed. To get a list of all available commands, try running

$ btx help

To get more information on any one command, keyword or directive, just combine it with the help command. For example, we used the all keyword with get several times to populate the context with all entries in the working bibilography. To get more information about this try running