
Hi, here is the famous, marvellous, uncredible

  ####      #    #    #  #####     ##     ####   #    #
 #          #     #  #   #    #   #  #   #    #  #   #
  ####      #      ##    #    #  #    #  #       ####
      #     #      ##    #####   ######  #       #  #
 #    #     #     #  #   #       #    #  #    #  #   #
  ####      #    #    #  #       #    #   ####   #    #

T_H_E Reference manager for unix systems, the one you where 
looking for! It will make you happy NOW.



              by Sixten Boeck and Andre Merzky
_____________________________________________________________________
originally written by
# Sixten Boeck
# email: boeck@physik.hu-berlin.de
# see:   http://crysta.physik.hu-berlin.de/~boeck
_____________________________________________________________________
modified by Michael Lachmann
e-mail: dirk@santafe.edu
(now it's "incredible"!)
_____________________________________________________________________
sixpack is under the GPL. See gpl.txt for more information
_____________________________________________________________________

disclaimer
----------
The current version is called 0.99, because the last one was called
0.98, and I didn't want any confusion to arise. But this is *ALPHA*
software. The only one who tested this latest version is me, and I made
a lot of changes! On a real scale, I would call this version 0.0.2.
So, backup your databases before you use it. Sixpack has no autosave
feature, but it creates backups of files it writes to.

Installation
------------

requirements:

1. bp (will be installed from bp-0.2.97.tar.gz )
2. Perl/Tk (you'll have to do this yourself)
optional:
3. wget (if you want to be able to directly import from the web)





you have two options - automatic and manually.

Automatic:
1. edit "install" and check that all is defined well
2. run (as root if you are installing globally)
   if you want to install both bp and sixpack:
     ./install with-bp
   or, if you want to install sixpack only
     ./install

optional:
in the subdirectory 'bp_additional_modules' are a couple of 
addtional or replacement modules to bp. To use them, you just need to
copy them to the directory BPHOME. if you run
    ./install with-mod
(or ./install with-bp with-mod)
Then these will be installed for you.


Manually:
0. install bp
1. edit bib and bib-remote, and set the correct path for perl.
2. copy the files bib and bib-remote to somewhere in your path.
3. copy the Directory Pict somewhere. You will have to set the configuration
   variable PICSDIR to that in sixpack.rc
4. (optional) If you need a specialised configuration (for example setting
   PICSDIR to something other than /usr/local/lib/sixpack/Pics), then copy
   the file sixpack.rc either to /etc/sixpack.rc or to ~/.sixpack.rc and edit
   it appropriately.
   

optional 2:
1. For the command-line interface, if you use vim, you could also install the
vim style file biblio.vim in the appropriate place





Use
---
bib [-gui] [-sixtex=file.bref] [-bibtex=file.bib]

-gui          Use graphical interface
-sixtex=file  load database from file
-bibtex=file  import database from bibtex file



bib-remote [command line]

Execute command line under the currently running sixack. Can be useful
for importing directly from your web-browser.



Configuration
-------------
In the configuration file (sixpack.rc) the following variables are
recognised: (all have default values, and thus aren't necessary)

WC = /usr/bin/wc
AWK = /usr/bin/awk
CAT = /bin/cat
TMP = /tmp/
CONV = /usr/local/bin/bibconv
DATE = /bin/date
EDIT = /usr/bin/vim -f
GREP = /bin/grep
LESS = /usr/bin/less
MV = /bin/mv
RM = /bin/rm
# if wget is defined, then import from URL is possible
WGET = /usr/bin/wget

where to put pixmaps
PICSDIR = /usr/local/lib/sixpack/Pics
where to put docs
SIXDOC = /usr/local/lib/sixpack/doc

# where the default resource file sits. Might also be
# /usr/X11/lib/app-defaults/Bib
BIBXRESFILE = /usr/local/lib/sixpack/Bib

PAPERS = ~/papers    # This variable holds the directory in which the raw
                     # papers are stored

BPHOME = /usr/local/lib/bp    # place where BP is installed. This will be
                              # overridden by the BPHOME environment
                              # variable, if defined

# TMP = /tmp/dirktest  # temporary file prefix - if not set it will default
                       # to /tmp/$USER

# LYXPIPE = ~/.lyx/.lyxpipe.in # path to pipe used by lyx. This should be the
	               # same as the \serverpipe variable in ~/.lyx/lyxrc

#DISPLAYLINE = au:17,ti:88 #which items should be displayed in the line-view. The default is
# au:17,ti:88, so dont change this if that is what you want.

# PIDFILE = ~/.sixpack.pid # place where the pid of the running process
                           # is stored.

# place where history is stored and its length
# HISTORYFILE = ~/.sixpack.his
# HISTORY = 500

# How many recent files appear in the 'File->Recent' menu
# RECENTFILES = 5


If a reference entry contains a line file=filename in its bibtex file,
then this line will show up under the 'Misc' entry in the dialog. By pressing
alt-v, or the leftmost icon, the file will be shown for viewing. You can
define handlers for various extensions. The variable
MISCHANDLE = /bin/echo no handler for file %s

holds the action to be done for an unrecognised type.

To define a handler for an extension, add a variable with the name
EXHANDLE.ext as in:

EXTHANDLE.pdf = xpdf
EXTHANDLE.ps = gv
EXTHANDLE.ps.gz = zcat %s | gv -
EXTHANDLE.tar.gz = view_article
EXTHANDLE.dvi = xdvi
EXTHANDLE.html = netscape-remote -remote "openFILE(%s)"

the special string %s will be replaced by the filename. Otherwise the
filename will be appended at the end.

If an entry contains a line
url=some.url.org
Then the url can be accessed. You can define the url handler:
URLHANDLE = netscape-remote -remote "openURL(%s)"

If you now view the file, the program will first try to open the file, and then
try the url. You can also open the url directly from the menu.


The default behaviour of sixpack is to save a file called filname.bib.bref
whenever a database filename.bib is saved in bibtex format. Then, on the
next load of the bibtex file, the modification date of the files is
compared, and the sixpack database is opened if the bibtex hasn't been
changed. This makes loading databases much faster. To turn this feature of,
change the following parameter:

BIBWITHBREF = 1  # this will enable the feature
BIBWITHBREF = 0  # this will disable it



To configure how menu entries the long menus should contain, change this
parameter:
ENTRIESPERMENU = 16

To add an external script to the menu do the following:

MENUEXEC1 = List Files: source ~/lib/ls_in_sixpack.six
MENUEXEC2 = export and Xdvi: source ~/lib/xdvi_in_sixpack.six

(up to 10 entries can be added)

Then edit script files, in this example they could be:
----- ~/lib/ls_in_sixpack ---
sys ls
-----------------------------

----- ~/lib/xdvi_in_sixpack ---
export bibtex file.bib
sys latex file.tex
sys bibtex file.tex
sys latex file.tex
sys latex file.tex
sys xdvi file.dvi
-------------------------------

As you can see this is still very primitive.....

A bit more about sys:
'sys' will execute a command. if Part of the command is enclosed in {
brakets }, that part will first be evaluated in perl. This enable the
command to read perl variables, or to call subroutines. This is a dirty
hack, because scripts will then depend on the internals of sixpack.
The following routines have been added to make it a bit less of a hack:

historyFind("command",index)
 finds the last time "command" was used (in the history), and gets argument
 index from that call.
 
Thus 

historyFind("export",-1)
 will find the name of the last exported file

historyFind("export.*html\$",1)
 will find the name of the last file exported to html. Notice that One can
use regexp, but special chars, such as $ and \ have to be protected with \



askOpenFile("title")
askSaveFile("title")
 will ask the user to enter a filename.

see the examples directory for examples.


User Interface
--------------

key-bindings:

up, down, pageUp, pageDown, end, home                    
                           - move in the entry list

shift-up, shift-down,       
alt-up, alt-down         - move to next marked entry

alt-enter                 - start editing current entry

alt-o                     - open file
alt-s                     - save file
alt-x                     - exit (if no modification to current database)
                             To exit when the database is modified, use the
                             menu

alt-insert                - insert new entry

alt-delete                - delete current entry, or marked entries, if any
                             are marked!!

alt-+                     - mark entry
                 (this can also be done with the left mouse button)

alt--                     - unmark entry
alt-a                     - mark all
alt-u                     - unmark all

alt-v                     - view article, entry has a line of the form
                            file=filename

alt-l                     - insert citain into LyX
			    
icons: 
--------+---------+-------+-------+-------+-------+------+-------+--------+------+
rolodex | clamp   | pencil| hammer| box   |binoc. |screen|letter | signs  | book |
--------+---------+-------+-------+-------+-------+------+-------+--------+------+
open    | new     | new   | edit  | delete|open   |open  |sort by| sort by| view |
database| database| entry | entry | entry |query  |exec  |author | title  | file |
        |         |       |       |       |window |window|       |        |      |
--------+---------+-------+-------+-------+-------+------+-------+--------+------+


X11 resources
-------------
The file BIBXRESFILE, usually insalled in /usr/local/lib/sixpack/Bib
contains various default X11 resources, such as font, color, background,
foreground, etc. You can change these in the file, or in other Xresource
file location, such a ~/.Xdefaults
Command line options are also processed.
			
			
Searches
--------
you can do pretty sophisticated searches:

au=smith
select all entries with authors whose name includes "smith"
ti=group
select all entries with titles that include "group"
Now you defined queries 0 and you, and you can do
#0 or #1
You can open the query window from the 'View' menu.

You could also have done
au=smith or ti=group

The full list of all names of fields is available under the 'Query' menu.

Under the 'Query' menu you'll also see an entry 'store current marks' (which
is equivalent to the command-line 'mark') . Using
this entry you can save the currently marked fields.
For example, you could import a new database. This marks all the imported
entries. Store the current marks. Now in the query window, you'll see
that entry #0 is 'mark'. Now you can do searches only on the new entries:
au=smith and #0

Marking entries by aux files
----------------------------
Sometimes it is usefull to handle all entries that were used in a
certain LaTeX file. For this one can use the .aux files generated
during the latexing process.
To select all entries mentioned in a certain aux file, choose the menu
entry "Edit->mark according to aux file", use the command line syntax
select aux filename
all entries from that file are selected according to the
CITEIDs. Notice that the old entries are not erased, which enables one
to mark entries from multiple files.


sort
----
The button third from the right (ignoring the 4 arrows) sorts by author,
and the one left of it by title. You can also select sorts from the 'Edit'
menu. Between sorts, the data isn't re-shuffled, so if you want to sort by
year, and within the year by author do:
1. sort by author
2. sort by year
(sadly sort by author sorts by the first name....)

The special command "mark double CITEIDs" will sort by CITEID, and mark all
entries that occur twice.

editing
-------
In order to change an entry, you have to open it for editing, edit it, and
then lock it. So do the following:
1. Select the entry
2. hit alt-enter
3. Edit the entry to your hearts content
4. hit alt-enter

Instead of 2 and 4 you cane also use the 4th button from the left, the one
with the tools which changes to a lock once you start editing.

generating CITEIDs
------------------
From the menu, you can ask to program to generate CITEIDs. If any
entries are marked, it will generate IDs for those entries. Otherwise,
for the highlighted entry. You specify What the CITEID should look
like in the variable CITEID. In the file sixpack.rc there is some
documentation about how to specify the variable. Here it is:

# Citeids are created according to the field CITEID. Imagine
# You cite the following paper:
# Introduction to produce citeids for sixpack
# G Lachmann and Z Bergstrom and Y Knot and X Moore
# feb 1998
# pages 1234
# Now write down the citeid you would create, and seperate
# The fields with ,
# a few examples:
#CITEID = Lachmann,98
CITEID = LACHMANN,1998
#CITEID = lachGEtal,98
#CITEID = lacANDber,98
#more complicated: (here we use the title, drop common words)
#CITEID = LachG,98,feb,:,IntProCit
#more complicated:
#CITEID = GLach,98,feb,:,intrtoprod

#Now, if we drop words from the title for the CITEID, we need to tell
#what words to drop.   
#This is te default. If you just use this, the field isn't needed.
#TITLEIGNORE = the of from in on to a 



importing
---------
You can see in the 'Transfer' menu the various formats that sixpack
(actually, bp) supports. Just select import/export, and enter the filename.

If the configuration variable WGET is set to the path of wget, then
importing from a url is possible. 

Just select the url (in netscape there is an option under the right-click
menu to 'copy link location), and then paste it in. (paste is also possible
with the 'insert' keyboard button).


direct import
-------------
Some web sites allow you to download citations directly into your
citation manager. This usually means that they specify the mime type
for the citation.
For example, when medlib lets you download a citation for endnote, it
specifies the mimetype as:
application/x-endnote-refer

To have sixpack deal with these, all you need to do is this: go to the
helper application menu in netscape preferences, and add a new
mime-type,

application/x-endnote-refer

(or any other type you need to deal with)
and set the application to

bib-remote import endnote %s text

to import a regular text formated file (that's usually the case)
or

bib-remote import endnote %s html

for an html formated file.
(Of corse you need to replace 'endnote' with whatever format that
particular mime-type is).

And, that's it! Now if sixpack is open (cmd line or gui mode) it will
automatically import the citations.


Using sixpack with LyX
----------------------
You'll have to work out the details, as I haven't used this
extensively, yet. Here are the basics:

(read the documentation of LyX called 'extended features')

* You need to tell LyX which bibtex file to use. For this, go to the
  end of the lyx file, and select Insert->lists and TOC->bibtex
  reference.  Enter the name of the bibtex file. E.g. test.bib

* Whenever you want to insert a citation in your lyx document, go to
  sixpack and select 'insert into lyx'.

* In sixpack you need to export the document to bibtex. So, either
  select all the references you want (middle mouse button or alt +) or
  leave everything unselected, and then you will export everything.
  Select Transfer->Export->bibtex and then write the name of the file,
  e.g. test.bib.  

Now when you create the document with lyx, you
should have a bibligraphy, and all references correctly.




