Manual

To use Pieberry as a download manager - you need to tell it where your library will be. To do this, go to File -> Settings, and nominate a suitable directory under "Root directory for library". This will be where all the subdirectories containing your files will live.

You should also select a (existing or new) bibliography file for storing the bibliographic information for your downloaded files. This file ought to use a .bib extension, which corresponds to a BibTeX format.

Other options include selecting the default entry type, and specifying that Pieberry should also write bibliographic information for downloaded files to a tab-separated-value format spreadsheet.

Pieberry will scan a web page for any recognisable links to PDF documents and download them.

Files will be downloaded to your library directory, in subdirectories organised in the following hierarchy.

Library (root directory for library)

• Author (the generic 'author' you specify for a given page)
  • Category (the subject/category phrase you specify for a given page)
    • Type (some particular types of document will be further stored in these subdirectories, such as submissions from interested parties)

To scan and download PDFs:

1. Type or paste a URL into the URL text box at the top of the main Pieberry screen. It will turn pink if it is not a valid URL.
2. Specify the common author for the documents in the next field - usually the person or organisation running the web site. If the documents on the page are authored by other people don't worry, you can change this later.
3. If the common author is an organisation rather than persons, ensuring the "corporate author" checkbox to the right is check will ensure that the name you specify is treated as a single name, rather than first and surnames.
4. Pieberry will try to guess the 'category' phrase in the next field from the title of the web page. If it can't or gets it wrong, change it.
5. To the right, there is a choice box allowing you to select different ways to append the category phrase to the titles of all documents you downloaded, or not to (it will still be used as the download directory though). This is useful if the documents' titles are generic things like "Final Determination", when what you actually want is "Final Determination - Rainfall review".
6. Once you're satisfied with the settings you've chosen, click the 'Scan' button. (It will turn to an 'Abort' button for the duration). Pieberry will now start downloading all PDFs, and will show them in the list view at the bottom of the screen.

As Pieberry tries to get the documents, it will show how it went by either marking them with a blue dot and 'success' if the download was successful, a red X and 'fail' if it couldn't download them, and a green 'X' and 'already downloaded' if a document of the same name already exists.

BUG ALERT: if there are multiple different documents with the same title, Pieberry will assume they are all the same and only download the first.

When Pieberry downloads documents it will rename them to a title with a date prefix reflecting the file's creation date, and the document's title to aid archival and retrieval in the format:

YYYYMMDD TITLE.pdf

Once Pieberry finishes downloading, the files are all downloaded but nothing has yet been done to your bibliography - you can make changes to the information associated with the files before saving them to your bibliography.

To work with the documents, right click on them to bring up a context menu. There you will be able to:

• Open the document in your PDF viewer
• Open the folder where the document was stored
• Delete the document and forget about it
• Edit the bibliographic information associated with the document
• Specify whether the document should be excluded from your bibliography (it remains on disk but uncatalogued - this is useful for not cluttering up your bibliography with appendices or other trivial documents. Some documents are excluded by default, like submissions).

If you are satisfied that all the information specified is more or less correct, select File -> Save bibliography to commit all the information to your bibliography.

If, on the other hand, something is wrong - say there's a document whose author is different from the generic one you specified for the web page, select 'Edit bibliography entry' to bring up an editing dialog.

The editing dialog consists of controls for specifying:

