BibDesk_iOS Log in to Edit
Overview
The BibDesk iOS app is currently being implemented as a read-only viewer of BibDesk libraries created on OS X.
The feature set is quite limited at present. It uses Dropbox to synchronize BibTeX libraries and associated PDFs from a single hardcoded directory. It can display a listing of all references in the library, along with associated Static and Smart groups. Full text searching of reference data is supported, but only for a single contiguous string. In the reference lists, the title and citation information is displayed but not authors. For each reference, the first linked PDF can be directly opened but not others. The PDF viewer is the same as is used in Safari and does not keep track of the section of the document last displayed.
Allowing changes to be made in iOS is a long term goal, but one that will require modifications to the OS X codebase to allow bidirectional synchronization and database conflict resolution. Doing so robustly such that the risks of data loss are minimized is a key challenge.
Another potential user base of the BibDesk iOS app is users of other reference manager software that use BibTeX as the file format. Linked PDFs would probably have to be handled differently, but with a few modifications this could be made useful for a broader audience.
Installation
BibDesk iOS can currently only be run by compiling the source code, which is relatively straightforward. First, you must download the latest version of Xcode from the Mac App Store. Second, download the source code from the BibDesk Subversion repository using the following command in the Terminal:
svn checkout https://bibdesk.svn.sourceforge.net/svnroot/bibdesk/trunk/bibdesk_ios bibdesk_ios
You can replace the final bibdesk_ios by any other name you like.
After you have checked out the source code, open the BibDesk.xcworkspace file. Note that you must open this file, not BibDesk.xcodeproj, as building BibDesk requires compilation of several additional projects which is facilitated by the workspace.
If you are not a member of the iOS Developer Program, then you will only be able to build and run in the iOS simulator and not install it on your iOS device. To run it in the simulator, select either "iPad x.x Simulator" or "iPhone x.x Simulator" from the popup in the upper-left corner, then click run.
Before linking with your Dropbox account, it is important to have created the right directory hierarchy. See the Dropbox Synchronization section below for more information.
Source Code
The BibDesk iOS source code is located in the
trunk/bibdesk_ios
directory of the SVN repository. A subdirectory (
bibdesk
) contains a branch of
trunk/bibdesk
, of which a subset of the source files have been modified to compile on iOS. All modifications are wrapped in
#if BDSK_OS_X
and
#if BDSK_IOS
preprocessor directives. Those are defined in the
Bibdesk_Prefix.pch
precompiled header file.
During development, changes from the OS X version of the codebase will be periodically merged into the branch with the following command:
svn merge -r rev1:rev2 https://bibdesk.svn.sourceforge.net/svnroot/bibdesk/trunk/bibdesk
To make sure the OS X version is unaffected by the iOS modifications, the OS X version can be built from the Xcode 3 project in the branch. When the iOS version has matured enough, the changes will hopefully be merged back into
trunk/bibdesk
, at which point the branch will go away.
All files in the BibDesk iOS directory have also been placed under the BSD license. There is one closed-source library which is used to obfuscate the Dropbox app secret. See below for more details.
Platform Support
The app supports both the iPhone/iPod touch and iPad. The interfaces for the two platforms are very similar but include optimizations for the larger screen size of the iPad.
It requires iOS version 5.1 or greater. iOS version 4.x and earlier are not supported because they do not include the
UIDocument
class, which is used for handling opening *.bib documents. iOS versions 5.0 and 5.0.1 are not supported because of issues related to suppressing local/cloud backups of data synchronized from Dropbox. iOS 6 does not appear to include significant API additions that would materially affect BibDesk development, so it does not make sense to target that exclusively. In addition, iOS 6 does not support the original iPad.
Dropbox Synchronization
Currently, the only means of loading data into BibDesk iOS is to synchronize it through Dropbox. In the future other mechanisms may be implemented but Dropbox works well so far and means that no additional software needs to be written to act as an intermediary on the Mac side. iCloud could also work, but that would require significant changes to the OS X application, and necessitate distribution through the Mac App Store, which is not considered an ideal option at this time.
The synchronization engine is very basic right now. It takes a single directory and non-recursively copies all files with "bib" and "pdf" extensions to the app. There is no indication of status beyond a spinning activity indicator and there is no way to cancel other than returning to the home screen and force quitting the app. Because no user interface has been created to change the directory that is synchronized, the app on the iPhone currently synchronizes from the "Papers" directory and the app loaded in the simulator synchronizes from the "PapersSimulator" directory.
All files are stored in the <Application_Home>/Library/Application Support/Dropbox directory, which is marked with the NSURLIsExcludedFromBackupKey attribute. This provides a permanent location for storage that is not backed up either to the user's computer through iTunes or to iCloud. For more information, see:
Long term, the synchronization engine should probably be rewritten to first sync selected BibTeX files from Dropbox, then scan those for associated PDFs and download them from whatever location they're at in the Dropbox. Since many users devices may be space constrained, there should be some mechanism for users to select which references should have their associated PDFs automatically synced. Possible mechanisms include selection of a particular Smart or Static group to be synced, or checking of a user-defined custom boolean BibTex field. For files that are not automatically downloaded, users should be able to download them on the fly from a reference page. Such files should be stored in <Application_Home>/Library/Caches so they can be purged by the device if it gets low on storage space.
Users should be given status information about what is being downloaded and how many megabytes remain in the transfer. They should be able to cancel the sync operation. It would also be helpful to allow the syncing to continue in the background if the user switches apps. Finally, it would be helpful to give the user a setting that allows them to disable synchronization over cellular networks.
Synchronization with Dropbox requires that app developers register the app with Dropbox. Registered apps are given an App key and App secret. The App key is used in the URL schema for Dropbox authentication. As is implied by the name, the App secret is supposed to be kept secret. It fills a somewhat similar role as Apple's Developer ID, where apps that abuse the system can have their privileges revoked. Given that BibDesk iOS is an open-source application, it is somewhat challenging to keep that secret while still allowing anyone to download and compile the application.
The current workaround is to use a closed-source framework (DBSessionInit.framework) maintained by Colin Smith that creates a new DBSession object initialized with the App key and secret of a "BibDesk Mobile" app that has been registered with Dropbox. Developers who do not wish to use this closed-source library can modify the initialization function in the application delegate class so that is uses an App key/secret that they register themselves. Doing so also requires the URL scheme to be updated in the Info.plist.