Installing and Using CiteMaker

Select BibTeX Database

Use the Select BibTeX Database (shortcut Esc+sd ) menu item to inform CiteMaker of the location of your BibTeX database file. This file must have an extension of .bib or .BIB . You must select a database file before you can insert citations into your main document. CiteMaker will prompt you for this value if it discovers you have no database selected when you attempt to insert a citation.

Take care when modifying this value after inserting citations into your document. BibTeX will expect any existing citations from the old database to appear in the new database as well; BibTeX will issue error messages for citations it cannot find in the database.

Note: If you frequently keep your .bib files in a particular directory, you can specify this location through the use of the BIBDBASEDIR environment variable, as shown below:

BIBDBASEDIR=c:\docs\bibfiles

Use the appropriate procedures for your operating system to set this environment variable.

Note that setting this variable merely controls the default directory which appears when the Select Database menu item is chosen; you may chose a file in an alternate location via the dialog box. Use of the BIBDBASEDIR environment variable is optional.

Select BibTeX Style File

Use the Select BibTeX Style File (shortcut Esc+ss ) menu item to inform CiteMaker of the location of your BibTeX bibliography style file. This file must have an extension of .bst or .BST . The style file controls the format of the bibliography entries and citations generated by CiteMaker .

CiteMaker has been tested with the following style files.

Most style files work with no modifications. Style files that rely on additional processing by LaTeX may require modification. See Modifying Bibliography Style Files .

You must select a BibTeX style file before you can insert citations into your main document. CiteMaker will prompt you for this value if it discovers you have no style file selected when it attempts to format a newly entered citation.

Note: If you frequently keep your .bst files in a particular directory, you can specify this location through the use of the BIBSTYLEDIR environment variable, as shown below:

set BIBSTYLEDIR=c:\docs\bstfiles

Use the appropriate procedures for your operating system to set this environment variable.

Note that this merely controls the default directory which appears when the Select BibTeX Style File menu item is chosen; you may chose a file in an alternate location via the dialog box. Use of the BIBSTYLEDIR environment variable is optional.

Select Reference Page Template

