# The &kbibtex; Handbook

Yuri
Chornoivan

    	yurchor@ukr.net

2004
2014
Thomas Fischer
2014-04-14
0.6
&FDLNotice;

&kbibtex; is a graphical &bibtex; editor and shell.

KDE
kbibtex
LaTeX
TeX
bibliography

## Preface

### Requirements

To run &kbibtex;, you need to have the following components installed on your system:

- &kf5-full; libraries.

- &latex;: high-quality document typesetting program. Most likely you want the &texlive; (or on older systems the &tetex;) package, if you are on a Unix-like system. It is an optional dependency, but without it &kbibtex; provides very limited functionality.

- bibtex2html collection of tools for translating from &bibtex; to &HTML; to enhance &kbibtex; entry previewing capabilities (optional dependency).

Most of these items as well as &kbibtex; itself might be included in your &Linux; distribution; please refer to your distribution documentation, or refer to your installation &CD; or DVD, for adding these packages to your computer.

### Intended Audience

This manual is intended for any individual, regardless of her or his experience with &latex;, &kde;, &kbibtex; or &Linux;.

Advanced users are not likely to read this manual, but all suggestions on documentation will be considered. If you would like to contribute to this project or the documentation, please consult the &kbibtex; web page.

## Introduction

### About &kbibtex;

&kbibtex; is an integrated environment for creating and editing bibliographies in &bibtex; format. &kbibtex; gives you the ability to use all the functionalities of &bibtex; in a graphical interface, giving you easy, immediate, and customized access to local and online bibliographies with ability of entries completing, compiling, previewing and searching.

#### About &bibtex;

&bibtex; is a program and file format designed by Oren Patashnik and Leslie Lamport in 1985 for the &latex; document preparation system Lamport86.

The format is entirely character based, so it can be used by any program (although the standard character set for accents is &tex;). It is field (tag) based and the &bibtex; program will ignore unknown fields, so it is expandable. It is probably the most common format for bibliographies on the Internet.

The &bibtex; program uses style files, a list of citations from &latex;, and a &bibtex; database to create a &latex; file listing the cited references. The idea of style files is that final copy in any journal-specific form can be done automatically.

