                         GutenPy User Manual

Opening Files: 

    Press 'o', or use the menubar's 'tool/open' item, to show the file
    selector for your Book Directory (set in prefs).  By default the
    file selector only shows the supported file formats: '.txt',
    '.zip', '.txt.gz', and '.txt.bz2'.
     
Navigation:

    The Spacebar will move you down one page.  A double-left-click
    with the mouse will do the same.
    
    The Backspace key, or Shift-Space, will move you up a page.  A
    double-right-click with the mouse will do the same.
    
    '/' and 'Ctrl-f' will open the search tool.  The search is not
    case sensitive, and can be a regular expression. eg: 'treacle' or
    'tr.*cle'.  For more information on regular expressions see:
    http://docs.python.org/lib/re-syntax.html and
    http://www.amk.ca/python/howto/regex/
    
    The PageUp, PageDown, Home, End, and cursor keys should work as
    expected.
    
    Turning the View option 'Show separator' on will draw a line
    under the three context lines at the top of page for easier
    continuous reading when using PageDown or Spacebar.


Adding a Bookmark:

    Pressing 'a' will ask you for the bookmark name to set for the
    current position in the file being viewed.  GutenPy will also ask
    you for a bookmark name when closing a file.  When quiting you are
    asked if you would like to save a mark for each open file.
    
    If you use 'default' as the bookmark name, the full path of the
    currently active file is used to store the bookmark.  This
    position becomes that file's 'default' bookmark, and is jumped to
    when that file is opened.
    
    If you type in a name for the bookmark, that named mark is added
    under the file's 'default' mark.  When there is no 'default' mark
    for the file one is created, then the named mark is added under
    it.


Viewing the Bookmarks:

    Pressing 'b' will display the bookmark list.
    
    If a file with set bookmarks is currently being viewed, it's marks
    are displayed first on the list.  Otherwise the marks are listed
    with the most recently added first.
    
    You can jump to a mark by double-left-clicking it, selecting it
    with the cursor keys and pressing enter, or selecting it and
    pressing OK.  This will open the file, if it's not already open,
    and jump to stored position.
    
    You can delete a bookmark by selecting it and pressing the Delete
    button.  If it's the 'default' mark for the file it, and all its
    named marks, are deleted.


Looking up Definitions:

    Pressing 'd' will have GutenPy ask you for a word to look up.
    
    Middle-clicking a word in a file will have GutenPy look up that
    word.
    
    The dict server (set in prefs) is then queried for definitions.
    Those definitions are then shown in a notebook, with the
    definitions from each dictionary on their own tab.
    
    You may also middle-click words in the definition notebook.


Line Numbering:
        
    Start line numbering by pressing 'l', or using 'View/Number lines'
    from the menubar.
    
    Turning on line numbering is useful when you need to reference parts
    of a Project Gutenberg file.


Showing The Separator:

    Activate the separator by pressing 's', or using 'View/Show
    separator' from the menu.
    
    Turning on 'Show Separator' can help you keep your place when
    paging down through a file.  Give it shot, you'll like it.