Use the Select Reference Page Template (shortcut Esc+sd ) menu item to inform CiteMaker of the location of your CiteMaker template file. The template file contains FrameMaker paragraph and character formats which specify the appearance of the bibliography entries generated by CiteMaker . The default template file (named template and located in CiteMaker 's work subdirectory) is automatically selected for you when you begin working with a new document. Using the Select Reference Page Template menu item is necessary only when you wish to override this choice.

For information on customizing the template file, see Customizing the Template File .

Insert Citation

Use Insert Citation (shortcut Esc+ic ) to add a citation to your document. The new reference will be placed at the location of the current insertion point. (If a range of text is highlighted when a reference is inserted, then the beginning edge of the selected text is treated as the insertion point.)

After the Insert Citation action is selected, the following dialog box will appear:

You should specify a string to be used in searching your database. CiteMaker will select all entries in the database containing the specified string in any data field. (Fieldnames in the database such as "Title" and "Page" are ignored for this search.). The search is case-insensitive. Whitespace may be included (e.g., when searching for phrases), but it must match exactly like any other literal text.

Note: CiteMaker uses Perl to search the database. Perl regular expression syntax (including wildcards, quantifiers, etc.) may be used for a more sophisticated search. For example, the diagram above shows alternation being used to search for the strings "davis" or "davidson". Care must be taken with sequences beginning with a backslash (\), since FrameMaker uses such sequences to represent special characters in dialog boxes. See the FrameMaker Quick Reference for more information.

After completing the search, CiteMaker will display a dialog box like the one shown below:

Each entry in this list box represents a database entry which matched the search criteria. The entries show the database key of the entry, followed by its title. Highlight the entry you wish to cite and click OK. This will bring up a confirmation dialog as shown below:

This dialog shows the selected database entry as it appears in the database. If you wish to insert this citation in the document, click Insert at this point. Clicking Reject will take you back to the previous list box to allow the selection of a different matching entry. (Clicking Cancel on the list box will cancel the insertion process altogether.)

By default, CiteMaker encloses lists of references in brackets and separates citations within a list with commas as shown below:

[reference] [reference1, reference2]

The symbols beginning, ending, and separating citation lists are specified by the FrameMaker variables ZZ_BIB_OPEN , ZZ_BIB_CLOSE , and ZZ_BIB_SEP. You can modify the these values via the Special->Variable menu item to customize the appearance of the citation lists. Any modifications to these values will be saved with the document; they will remain in use until they are modified again.

Delete Citation

Use the Delete Citation (shortcut Esc+dc ) to remove a citation from your document. Click on the desired reference to highlight it, then select the menu item to delete the reference. (Clicking on a citation separator will delete the citation before the separator; clicking on the opening and closing citation list symbols will delete the first and last citations in the list respectively). CiteMaker will automatically delete any appropriate citation list symbols if necessary.

Note: It is recommended that you always use the Delete Citation menu item to remove citations. It is possible to remove citations in the same manner as you would delete other text; however, care must be taken to delete the appropriate surrounding symbols by hand in this case. CiteMaker automatically checks the syntax of your document whenever it is saved in order to verify that all the citation lists are correctly formatted. If you need to insert a new citation list symbol which was accidentally deleted, use the Special->Variable menu item to insert the appropriate variable as described above. Do not merely type in the text representation of the symbol, as this will not be recognized by CiteMaker . Text containing citations may be cut, copied, and pasted as normal within your document, as long as all the citation lists remain correctly formatted.

Toggle Citation Updates

By default, CiteMaker automatically updates the appearance of all citations in your document each time a citation is inserted or deleted. This requires additional processing time since CiteMaker must invoke BibTeX to calculate the appearance of the citations. You can control whether or not to perform this citation update by selecting the Toggle Citation Updates (. If you decide to turn citation updates off, you can force an update of the citations in your document at any time by selecting the Update Citations menu item.

If you insert a citation into your document while citation updates have been turned off, then the citation will be represented with the value of the corresponding BibTeX database key. (If citation updates are currently enabled, the key value will also appear briefly for a newly inserted citation while CiteMaker is calculating its appearance.)

Note: Since the appearance of the citations depends on the bibliography style, you must have a bibliography style file defined whenever CiteMaker attempts to update the citations. CiteMaker will automatically prompt you for a style file if none is currently selected. In addition to the circumstances described above, CiteMaker automatically updates the appearance of the citations in your document and generates a new reference list whenever you save your document (even if citation updates have been turned off).

Generate Bibliography

You can generate a new reference list based on the works you have cited in your document by selecting Generate Bibliograph (shortcut Esc+gb ). CiteMaker creates the reference list as a separate file whose name is derived from the main document filename by appending -bib to the base name and retaining the original extension (if any). Thus, a main document named thesis.fm generates a reference list file named thesis-bib.fm . The generated file is placed in the same directory where the main document file resides.

Note: it is necessary to have a bibliography style file defined in order to generate the reference list. CiteMaker will automatically prompt you for a style file if none is currently selected.

A convenient way to combine the main document and its reference list is to import the reference list file into the main document file at the appropriate place via the File->Import->File menu item. If you choose the Import By Reference option, then you only need to perform this operation once; any changes in the bibliography document will be reflected back in the main document.

Note: CiteMaker automatically saves both your main document (which could change due to citation updates) and the reference list file whenever the reference list is generated. Immediately after generating the reference list, the appearance of the main document will reflect any citation updates which occurred. However, even if you have imported the reference list file by reference, the appearance of the reference list will not reflect the most recent reference list update. Select the File->Revert to Saved menu item to update the appearance of the reference list.

CiteMaker invokes BibTeX when generating the reference list and when updating the appearance of citations in your document. During these operations, BibTeX may potentially generate error or warning messages. When this occurs, CiteMaker will display a dialog box alerting you to this situation. You can obtain the specific diagnostic information by examining the BibTeX log file work.blg . This file is copied to the directory where your main document resides each time BibTeX is invoked whether or not BibTeX generates any errors or warnings.