summaryrefslogtreecommitdiff
path: root/biblio/bibtex/utils/JavaBib
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /biblio/bibtex/utils/JavaBib
Initial commit
Diffstat (limited to 'biblio/bibtex/utils/JavaBib')
-rw-r--r--biblio/bibtex/utils/JavaBib/JavaBib1.jpgbin0 -> 83258 bytes
-rw-r--r--biblio/bibtex/utils/JavaBib/describe.html142
-rw-r--r--biblio/bibtex/utils/JavaBib/docs.html270
-rw-r--r--biblio/bibtex/utils/JavaBib/index.html47
-rw-r--r--biblio/bibtex/utils/JavaBib/screen.html29
5 files changed, 488 insertions, 0 deletions
diff --git a/biblio/bibtex/utils/JavaBib/JavaBib1.jpg b/biblio/bibtex/utils/JavaBib/JavaBib1.jpg
new file mode 100644
index 0000000000..09379f87fc
--- /dev/null
+++ b/biblio/bibtex/utils/JavaBib/JavaBib1.jpg
Binary files differ
diff --git a/biblio/bibtex/utils/JavaBib/describe.html b/biblio/bibtex/utils/JavaBib/describe.html
new file mode 100644
index 0000000000..30581cbaf6
--- /dev/null
+++ b/biblio/bibtex/utils/JavaBib/describe.html
@@ -0,0 +1,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>
diff --git a/biblio/bibtex/utils/JavaBib/docs.html b/biblio/bibtex/utils/JavaBib/docs.html
new file mode 100644
index 0000000000..729d577e40
--- /dev/null
+++ b/biblio/bibtex/utils/JavaBib/docs.html
@@ -0,0 +1,270 @@
+<!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 Documentation</h1></center>
+
+<h2>
+Contents</h2>
+
+<ul>
+<li>
+<b><font size=+1><a href="#startup">Startup</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#file">File Menu</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#edit">Edit Menu</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#records">Records Menu</a></font></b></li>
+
+<li>
+<b><font size=+1>Search Menu</font></b></li>
+
+<li>
+<b><font size=+1>Cite Menu</font></b></li>
+
+<li>
+<b><font size=+1>Window Menu</font></b></li>
+
+<li>
+<b><font size=+1>Help Menu</font></b></li>
+</ul>
+
+<h2>
+<a NAME="startup"></a>Startup</h2>
+The method by which JavaBib is started depends on the installation you
+choose.&nbsp; If you are running the program from a '.jar' file, type '<b>java
+-jar JavaBib.jar</b>'&nbsp; The '.jar' file contains a manifest file which
+indicates which class contains the 'main' method.&nbsp; Alternatively,
+you can unpack the '.jar' file into a directory.&nbsp; The class files
+will then be present as separate files.&nbsp; This method of loading the
+files may be slightly faster as each file does not need to be unpacked.&nbsp;
+However, since the Java interpreter only loads each class once, the performance
+benefit will be quite small.&nbsp; If you have installed JavaBib in this
+way, execute it by typing '<b>java JavaBib</b>'.&nbsp; For both types of
+execution, one can add a file name to indicate which file JavaBib is to
+open.
+<p>Once JavaBib has been launched, the main window with a blank edit panel
+appears.&nbsp; In front of this the startup dialog is displayed.&nbsp;
+The startup dialog shows a list of files that have previously been opened.&nbsp;
+To open one of the listed files, you can either double click on it or select
+it, choose 'open listed file', and press continue.&nbsp; The selected file
+is then opened.&nbsp; If the file you want to edit is not listed, or you
+want to start a new file, select 'open new or unlisted file' and press
+continue.&nbsp; A file dialog will be displayed, where you can select a
+file to open or type in a new file name.&nbsp; Note that the file name
+must have a '.bib' extension.&nbsp; If the selected file does not have
+a '.bib' or '.bdx' extension, then the selected file name will have '.bib'
+appended to it.
+<p>JavaBib tries to open the named file.&nbsp; The first step in opening
+the file is to look for an index file.&nbsp; Index files have the extension
+'.bdx'.&nbsp; The index file contains the name of the associated BibTeX
+file as well as the length of the file and the date when it was lasted
+edited.&nbsp; If the index file is found, it is opened.&nbsp; If the matching
+BibTeX file exists and if the length and last modified date are correct,
+the index is loaded into memory.&nbsp; The index file contains the location
+of each entry in the '.bib' file, as well as pointers to the previous and
+next entry.&nbsp; If the index file is not present, then the BibTeX file
+itself is checked for.&nbsp; If it is found, then an index is generated
+for the file.&nbsp; If the BibTeX file is also missing, then a new BibTeX
+file is opened and made ready for writing.
+<h2>
+<a NAME="file"></a>File Menu</h2>
+
+<ul>
+<li>
+<b><font size=+1><a href="#file->open">Open</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#file->close">Close</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#file->compact">Compact</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#file->import">Import</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#file->export">Export</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#file->exit">Exit</a></font></b></li>
+</ul>
+
+<h3>
+<a NAME="file->open"></a>Open</h3>
+Opening a file repeats the operation that occurs when JavaBib is first
+launched.&nbsp; Upon selecting open, a startup dialog is displayed.&nbsp;
+This dialog lists the names of recently opened files.&nbsp; The user may
+select one of these or open a new file.&nbsp; Note that only one file can
+be accessed at one time.&nbsp; JavaBib does not load the BibTeX file into
+memory.&nbsp; Rather, the file is accessed one record at a time, as needed.&nbsp;
+Simultaneous access on the same file can lead to problems whenever new
+records are added.&nbsp; Thus, it is not advisable to have one file open
+more than once.
+<h3>
+<a NAME="file->close"></a>Close</h3>
+The close operation closes the displayed window.&nbsp; If the file does
+not have any records, it is deleted from the disk and the index is not
+written.&nbsp; If the file has records, then after the file is closed the
+index file is also written.&nbsp; If the window being closed is the last
+window, then the application is closed.&nbsp; On closing, the properties
+file is also written to the disk, storing the dimensions of the window
+and the list of files that have been worked on.
+<h3>
+<a NAME="file->compact"></a>Compact</h3>
+The compact operation removes extra space from the database.&nbsp; When
+records are deleted or modified, they are overwritten with a line of comment
+characters.&nbsp; New records are always added to the end of the file.&nbsp;
+Records which contain cross references are added to the end of the file,
+after which the referred to record is moved to the new end of the file.&nbsp;
+This ensures that BibTeX conventions are satisfied.&nbsp; However, it also
+means that files will end up full of spaces.&nbsp; The compact operation
+removes this extraneous space from between the records.
+<h3>
+<a NAME="file->import"></a>Import</h3>
+Records from other BibTeX files can be imported into an open file.&nbsp;
+To this point, text files are the only source of import.&nbsp; When this
+option is selected, a file dialog is displayed so that the user can select
+which file to open from.&nbsp; Note that if you try to import records from
+a file which is not a BibTeX data file, you may crash JavaBib.&nbsp; Be
+careful importing data.
+<h3>
+<a NAME="file->export"></a>Export</h3>
+The export operation writes selected entries to a new file.&nbsp; When
+export is selected, a file dialog is opened.&nbsp; Enter the name of the
+file to export to.&nbsp; The selected entries will then be written to this
+file.
+<h3>
+<a NAME="file->exit"></a>Exit</h3>
+Selecting exit closes all windows and shuts down JavaBib.&nbsp; On exit,
+the index files for each open database is written.
+<h2>
+<a NAME="edit"></a>Edit Menu</h2>
+
+<ul>
+<li>
+<b><font size=+1><a href="#edit->new">New</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#edit->clear">Clear</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#edit->reset">Reset</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#edit->cancel">Cancel</a></font></b></li>
+
+<li>
+<b><font size=+1><a href="#edit->options">Options</a></font></b></li>
+</ul>
+
+<h3>
+<a NAME="edit->new"></a>New</h3>
+Selecting New clears the entry panel and presents a blank record for to
+record a new entry.&nbsp; Before displaying the new entry however, any
+currently displayed information is checked for changes.&nbsp; If changes
+have been made, then the user is prompted for confirmation on writing or
+trashing any changed.&nbsp; If the record is to be written, it is checked
+for consistency with the requirements for this record type.&nbsp; The checks
+include the presence of all required fields as well as a unique key.&nbsp;
+If this entry is a cross reference, the presence of a cross reference key
+is checked, and a check is made to ensure that the cross reference does
+not itself contain a cross reference.&nbsp; Once all checks are passed,
+the record is written.
+<h3>
+<a NAME="edit->clear"></a>Clear</h3>
+Clears the information in the active record.&nbsp; All data fields are
+cleared.&nbsp; The record type, citation key and crossreference field are
+not changed by this operation.
+<h3>
+<a NAME="edit->reset"></a>Reset</h3>
+Restore the initial values for this field, before any changes were made.
+<h3>
+<a NAME="edit->cancel"></a>Cancel</h3>
+Cancel the current edit operation.&nbsp; If an existing record is being
+acted upon, then this operation is the same as reset.&nbsp; If a new record
+is being created, cancel causes the edits to be lost and displays the most
+recently selected record.
+<h3>
+<a NAME="edit->options"></a>Options</h3>
+Not yet implemented.&nbsp; In future, this selection will enable various
+program options to be modified.
+<h2>
+<a NAME="records"></a>Records Menu</h2>
+
+<ul>
+<li>
+<b><font size=+1>Cut</font></b></li>
+
+<li>
+<b><font size=+1>Copy</font></b></li>
+
+<li>
+<b><font size=+1>Paste</font></b></li>
+
+<li>
+<b><font size=+1>Delete</font></b></li>
+
+<li>
+<b><font size=+1>Select All</font></b></li>
+
+<li>
+<b><font size=+1>Deselect All</font></b></li>
+</ul>
+
+<h3>
+Cut</h3>
+The records cut menu option deletes the selected records from this file
+and puts the contents of the deleted records into the clipboard.&nbsp;
+All the selected records are transferred to the clipboard as well as any
+required cross referenced records which are not included in the selection.&nbsp;
+This ensures that any pasted records will take with them the cross references
+that are needed.&nbsp; When the records are deleted, they are removed permanently
+from the file.&nbsp; They are overwritten with '%' characters, permanently
+removing the record information from the file.
+<h3>
+Copy</h3>
+Copy the information in the selected records into the clipboard.&nbsp;
+Any additional cross reference information is also copied into the clipboard.&nbsp;
+The records that are placed in the clipboard are passed as plain text.&nbsp;
+The records can thereby be pasted into any other application that shares
+the system clipboard.&nbsp; On the Windows operating system, this works.&nbsp;
+On Linux, the X windows system clipboard does not seem to be the same clipboard
+that Java accesses.
+<h3>
+Paste</h3>
+Paste takes the contents of the system clipboard and reads it as BibTeX
+records.&nbsp; If any records are found, they are added to the file.&nbsp;
+On addition, duplicate keys are checked for.&nbsp; If a duplicate key is
+found, then the user is asked to enter a new key.&nbsp; Selecting cancel
+in response to this operation results in the record not being added.&nbsp;
+If the key is changed, then any records with a cross reference pointing
+at this record will also have their key changed.
+<h3>
+Delete</h3>
+Delete removes the selected entries from the file.&nbsp; The selected records
+are replaced by TeX comment characters, '%'.&nbsp; Selecting delete removes
+the records permanently from the file.
+<h3>
+Select All</h3>
+Select the keys for all the records.&nbsp; When all the records are selected,
+cut, copy, paste, and delete operations can be performed on all the records
+in the file.&nbsp; Selecting this menu option will switch the selection
+mode to multiple if that has not already been done.
+<h3>
+Deselect All</h3>
+Deselct all the records in the file.&nbsp; This method is useful to ensure
+that records in a large file are not subject to undesired operations.
+</body>
+</html>
diff --git a/biblio/bibtex/utils/JavaBib/index.html b/biblio/bibtex/utils/JavaBib/index.html
new file mode 100644
index 0000000000..3b03cce7c3
--- /dev/null
+++ b/biblio/bibtex/utils/JavaBib/index.html
@@ -0,0 +1,47 @@
+<!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>
+<b><font size=+4>JavaBib III</font></b></h1></center>
+
+<ul>
+<li>
+<font size=+2><a href="describe.html">Description</a></font></li>
+
+<br>&nbsp;
+<li>
+<font size=+2><a href="docs.html">Documentation</a> - in process.</font></li>
+
+<br>&nbsp;
+<li>
+<font size=+2><a href="screen.html">Screen Shots</a></font></li>
+
+<br>&nbsp;
+<li>
+<font size=+2>Download</font></li>
+
+<br>&nbsp;
+<ul>
+<li>
+<font size=+2><a href="JavaBib.jar">JavaBib.jar</a> - run from command
+line with "java -jar JavaBib.jar".</font></li>
+
+<br>&nbsp;
+<li>
+<font size=+2>JavaBib.zip - MS Windows zip file, JavaBib.jar and the documentation.</font></li>
+
+<br>&nbsp;
+<li>
+<font size=+2>JavaBib.tar.gz - Gzipped tar file, JavaBib.jar and the documentation.</font></li>
+</ul>
+</ul>
+
+</body>
+</html>
diff --git a/biblio/bibtex/utils/JavaBib/screen.html b/biblio/bibtex/utils/JavaBib/screen.html
new file mode 100644
index 0000000000..484ff7491f
--- /dev/null
+++ b/biblio/bibtex/utils/JavaBib/screen.html
@@ -0,0 +1,29 @@
+<!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 Screen Shots</h1></center>
+
+<h3>
+Main Window</h3>
+<img SRC="JavaBib1.jpg" height=597 width=707>
+<p>The main window is where most of the work on BibTeX records is conducted.&nbsp;
+The menu bar provides a range of options, from opening new files to modifying
+the existing record.&nbsp; On the left, one can choose which records to
+view.&nbsp; Selecting a record updates the edit panel on the right.&nbsp;
+The control panel at the bottom of the window allows you to move between
+records and some shortcut buttons for record editing.&nbsp; The text field
+at the bottom of the control panel displays a LaTeX citation entry.&nbsp;
+This entry can be copied from this text field.&nbsp; Alternatively, it
+can be copied to the system clipboard by using the 'cite' menu.&nbsp; Unfortunately,
+on some systems Java does not access the same system clipboard as the application
+into which you might want to paste the entry.
+</body>
+</html>