Browsing The Cached Catalog:

    When first running the Catalog Browser, GutenPy must make its
    initial cache of the catalog.  This involves parsing Project
    Gutenberg's catalog.rdf.bz2 file (set in prefs) and can take a few
    minutes.  Relax, make a sandwich, watch some FireFly.

    The Catalog Browser consists of the Catalog Listing (with it's
    Author, Title, Subject and Language filters), and the Download
    Booklist.

    The Catalog Listing and its Filters:

        The Catalog Listing, when initially shown, displays only books
	by authors whose names start with an 'a' (author filter set to
	'^a', but more on that in a bit).  Listing the whole catalog
	just took too long, and wasn't very useful anyhow.
		
        It's column headers show what the active filters are in
	brackets, eg: author (^a)

	Each column may be clicked to change sorting order.

	Double-clicking a listed book will add it to the Download
	Booklist below.

	You can select more than one book at a time by holding down
	the Control key while selecting.

	Holding down the Control key while using the cursor keys to
	move around, and the Spacebar to select, is also an option.

	Once the books are selected, use the 'Add to Booklist' button
	(Alt-t) to add the whole lot to the booklist.

	The Filters:
		    
            Books are only listed if they match all four of the
            Author, Title, Subject and Language regular expression
            filters.

            You can either press the 'Apply' button (Alt-a), or hit
            Enter in any of the four filters, to activate them.

            An empty filter matches anything.  Thus having all four
            empty would list the entire catalog.

            A string, or sequence of characters, is matched if it is
            found anywhere in the item.  Having 'twain' as the author
            filter will match all authors that contain 'twain'
            anywhere in them, like 'yadatwainyada'. You could use
            'twain' as the author filter, 'tom' as the title filter,
            and empty subject and language filters to find all books
            whose author's name contains 'twain' somewhere in it,
            whose title contains 'tom' somewhere in it, and they can
            be of any subject and language.

            '^' matches the beginning the item.  So, '^term' matches
            all items that begin with 'term'.

            '$' matches the end of the item. So, 'term$', matches all
            items that end with 'term'.

            '.' is a wild card, that usually follow by a count or the
            character '*', which means 'any, or none'.  This is usually
            used like so: '^term.*term$'. This means: starts with
            'term', has anything or nothing in between, and ends with
            'term'
	 
            For more information on python regular expressions see the
            following:
            http://docs.python.org/lib/re-syntax.html
            http://www.amk.ca/python/howto/regex/

    The Download Booklist:
	       
        The selected books can be downloaded from the Gutenberg mirror
        (set in prefs) with the 'Download Booklist' button (Alt-d).

        As well, the Booklist can be saved for future downloading with
        the 'Save Booklist' button (Alt-s).  When the Catalog browser
        is next started, the saved booklist will be loaded in.

        Books may be removed from the Booklist with the 'Remove from
        Booklist' (Alt-f) button.  Or, clear the entire list with the
        'Clear all from Booklist' button (Alt-c).

        Save an empty Booklist to clean out the saved list.

        Downloading the Books:

            When downloading the Booklist GutenPy will ask for a
            destination directory and a filename for each book.
        
            The directory will default to the Book Directory (set in
            prefs).  You can press the buttons and select 'other' to
            choose, or create, some other directory to save to.  I
            like to make separate directories for each author, but
            that could just be me.

            The filename will default to the books title and '.zip'.
            Remember to keep the '.zip' at the end when changing the
            name.


Visiting the Project Gutenberg Website:

    Browsing around the www.gutenberg.org website is also a lot of
    fun.  Check out their top 100 books.
    
    When selecting which version of a book to download I usually go
    for the zipped ascii, but sometimes the html version has nice
    illustrations.  GutenPy can't read the html version, but heck,
    that's what Firefox is for.


Preferences:

    Main Preferences:

        Setting the text font and colours should be pretty straight
        forward.
        
        'Book Directory' is the directory where the Catalog Browser will
        download your ebooks too, and where the File Selector defaults
        too.
        
        'Config Directory' is where GutePy will store its bookmarks, saved
        booklist, preferences, and the cached catalog.
        
        'Gutenberg Webpage' is the address to give your webbrowser when
        using the 'Visit Project Gutenberg webpage' tool.
        
        'Gutenberg Mirror' is the address of the mirror from which
        download your books.  To find a mirror near you check out:
        
        http://www.gutenberg.org/MIRRORS.ALL
        
        'Gutenberg Catalog.rdf.bz2' is the location of Project Gutenberg's
        catalog.rdf.bz2, which GutenPy uses to build it's catalog cache.
        This can be changed to a local file if you have someone else
        download it for you, eg: C:\catalog.rdf.bz2
        
        'Dict Server' is the location of the dict server to query for
        definitions.  If you happen to running a dict server on your
        machine you can change this to 'localhost'.  Linux users can
        install 'dictd' to run their own dict server.  For more
        information on dict see: 
        http://www.dict.org/links.html
        
        'Dict Port' is the port on the dict server to make requests on.
        Usually 2628, but if you are running a server on a different port,
        change as needed.
        
        All the entry settings will return to default if they are empty
        when the apply button is pressed.
    
    Behaviour Preferences:

        'Confirm Quit' when checked will ask you whether you certain
        when quiting GutenPy.

        'Auto Save Bookmarks on Quit' when checked will, instead of
        asking, just automatically save default bookmarks for files
        when closing or quiting.

        'Remember Open Files' when checked will remember what files
        are open when you quit, and load those files back in when you
        next start GutenPy 

Lee Bigelow
<ligelowbee@yahoo.com>