• The BibTeX key for the given document - it is best to leave the 'auto-generate' box checked here unless you have a specific reason for choosing your own key.
• The author. If the PDF itself has a different author specified in it, it will be displayed in the field to the right. Click the button between them to substitute one for the other.
• The title. Pieberry guesses this from the text of the webpage links. Again if the PDF has a different title specified within it, this is displayed to the right.
• The date of publication - Pieberry always takes this from the creation date of the PDF file, if possible (but may use the current date if it couldn't figure it out).
• The class of document - by default, this is a generic web type of document, either 'Misc' or 'Online'. You can select from a range of other BibTeX-recognised document classes including articles, books and collections.

NOTE: to change the default document type, select one of the options in the File -> Settings dialog

• The fields below here will depend on the class of document selected. Mandatory fields will turn pink if they are unfilled. Optional fields are coloured yellow.

NOTE: Ensure that if you use curly braces ("{}") that they are always evenly matched to avoid confusing BibTeX, should you use it.

IMPORTANT NOTE: Pieberry uses the 'Annote' field to store additional information about the document, in particular, where it was saved to. If you use a BibTeX style that uses the Annote field (very few) then this may be unwelcome. Deleting it is not harmful, but it will mean that Pieberry won't be able to open your documents for you in the PDF viewer.

To find documents that are already in your bibliography, select Tools -> Find items in bibliography, or do Ctrl-F. This will bring up a search dialog. The search dialog uses a simple syntax to search your bibliography:

"field1==term1;term2, field2==term3"

You can search a given field like "title", "author" or "year" by typing "title==" etc. As a shortcut, the first letter can be used e.g. "t==". Following the "==" should be the terms you're looking for, separated by semicolons. After these, you can put a comma, and specify another field if needs be.

The search will try to find the 25 documents most nearly satisfying all your search terms.

NOTE: this is a nearest-match type search, not a limiting search. Specifying multiple fields will increase, rather than decrease the number of documents matched, but should put the ones you want at the top of the list. I will tackle limiting search at some point.

When you search, any matched documents will appear in the list view. Right-click and select 'Edit bibliography entry' to edit. It will not be saved immediately. Select File -> Save bibliography or Ctrl-S to save any entries you've edited.

To create a new bibliography entry without necessarily having a file for it, select Tools -> Create new (empty) bibliography entry.

To create a bibliography entry for the web page in the URL field itself, rather than any documents attached to it, select Tools -> Create reference for top-level page.

You can also drag and drop PDF files into Pieberry, which will open up a bibliography edit window to allow you to add it to your library.

You may now wish to cite documents in your bibliography in a paper you're writing. If you're a LaTeX user you can use the bibliography file to feed into BibTeX through the usual process (consult BibTeX documentation).

NOTE: Pieberry will save .bib files in utf-8 format. This can cause problems with BibTeX when non-ASCII characters appear in its fields. At a minimum, use \inputenc{utf-8}. Preferably you might use a utf-8 friendly version of BibTeX like Biber or Pybtex.

To get a citation directly from Pieberry, right click on a document, and select the 'Copy' submenu, under which there are the options 'Copy citation to clipboard' in html and text format. Selecting one of these should put a well formatted citation into the clipboard for you to paste into a document.

NOTE: The format of the citation is not customisable at this point.

The html version of this operation will embed the URL of your document, if it has one, as a hyperlink in the citation to make your sources more easily accessible to your readers. This is particularly useful in MS Word.

You may also copy the BibTeX key of the document to the clipboard for working with LaTeX, or the original URL of the document.

Every time you open the Desktop cleaner -> Process files from desktop window, Pieberry will 'sweep' all the PDF and MS WORD files on it into a temporary directory.

It will then populate the desktop cleaner window with a line of controls for each file, allowing you to select where they should be filed and under what name.

Under Desktop cleaner -> Desktop cleaner settings you can set up the various subdirectories (project folders) that you would like to file into.

For each directory, you can specify keywords for authors and titles, that correspond to that directory. The desktop cleaner will use these to suggest a suitable directory.

You should also select your projects directory and your desktop directory in the corresponding fields.

For each file, you can do the following things:

• Mouse over the icon to the left - this will present a tooltip with relevant file metadata for your information.
• Select a destination folder from the list of folders you set up in the desktop cleaner settings. If the file metadata matches any of the terms you associated with a directory, then it should already have an automatic recommendation for which directory.
• Alter the destination filename - this will be automatically suggested based on the creation date (for PDFs) or last modification date (for MS WORD docs), and the longer of its existing filename or any title specified in its metadata.
• Create a bibliography entry (for PDFs only) - this will put a copy of the document into your library (it will not remove it from the desktop cleaner).
• Delete the file if it is no longer necessary.
• "Go" and file the document as specified.

BUG ALERT: on MS Windows, there is an issue with Pieberry causing MS WORD documents to be 'locked' and unable to be moved. This is proving difficult to resolve, but the problem usually goes away after closing and reopening Pieberry.

You can also open the temp directory to get right at these files, or 'process all' which will move all files that have a destination directory specified.

Pieberry - in addition to its bibliography search function - also contains a simple filename search function, accessible through the Tools menu or by Ctrl-Shift-F. Like the bibliography search, it takes a simple syntax of:

area==term1;term2

You can search the 'library' or 'projects' areas ('l' and 'p') for short, or 'all', and also search by year or month.

This searches only filenames, not metadata nor document text. A full text search may be some way off. Files thus found will be displayed, but the citation functionality is not available.

You can drag files from the list view to other locations - this will copy, not move the files.