An example of &bibtex; database entry:

    @article{PAM_doi:10.1007/BF00048294,
    	author = {Streitenberger, P. and Knott, John F.},
    	doi = {10.1007/BF00048294},
    	issn = {1573-2673},
    	journal = {{International Journal of Fracture}},
    	number = {3},
    	pages = {R49},
    	publisher = {Springer},
    	title = {{The calculation of crack opening area and crack opening volume from stress intensity factors}},
    	url = {http://dx.doi.org/10.1007/BF00048294},
    	volume = {76},
    	x-fetchedfrom = {SpringerLink},
    	year = {1995}
    }

#### &kbibtex; and &latex; Editors

&latex; code can be edited with a wide variety of tools from simple minimalistic text editors to powerful visual suites. For the comparison of &latex; editors, see this page.

&kbibtex; provides out-of-box integration with &kile; and &lyx; though it can be successfully used with any kind of &latex; editor.

### &kbibtex;'s Main Features

&kbibtex; allows you to do the following things:

- Enter a preamble that defines how special text should be formatted in your bibliography using Element New element New preamble menu item or Main Toolbar.

- Choose an entry encoding using Encoding item in Save as dialog or on the File Settings panel.

- Enter comments that are not taken in regard by &bibtex; using Element New element New comment menu item or Main Toolbar.

- Preview and save bibliography entries in various formats (Source (&bibtex;), Source (RIS), Wikipedia, standard (&XML;/XSLT), fancy (&XML;/XSLT), and abstract-only (&XML;/XSLT)) using Reference Preview panel. Additional preview styles become available when bibtex2html is installed.

- Search for the bibliography entries data in online databases using Online Search panel.

- View local or remote (online) resources (such as files) linked in the &bibtex; entry using Document Preview panel.

- Find and fix duplicate entries in bibliography using Edit Find Duplicates menu item or Main Toolbar.

- Import your Zotero library using Zotero panel.

## Quickstart

### Writing a Bibliography File for Beginners

After the first run, &kbibtex; will propose to make it the default editor for bibliography formats. We recommend you to do so. If for some reasons you will decide to reconsider please remove the strings with `kbibtex` substring from `mimeapps.list` file in `.local/share/applications` folder of your home folder.

Then you will see a window that looks similar to this:

&kbibtex; window after the first start
&kbibtex; window after the first start

To start a new bibliography document press the New button on the right panel, the New button on the toolbar or choose the &Ctrl;N File New menu item.

Now it is time to add some entries.

Users of &kbibtex; have two choices when adding a new entry: they can use the Online Search panel to find entry data online or they can write the code by hand.

Let's try to add a book entry manually.

1. Choose Element New element New entry from the &kbibtex; menu. &kbibtex; should open Edit Element window.

   &kbibtex; element's editing window
   &kbibtex; element's editing window

2. Choose Book from the Type: drop down list.

3. Enter `Lamport86` into the Id: field.

   The Id is used for referencing the bibliography entry in your main document.

4. Go to the Title tab and enter `LaTeX: A Document Preparation System` into the Title: text box.

5. Go to the Author/Editor tab, click on Add button and enter `Lamport, Leslie`.

6. Go to the Publication tab then enter `1986` into the Year: text box and `Addison-Wesley` into the Publisher: text box.

7. Click OK.

8. Choose &Ctrl;S File Save menu item and save your bibliography file as `example.bib` in your to-be-written paper folder.

### Using the bibliography in your &latex; document

To actually use the bibliography in your paper, you need to add the following commands in your &latex; file (these commands are usually can be found at the end of the document - where the References section to appear):

    \bibliography{foo}
    \bibliographystyle{plain}

Here, foo is the name of your `bib` file created with &kbibtex; and plain is the name of bibliography style.

There is a plenty of specific bibliography styles. Please consult your publisher for the one to choose or try and find the one that suits the best for your purposes.

Below is a list of some generic styles available everywhere:

plain

  normal style, listed in alphabetic order and labeled numerically

unsrt

  same as plain except entries appear in order of citation

alpha

  same as plain except entry identifiers are used

abbrv

  same as plain except uses abbreviations for first names, month names, and journal names

So you can use your &latex; editor's capabilities (please consult the editor documentation for this) or just enter the following code in a generic text editor then save the file with `tex` name extension.

    \documentclass{article}
     \begin{document}
     \bibliographystyle{plain}% Choose a bibliographic style
     Test file with a reference (see~\cite{Lamport86}).
     \bibliography{example}
     \end{document}

For our testing purposes, let this file be named `example.tex`.

Please save this file to the same folder as your `example.bib`.

Now that you have the basis for a document, you have to run both latex and bibtex to process it.

First, you should run latex (to create a foo.aux file, which bibtex reads). Then run bibtex once to get some of the citations and create a `bbl` file. Then run latex again so that the cross references between the text file and the bibliography are correct. You may want to repeat running bibtex and latex on the file to make sure that all cross references are correct. Be warned that adding/deleting citations and sources will require running bibtex again.

Thus, the following commands can be used to compile the document from console:

    latex example
    bibtex example
    latex example
    latex example

If you are using some advanced &latex; shell like &kile; or &lyx;, there is no need to worry about running all these commands from console emulator. Just use a hot key (&Alt;6 in &kile;) or a toolbar button to see the results.

Now, you can see the results as a &DVI; or &pdf; file (the format depends on your configuration), stored in the same folder as your source files.

Congratulations! You have just created your first document with &bibtex; bibliography.

## &kbibtex; Interface

### &kbibtex;'s Panels

The main functionality of &kbibtex; is available through its nine panels. It is possible to rearrange these panels or even detach them from the main window by clicking with &LMB; on the panel's header and dragging it to the new place.

You can make the &kbibtex; panels visible or hide them using the Settings Show Panels submenu. It is enough to check the panel's item to make it visible or uncheck it to hide the panel.

#### List of Documents Panel

The List of Documents panel allows to switch between the opened bibliography documents (Open Files tab), open recently used documents (Recently Used tab), open your main bibliography documents (Favorites tab), or browse your computer file system to find bibliography documents (Filesystem Browser tab).

To add a bibliography file to favorites select it on any tab except Favorites, click with &RMB; and choose Add to Favorites. To remove the bibliography from favorites select it on Favorites tab, click with &RMB; and choose Remove from Favorites.

List of documents panel List of documents panel

#### List of Values Panel

The List of Values panel can be used to easy up viewing statistics on usage of values in the entries fields and batch editing of these values.

The upper drop down box is used to choose the bibliography field to display statistic data (a count of entries with the same value for the field) on the lower list.

You can click with &RMB; on an entry in the lower list to access the batch editing capabilities. It is possible to Replace all occurrences of the value, Delete all occurrences of the value, Search for selected values using the Filter Toolbar, Add value to selected entries, Replace value of selected entries or Remove value from selected entries (some entries should be selected in the main entry list first).

List of values panel List of values panel

#### Statistics Panel

The Statistics panel is designed to display a comprehensive list of statistical information about the current bibliography document.

Statistics panel Statistics panel

#### Reference Preview Panel

The Reference Preview panel is used to preview and save in &HTML; format the currently selected bibliography entry.

Reference preview panel Reference preview panel

It is possible to preview the reference as Source (&bibtex;), Source (RIS), Wikipedia, standard (&XML;/XSLT), fancy (&XML;/XSLT), and abstract-only (&XML;/XSLT) formats. Additional options become available when bibtex2html is installed.

When you click on the elements of the reference in &XML;-based format &kbibtex; will apply the corresponding filtering to the bibliography list.

Click the Open button to open the reference in the default Internet browser. The Save as &HTML; button can be used to save the reference in &HTML; for further use on your website.

You can click with &RMB; on the panel to select Reload to update the reference according to the latest changes in the entry.

#### File Settings Panel

The File Settings panel can be used to define some parameters of the `bib` file of the current bibliography.

File settings panel File settings panel

It is possible to select Encoding, String Delimiters, Comment Quoting, Keyword Casing, and Person Names Formatting.

By default &bibtex; will lowercase all intermediate words in sentences. Check Protect Titles check box to protect the case in the entry titles.

#### Online Search Panel

The Online Search panel can be used to perform a search in the Internet bibliography databases to find the needed entries or to obtain the complete set of data for a manually entered entry.

Online Search panel Online Search panel

The entries can be searched by Free text, Title, Author, or Year. The number of results shown on the Search Results panel can be tweaked using the Number of Results spin box.

Click the Use Entry button to fill the search criteria fields from the currently selected bibliography entry. This way you can complete the existing entry with the data from the Internet databases. The Search button can be used to start the search.

&kbibtex; can perform a search in the most popular Internet databases. To select the set of the databases for your search switch to the Engines tab or click with &LMB; on the change link on the Query Terms tab.

To visit the database homepage in the Internet click with &RMB; on its entry in the Engines tab and select Go to Homepage.

#### Zotero Panel

The Zotero panel can be used to import your Zotero library.

Zotero uses specialized browser add-ons to save bibliography entries from Internet pages. The data are stored in an online database that can be reached from anywhere. Zotero documentation can be found here.

Zotero panel Zotero panel

Click the Get Credentials button on Credentials tab to start the Zotero authorization wizard. Follow the instructions to allow &kbibtex; access your Zotero library.

Then the Load bibliography button can be used to download data from Zotero library.

To access the downloaded library entries double-click on the corresponding item on Collections or Tags tabs. The entries that satisfy the chosen criteria will be shown on the Search Results panel.

#### Search Results Panel

The Search Results panel is used to handle the search results obtained using Online Search panel.

Search Results panel Search Results panel

Click the Import button to import the currently selected search result into your bibliography.

To access other actions for the currently selected search result click on it with &RMB;. From the opened menu you can review the result (View Element item) or copy it for further pasting in &bibtex; format elsewhere with &Ctrl;V (Copy item).

#### Element Editor Panel

The Element Editor panel can be used to edit the currently selected bibliography element.

Element Editor panel Element Editor panel

Click the button to select a suggested identifier for the element.

Enter the respective data in the editor fields. The field data format can be switched between Text, Reference and Source Code using the drop down box to the left of the text box.

Click the Options button to open a drop down menu with two items.

The Show all fields item can be used to show or hide all empty fields of the current element.

It is possible to switch keyboard focus between the fields using the &Tab; key. So the second menu item, Tab key visits only editable fields, can be used to switch on and off navigation between editable fields only.

Click the Check with &bibtex; button to preview the editing entry as it will be shown in the compiled &pdf; file.

Check the Automatically apply changes box to have all your changes automatically applied to the entry without the need to click the Apply button.

Click the Reset button to revert all your changes.

#### Document Preview Panel

The Document Preview panel can be used to preview pages or documents linked with the currently selected bibliography entry.

By default, the Document Preview panel can be opened by pressing &Ctrl;&Shift;D keyboard shortcut.

Document Preview panel Document Preview panel

Click the button to toggle between local files only and all documents including the remote ones.

Click the button to open the page or the document in the default external application.

The address drop down box can be used to switch between the pages and documents.

### &kbibtex;'s Toolbars

&kbibtex; has two completely customizable toolbars located on the top part of its window.

More information on customizing the toolbars can be found in the corresponding section of &kde; Fundamentals manual. Below is the short description of the default buttons of &kbibtex; toolbars.

#### Main Toolbar

Main Toolbar Main Toolbar

The default Main Toolbar of &kbibtex;.

- New: creates a new bibliography document.

- Open: opens the generic &kde; Open/Save dialog to open some existing bibliography to edit.

- Close: closes the currently active bibliography document.

- Save: saves the currently active bibliography document.

- Save as: allows to save the currently open bibliography document under the new name using the generic &kde; Open/Save dialog.

- New element: allows to create the new entry, comment, preamble or macro in the current bibliography document.

- Find Duplicates: finds and fixes duplicate elements in the current bibliography document.

- Send to &lyx;/&kile;: sends a reference on the currently selected bibliography entry to &lyx; or &kile;. More on this in the corresponding chapter of this manual.

#### Filter Toolbar

Filter Toolbar Filter Toolbar

The default Filter Toolbar of &kbibtex;.

The simplest method to navigate in large bibliographies is to use the Filter toolbar: &kbibtex; will filter the displayed list according to your input. If you are searching for some element, but you do not know its exact position in the list, just type some letters from its data in the Filter text box.

When you enter the first few letters, you will see the list changing. The more letters you enter, the more reduced list you will see. This filtering occurs immediately as you type.

If you look at the right part of the Filter toolbar, you will notice two drop-down menus. The drop-down menus were designed for you to be able to quickly tailor filtering criteria to your needs. The first drop-down menu is used to define matching mode (any word, every word or exact phrase). The second is to define the field where the filtering should be done. You can choose any field or select a field to narrow down the list of the results in large bibliographies.

There are also two buttons on this toolbar:

- Include &pdf; files in fulltext search: allows you to include fulltext &pdf; in the filtering.

- Reset filter criteria: resets filtering criteria.

### &kbibtex;'s Menus

&kbibtex; follows the standard &kde; menu scheme. So it has many menu entries that are common for all &kde; applications. More information on these menu entries can be found this help section.

Below, you can find descriptions for &kbibtex;-specific menu entries.

Edit Delete

  Delete currently selected element in the bibliography list.

Edit Find Duplicates

  Allows you to find and remove duplicates in the currently opened bibliography.

Element New element New entry

  Open Edit Element window to enter a new bibliography entry.

Element New element New comment

  Open Edit Element window to enter a new comment that are not taken in regard by &bibtex;.

Element New element New macro

  Open Edit Element window to enter a new macro.

Element New element New preamble

  Open Edit Element window to enter a new bibliography preamble that defines how special text should be formatted in your bibliography.

&Ctrl; E Element Edit Element

  Open Edit Element window to edit the currently selected bibliography element.

&Ctrl; D Element View Document

  Open local or remote document for the currently selected entry in the bibliography list.

  The link to the document can be added or edited using External tab of Edit Element window.

  External documents tab of entry's editing dialog
  External documents tab of entry's editing dialog

  The Add button can be used to add a link to remote page.

  The Add file... drop down box is used to select some local file and add a reference or the whole file to the current bibliography.

  If you click on the currently selected item will be cleared.

  Click on the button to open the document link in the browser.

  Click on the button to remove the currently selected document item.

  To rearrange items in the document list use and buttons.

  Eventually, the button can be used to save remote documents locally.

Element Find &pdf;...

  Try to find some &pdf; documents for the currently selected bibliography entry in the Internet.

  Find &pdf; dialog
  Find &pdf; dialog

  You can Ignore, Download or just Use &URL; only for the entry.

Element Format entry ids

  Allows you to format identifiers for the currently selected bibliography entries according to the default formatting.

  The default identifiers formatting can be defined using Id Suggestions page of &kbibtex; configuration dialog.

Element Color

  Allows you to select a color label to the currently selected bibliography entries or remove such label (No color).

  The color labels can be configured using Color & Labels page of &kbibtex; configuration dialog.

Element Send to &lyx;/&kile;

  Send references to the currently selected bibliography entries to &lyx; or &kile;.

Settings Configure &kbibtex;...

  Open &kbibtex; configuration dialog.

### &kbibtex;'s Configuration Dialog

Several &kbibtex; parameters can be configured via the Preferences dialog. This dialog can be opened using the Settings Configure &kbibtex; menu item. Below you can find a description of &kbibtex; configuration pages.

Click the Defaults button to reset all items to their default values.

The Reset button can be used to discard all current configuration changes without closing the Preferences window.

#### General Configuration

General configuration
General configuration

This configuration page allows you to change the default Person Names formatting which will be automatically applied to the names entered in the Element Editor dialog.

#### Keywords Configuration

Keywords configuration
Keywords configuration

This page can be used to edit keyword list. The keywords applied to the bibliography entries with Element Editor are useful to structurize your bibliography. Filtering by keywords can give you a fine-grained results by topics.

The Add button can be used to add a keyword to the list.

Click on the Remove button to remove the currently selected keyword item.

#### Color & Labels Configuration

Color & Labels configuration
Color & Labels configuration

Color labels are another useful way to structurize your bibliography. This configuration page can be used to define the labels and their colors.

The Add button can be used to add a label to the list.

Click on the Remove button to remove the currently selected label.

Double click on an item in the Color or Label column to start editing it.

#### Id Suggestions Configuration

Id suggestions configuration
Id suggestions configuration

This configuration page is used to handle identifier suggestion schemes for Element Editor. You can add, edit, remove and rearrange the schemes using the respective buttons to the right of the suggestions list.

Click the Toggle Default button to switch the default id suggestion scheme to the currently selected item. This button can be used to define format for the Format entry ids action.

#### User Interface Configuration

User interface configuration
User interface configuration

Using this configuration page you can make &kbibtex; show or hide comments and macros in the bibliography list, choose bibliography system (&bibtex; or &biblatex;) and define what to do when you double-click an element in the bibliography list (Open Editor or View Document).

&biblatex; is a reimplementation of &bibtex;. With &biblatex; the formatting of the bibliography is entirely controlled by &latex; macros, not `bst` files. It supports subdivided bibliographies, multiple bibliographies within one document, and separate lists of bibliographic shorthands. Bibliographies may be subdivided into parts and/or segmented by topics. Just like the bibliography styles, all citation commands may be freely defined. The &biblatex; package is completely localized and can interface with the babel package. From &biblatex; documentation.

Also &biblatex; can use biber as a backend. With &biblatex; it is possible to use UTF-8 symbols in bibliography entries.

So you can use &biblatex; to create sophisticated bibliographies.

#### Saving and Exporting Configuration

Saving and exporting configuration
Saving and exporting configuration

This page allows you to choose a &latex; command (&eg; `\cite{...}`) which will be used as a wrapper for the reference copied with &Ctrl;&Shift;C Copy Reference item of popup menu from the bibliography list.

It is also possible to make &kbibtex; determine &lyx; data pipe automatically by checking the corresponding box.

When Detect &lyx; pipe automatically item is not checked, you can add the pipe address manually in the text box Manually specified &lyx; pipe or select it using the generic &kde; Open/Save dialog by pressing the button to the right of the text box.

Eventually, you can configure backups here. It is possible to select the backup subject (Local files only, No backups or Both local and remote files) using Backups when saving drop down box and the number of backups to store.

#### &pdf; & Postscript Configuration

&pdf; & Postscript configuration
&pdf; & Postscript configuration

This configuration page can be used to choose some options for previewing of &kbibtex; entries. You can select Paper Size, language for babel &latex; package and the bibliography style.

## Advanced Usage

### Cross References

Cross references allows you to save some time by creating links between parent entry (can be treated as a proceedings or collection of articles) and children entries (reports or articles).

To create a cross reference just add its identifier in the Cross-Reference: field of the entry's Publication tab.

Publication tab of entry's editing dialog
Publication tab of entry's editing dialog

You can either enter the identifier directly or click on the button to choose it from the list of available identifiers.

### Macros

Suppose your bibliography contains many references to the same journal and you do not want to enter its title over and over again. Then you can define a macro for the journal title.

Let's say, we want to define a macro efm for Engineering Fracture Mechanics. Then we should do as follows:

1. Choose Element New element New macro menu item.

2. Enter an identifier (abbreviation) for the title in the Id: text box. The default identifier is `New1`. We should enter `efm`.

3. Choose (Plain Text). The other option, (Source Code) can be used if you want to insert some macro with &latex; commands in it.

4. Enter `Engineering Fracture Mechanics` in the Value: textbox.

   Defining macro
   Defining macro

5. Click on the Apply button.

6. Optionally, switch to the Source tab to inspect the code of the macro.

   Defining macro (source code)
   Defining macro (source code)

7. Click on OK button.

The same procedure can be used to fix the titles, author and month names, &etc; according to abbreviation rules of your publisher for the entries from online databases. By default, these rules (macros) should be defined in the bibliography style files (`bst`).

## Integration with &kile; and &lyx;

&kbibtex; can be easily integrated with common &latex; editors, namely &kile; and &lyx;.

### Integration with &kile;

&kile; is a &tex; and &latex; source editor and shell.

&kbibtex; is a default viewer/editor for &bibtex; files in &kile;, so there is no need for additional configuration.

To add selected citations from bibliography files start &kile;, open some &latex; file, place the cursor there you want to add the citation, then switch to &kbibtex; window, select elements in the element list and choose Element Send to &lyx;/&kile; or use the Send to &lyx;/&kile; element's context (&RMB;-click) menu item.

The citations will be inserted as `\cite{element identifiers}` at the cursor position in the current &kile; document.

### Integration with &lyx;

&lyx; is a document processor that encourages an approach to writing based on the structure of your documents (WYSIWYM) and not simply their appearance (WYSIWYG).

&kbibtex; can be integrated into &lyx; via &lyx; input/output pipe.

1. First, you have to configure &lyx; to use the pipe. Choose Tools Preferences from &lyx; main menu. Open Paths page and enter some path (&eg; `~/.lyx/lyxpipe`) into the LyXServer pipe text box.

   &lyx; configuration
   &lyx; configuration

2. Click Save to save the changes.

3. Choose Tools Reconfigure to reconfigure &lyx; and restart it.

4. To add selected citations from bibliography files, open some document, place the cursor there you want to add a bibliography and select Insert List / TOC&bibtex; Bibliography... from the &lyx; main menu.

5. Press Add... then Browse.... Point &lyx; to a &kbibtex; `bib` file. Click on Add then click on OK.

6. Then place the cursor where you want to add the citation and switch to &kbibtex; window. Select elements in the element list and choose Element Send to &lyx;/&kile; or use Send to &lyx;/&kile; element's context (&RMB;-click) menu item.

7. The citations will be inserted as a reference at the cursor position in the current &lyx; document.

## Credits and License

&kbibtex;

Program copyright © 2004-2014 Thomas Fischer fischer@unix-ag.uni-kl.de

Documentation copyright © 2013 Yuri Chornoivan yurchor@ukr.net

&underFDL; &underGPL;
Lamport86 Leslie Lamport

### Latex: a document preparation system

1986
Addison-Wesley Publishing Company

&documentation.index;