                         GutenPy User Manual

Opening Files: 

    Press 'o', or use the menubar 'File/Open' item, to show the file
    selector for your Book Directory (set in prefs).
  
    If 'Remember Open Files' was on (set in prefs) when GutenPy was
    last shutdown, the files from that session will be opened
    automatically on startup. 

    By default the file selector's filter is set to
    'Only Supported', and only shows the file formats: '.txt', '.zip',
    '.txt.gz', and '.txt.bz2'.

    You could also you the Sidebar to open files.


Closing and Quitting:

    Press 'q', or use the menubar 'File/Close file' item, to close the
    current file.  If there are no open files and 'Confirm Quit' is on
    (set in prefs), you will be asked if you wish to quit GutenPy.  If
    'Confirm Quit' is off GutenPy will quit without asking.

    Press 'Ctrl-q', or use the menubar 'File/Quit GutenPy', to quit
    GutenPy completely.

    When closing a file, and 'Auto Save Bookmarks' is off (set in
    prefs), you will be asked to set a boomark for the current
    positon.  If 'Auto Save Bookmarks' is on a default bookmark will
    be set without asking.

    When quitting, and 'Auto Save Bookmarks' is off, you will be asked
    if you wish to set bookmarks for each open file.  If 'Auto Save
    Bookmarking' is on a default bookmark will be set for each open
    file.

    When quitting, and 'Remember Open Files' is on (set in prefs), the
    currently open files will be remembered and restored when GutenPy
    is next run.
    

Sidebar:

    Press 's', or use the menubar 'View/Show Sidebar' item, to
    toggle the display of the sidebar.

    Double-left-click an item in the file/bookmark listing to open it.

    The Delete button on the bottom of the sidebar can be used to
    remove a selected file or bookmark.

    
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. 

    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.
    
    The View option 'Show separator', when 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 a bookmark name to set for 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 bookmark for each open file (If the behaviour preference
    'Auto Save Bookmarks' is on a default mark is saved without asking
    when closing and quitting).
    
    The file's default bookmark is jumped to when that file is next
    opened.
    
    If you type in a name for the bookmark, that named mark is added
    under the file's default mark.  If you add a named mark when there
    is no default mark for the file, a default mark is created and the
    named mark is added under that.


Viewing the Bookmarks:

    Pressing 'b' will display the bookmark list.  The bookmarks may
    also be viewed in the sidebar by pressing 's'.
    
    The bookmarks 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.  If the file is open GutenPy will
    just scroll to the saved position.
    
    You can delete a bookmark by selecting it and pressing the Delete
    button.  If you delete the 'default' mark for the file it, and all
    its named marks, are deleted.


Looking up Definitions:

    Pressing 'd', or using 'Tools/Definition' 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.

Full Screen:

    Toggle fullscreen mode by pressing 'f', or using
    'View/Fullscreen'.

    Fullscreen mode will maximize the window, and hide the toolbar and
    sidebar, giving you the extra reading room.
    

Hiding the Toolbar:

    Toggle the toolbar by pressing 't', or using 'View/Show toolbar'.


Wrapping Long Lines:

    Toggle line wrapping by pressing 'w', or using 'View/Wrap long
    lines'.

    If on, long lines will be wrapped and horziontal scrolling won't
    be necessary.  It may disrupt the layout of the file, but the
    entire file will be visible and line numbering will still be
    accurate.

 
Showing The Separator:

    Toggle the separator by pressing 'Ctrl-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.


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


Browsing The Cached Catalog:

    Press 'Ctrl-c', or use 'Tools/Browse Cached Catalog', to start
    the Catalog Browser.

    When first run the Catalog Browser 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
    filters, and the Download Booklist.

    The Catalog Listing and its Filters:
		
        If the checkbox beside the filter's title is checked, that
        filter will be remembered and used when the catalog is next
        opened.

        The Catalog Listing'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.

            The checkbox beside the filters title sets whether to save
            that filter for use in future sessions.

            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.  Thus, 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 is usually follow by a count or
            the character '*', which means 'any, or none'.  This is
            usually used like so: '^term.*term$', meaning: 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 'Download to directory' button
            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'
 
            This is the directory where the Catalog Browser will
            download your ebooks too, and where the File Selector
            defaults too.
        
        'Config Directory' 
            
            This is where GutePy will store its bookmarks, saved
            booklist, preferences, and the cached catalog.
        
        'Gutenberg Webpage' 

            This is the address to give your webbrowser when using the
            'Visit Project Gutenberg webpage' tool.
        
        'Gutenberg Mirror' 

            This is the address of the mirror from which to download
            your books.  To find a mirror near you check out:
        
            http://www.gutenberg.org/MIRRORS.ALL
        
        'Gutenberg Catalog.rdf.bz2' 

            This is the location of Project Gutenberg's
            catalog.rdf.bz2 file, which GutenPy uses to build its
            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' 

            This is the location of the dict server to query for
            definitions.  If you happen to be 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' 

            This 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 the default settings if
        they are empty when the apply button is pressed.
    
    Behaviour Preferences:

        'Confirm Quit' 

            When checked GutenPy will ask you whether you are certain
            when quitting.

        'Auto Save Bookmarks on Quit' 

            When checked will, instead of asking, automatically save
            default bookmarks for open files when closing or quitting.

        'Remember Open Files' 

            When checked will remember what files are open when you
            quit, and restore those files when you next start GutenPy.

Lee Bigelow
<ligelowbee@yahoo.com>
