summaryrefslogtreecommitdiff
path: root/biblio/bibtex/utils/JavaBib/describe.html
blob: 30581cbaf6d141d246331cc36fe52b935796c2a8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="Author" content="John Janmaat">
   <meta name="GENERATOR" content="Mozilla/4.76 [en] (X11; U; Linux 2.2.16-22 i686) [Netscape]">
</head>
<body>

<center>
<h1>
JavaBib III</h1></center>

<h2>
Background</h2>
JavaBib is my attempt to make it easy to manage BibTeX files for the LaTeX
document processing environment.&nbsp; BibTeX files are files which contain
bibliographic information which the BibTeX program can use to generate
citation and reference information in LaTeX documents.&nbsp; As for everything
else associated with TeX, the data files themselves are bare text.&nbsp;
This has the tremendous advantage of making the documents system independent.&nbsp;
However, flat text files are a rather unwieldy way to manage a database.
<p>My own experience with document preparation has been in part an exercise
in locating references lost under a stack of papers in some office of mine.&nbsp;
I have found that I waste a lot of time looking for that perfect reference,
and often just give up in the search.&nbsp; To make this situation a little
better, I have tried to write a reference manager.&nbsp; The first incarnation
was a simple database under MicroSoft Access.&nbsp; This was O.K. for storing
the information, but rather useless for anything else.&nbsp; When I began
to use LaTeX, I found that the Access program was just a waste of hard
disk space, as I ended up working in Linux.&nbsp; Thus began my attempt
to build a nice GUI front end for BibTeX.
<p>The first incarnation of JavaBib was a command line based processor
that could search and modify databases.&nbsp; I stuck some GUI components
on top of this, but overall it was not all that effective.&nbsp; A second
pass was built from the ground up to be a GUI application.&nbsp; It was
somewhat better, but remained a little buggy.&nbsp; Rather than fix the
bugs, I vowed to develop a third version that both fixed the bugs and dealt
with some issues not appropriately handled in the first version.&nbsp;
These issues included the fact that Java can be quite slow when filling
memory with arrays of non-native Java objects.&nbsp; JavaBib and JavaBib
II both loaded an entire JavaBib file into memory as a vector of BibTeX
records.&nbsp; This can be quite slow to load.&nbsp; Since most of the
time using JavaBib is simply adding extra entries to an existing file,
the speed issue proved to be a great inconvenience.
<p>JavaBib III follows a completely different format.&nbsp; Rather than
reading an entire file into memory, it builds an index for the file.&nbsp;
This index allows access to specific entries in the file.&nbsp; Once the
index has been built, it is all that is loaded for subsequent uses, so
long as the underlying data file is not changed.&nbsp; Startup is much
faster this way, and most operations are not slowed up too much by accessing
the file on the disk.&nbsp; The two operations that are considerably slowed
by this approach are finding and searching.&nbsp; However, I think this
is an appropriate tradeoff given the other benefits.
<h2>
How It Works</h2>
A JavaBib session begins by invoking the program.&nbsp; This is usually
done from the command line, as I have not yet figured out an easy way to
run it as a click-able icon on a desktop.&nbsp; On startup, JavaBib looks
for a configuration file.&nbsp; This configuration file contains a history
of files that have been worked on and dimensions for the JavaBib window.&nbsp;
The parameters are loaded if found, or default values are set if the configuration
file is missing.
<p>At this point, JavaBib displays a blank main window.&nbsp; In front
of this window a startup dialog is shown.&nbsp; This dialog lists the names
of up to ten previously opened files.&nbsp; You can select one of these,
or choose to open a new or unlisted file.&nbsp; Once it has a file name,
JavaBib checks to see if there is an index file to go along with the file
you selected.&nbsp; Index files have the extension '.bdx'.&nbsp; If it
finds an index file, the index information is loaded.&nbsp; The index file
stores the last modification time and file size of the BibTeX file to which
it refers.&nbsp; If these match the conditions of the file, then the index
is used to locate the first entry, which is displayed in the main window.
<p>If an index file is invalid or cannot be found, then JavaBib will construct
one.&nbsp; To construct an index, JavaBib reads the entire BibTeX file.&nbsp;
The index contains the file position of the first character after a valid
record, the key of the next record in the file and the key of the last
record in the file.&nbsp; Once the index is built, then the first record
is displayed.&nbsp; If the file itself cannot be found, then a new file
is opened and made ready to receive records.
<p>Records are copied from the file to the display panel.&nbsp; One copy
is maintained in memory, and another displayed.&nbsp; When the user chooses
to add a new record or display a different record, the information in the
display panel is converted into a BibTeX record which is compared to the
one in memory.&nbsp; If they do not match, then the user is asked about
saving the changes.&nbsp; Before saving, the record is checked for validity.&nbsp;
All required fields must contain information, and the record must have
a unique key.&nbsp; If there is a cross reference entry, it must exist
and it must not be nested.
<p>When writing new entries or changes, these are appended to the end of
the file.&nbsp; For records that have been changed, the record in the file
is deleted.&nbsp; Deleting an entry consists of replacing its information
with a line of '%' symbols.&nbsp; TeX and BibTeX consider the '%' as a
marker for comments, and thus ignores these lines.&nbsp; If the new record
contains a cross reference entry, then the information for the cross reference
is deleted from the inside of the file and rewritten at the end of the
file.&nbsp; This operation is required to ensure that any entry which is
referred to in a cross reference appears after the reference.&nbsp; Also,
when a referenced record is moved, the field 'BOOKTITLE' is added.&nbsp;
Clearly, using cross references extensively will result in a file that
is full of empty records.&nbsp; To clean up such a file, the compress operation
recreates the file and removes any extraneous material between records.&nbsp;
Since BibTeX records are written to the file with each edit, if JavaBib
does crash, only the record being worked on will not be recorded.&nbsp;
All previous work will have been added to the file.
<p>Search and find operations proceed through the file.&nbsp; Find operations
move forward from record to record as they are displayed in the list on
the left side of the main window.&nbsp; Since the alphabetical list need
not reflect the order in the file, this operation involves much disk access.&nbsp;
The search operation is a little more efficient.&nbsp; It begins by constructing
its own index with the keys ordered by file position.&nbsp; The search
then begins at the beginning of the file and reads forward through this
index list.&nbsp; The file pointer is always moving in one direction.&nbsp;
If the system on which JavaBib is run reads ahead and buffers disk information,
this search should not be too slow.
<p>Cutting, copying, and pasting records is done via a clipboard.&nbsp;
On a Windows system, the system clipboard is used.&nbsp; Thus, the text
representation of BibTeX records can be copied and pasted between JavaBib
and other applications.&nbsp; Note that this can be dangerous if information
being pasted into JavaBib does not conform with the required BibTeX record
format.
<p>When JavaBib shuts down, it closes the BibTeX file.&nbsp; It then reads
the last modification date and file size which it stores in the index file.&nbsp;
The index file is written to the disk as a text file.&nbsp; Once completed,
the window is closed.&nbsp; On exiting the program, the parameter file
is written to the disk.
<h2>
Download</h2>
JavaBib is packaged as a .jar file.&nbsp; These files are readable by Java
directly.&nbsp; Thus, to install and run JavaBib, just download JavaBib.jar.&nbsp;
To run the program, simply type "java -jar JavaBib.jar" at the command
line.&nbsp; I leave the installation of a Java runtime environment to you.&nbsp;
To find out about this, go to <a href="www.sunsoft.com">www.sunsoft.com</a>.
<p><a href="JavaBib.jar">JavaBib.jar</a>
<p>Note: You may need to right click on the link and then select 'save
link as' to get the download to work.
<h2>
Feedback</h2>
If you have any comments about this program, please feel free to contact
me at <a href="mailto:jjanmaat@acadiau.ca">jjanmaat@acadiau.ca</a>.
</body>
</html>