CiteInPages Comment | Log in | Print | Subscribe to this page

CiteInPages is a suite of Applescripts that allow the open source reference manager BibDesk to be integrated with Apple's word processor, Pages (v. 3, 4, or 5.2; if you're interested in Word integration, see BibFuse). Using BibDesk templates, "working citations" containing BibTeX cite keys in a defined format can be dragged, pasted, or inserted by script from BibDesk into Pages documents as the documents are edited. CiteInPages replaces these working citations with numbered or author-date in-text citations, creates a correctly-ordered bibliography based on a BibDesk template, and pastes the bibliography into the Pages document. It works on native Pages files through Pages itself and does not require converting the file to rtf, which may cause some loss of information, inserted images or layout features. CiteInPages is freely available for use and modification with a BSD license.

Download: Two versions are available, CiteInPages5 for Pages 5.2 and up, and CiteInPages for Pages 3 & 4.

  • CiteInPages5 v. 1.01 (190K zip file containing three scripts, a citation template, two bibliography templates, and installation instructions). CiteInPages5 requires Pages 5.2+ and BibDesk 1.3.14 or beyond (tested with OSX 10.9.4 and Yosemite beta). The script files are the only difference between CiteInPages5 and CiteInPages, so upgrading is just a matter of adding the new scripts to the BibDesk scripts folder. The CiteInPages5 scripts should be able to coexist with the previous CiteInPages scripts if you're using both versions of Pages, as long as only one version of Pages is running at a time.
  • CiteInPages v. 1.05 (220K zip file containing five scripts, a citation template, two bibliography templates and installation instructions). Version 1.05 requires Pages 3 or 4 and BibDesk 1.3.14 or beyond. It is not compatible with Pages 5. CiteInPages runs on OSX 10.4 to 10.9 and Pages from iWork '08 and '09. File name extensions should be set to display in the Finder when using CiteInPages (see note #15 in the Notes section below). CiteInPages is not compatible with internal footnotes in Pages 3 but is compatible with footnotes though not automatic tables of contents in Pages 4 (see note #8 in the Notes section below).

Below: Summary - Installation - Configuration - Usage - Error alerts - Notes - Contact
Also: TemplateNotes - Other templates & scripts

Changes from CiteInPages5 v. 1.0 to 1.01. An issue was fixed with clipboard text transfer that caused Pages 5.2 to hang when pasting in the bibliography list from BibDesk only when the script was started from the BibDesk script menu. Also, a minor workaround was added to accommodate the failure of OSX Yosemite beta to return a colon at the end of paths to Apple "package" files. (Thanks to Daniele Pontillo).
Changes from 1.05 to CiteInPages5 v. 1.0. Applescript support in Pages 5.2 remains limited compared to previous versions of Pages. Most text formatting is still inaccessible, so CiteInPages5 cannot create superscript or italic in-text citations (sorry). Also bibliography list numbering and formatting like hanging indents, which were previously automatic, now must be done manually. In practice, this is relatively easy (select the new bibliography and choose "Numbered List" style or set the paragraph formatting). Also the insertion point in Pages is inaccessible to Applescript so the script previously available for inserting selected BibDesk references at the insertion point in Pages is not included in CiteInPages5. References are still easy to drag or copy/paste into Pages using the supplied inTextCitation.txt template. The previous text indexing problems when footnotes and automatic tables of contents were present in Pages 3 & 4, respectively, appear to be corrected in Pages 5.2 (see note #8 in the Notes section below).

- OldCIPReleaseNotes -

Summary

BibDesk is an excellent open source BibTeX reference database manager that was designed to work with LaTeX/BibTeX publishing systems. However, it is also a capable general-purpose reference manager with very good import/export capabilities, and a flexible templating system that allows citations in defined formats to be dragged or pasted from BibDesk into text editing programs and for bibliography lists to be generated in defined formats. BibDesk is also Applescriptable, with an Applescript menu from which scripts can be chosen to run.

Pages is a word processor from Apple with a number of nice features, including page layout capabilities, ability to read and export Word documents and, in versions 3 and later, Word-compatible change tracking and commenting. Some find it a more comfortable editing environment than Word. However, until recently reference managers have not worked smoothly with Pages, and reference manager support is still limited. This decreases the usefulness of the program for academic writing. Furthermore, Pages 5 was an extensive rewrite of the program that was released with only rudimentary Applescript support. Pages 5.2 has increased Applescript support and there is hope that future versions of Pages will equal and surpass the level of scripting support available in the program prior to version 5.

The CiteInPages scripts are designed allow BibDesk to be used as an integrated reference manager for Pages. When the bibliography scripts are selected from BibDesk's Applescript menu, they duplicate the frontmost open Pages document, scan through the duplicate and replace "working citations" containing BibDesk cite keys with numbered or author-date citations in the text, assemble the cite keys into a correctly-ordered list, extract a corresponding formatted bibliography from the frontmost open BibDesk database using a specified BibDesk template, and insert that bibliography into the duplicate document at the end or in another specified location (the original document is unchanged). All document processing is handled within Pages and thus the scripts allow replacing citations and inserting bibliographies into Pages documents without the problems associated with converting the documents to other file formats. CiteInPages supports sequentially-numbered, alphabetically-numbered and author-date citation styles in three separate scripts. In CiteInPages for Pages 3 & 4 a script is also provided to insert selected citations to references in BibDesk at the insertion point in Pages. This functionality isn't available yet in Pages 5, so citation insertion in CiteInPages5 is via copy/paste or drag & drop using the provided working citation template which is editable.

Two bibliography template files are supplied with CiteInPages. By default, the "numbered" script uses a template based on the AMA style (a modified Vancouver) and the "alpha-numbered" and "author-date" scripts use a template based on the APA style. Both templates provide layout for articles, books, in-books, in-proceedings, conference presentations, tech reports, electronic references, web pages and generic layout for other types of references. Templates can be edited, new templates can be created and in-text citations can be adjusted to support other bibliographic styles.

Installation notes (also see the stepwise instructions in the download)

The download (above) contains the CiteInPages5 or CiteInPages Applescripts, the working citation template that I use, and two styled bibliography templates to help start things off. Step-by-step installation instructions are included as a readme text file in the download. In summary, the CiteInPages scripts (CiteInPages numbered.scpt, CiteInPages alpha-numbered.scpt, CiteInPages author-date.scpt and CiteInPages text citation.scpt) should be placed in BibDesk's Scripts folder:

~/Library/Application Support/BibDesk/Scripts

For CiteInPages only, not CiteInPages5, use the version of the text citation script that is appropriate for your version of Pages (Pages 3 from iWork '08 or Pages 4 from iWork '09). You can change the name of the script to remove the reference to Pages after you copy it into the Scripts folder. This script is not included in CiteInPages5.

The template files (inTextCitationTag.txt, CIP-AMAstyle.rtf and CIP-APAstyle.rtf) should be placed in BibDesk's Templates folder:

~/Library/Application Support/BibDesk/Templates

The scripts can be renamed. The templates should not be renamed unless corresponding changes are made in the template properties at the top of each script (see Configuration below). Scripts can also be re-directed to use other templates by changing the template properties in the scripts as described in Configuration below.

After copying the files into the appropriate folders, CiteInPages users (not CiteInPages5) can select references in BibDesk and copy them to Pages documents by choosing "CiteInPages text citation" from BibDesk's scripts menu. CiteInPages5 and CiteInPages users can also drag-and-drop or copy/paste formatted in-text working citations from BibDesk to Pages by adding the in-text citation template file (inTextCitationTag.txt) as a text export template in BibDesk's Templates preference pane, and setting the Default Format popup menu under "Copying and Dragging" in BibDesk's Citations preference pane to "Template" and the Template popup menu just below to the name of the new template (see BibDesk's help file or the link above for specific instructions about adding and selecting templates). Step-by-step instructions for installing this file as a template in BibDesk are provided in the readme file included in the download.

Configuration

CiteInPages is distributed with default values that should allow it to operate without additional configuration if the supplied scripts and templates are installed according to the included directions. For those wishing additional flexibility, the following sections explain how template files can be edited by users, and how the properties at the top of the scripts can be edited by the user to target the scripts to other templates or control other aspects of formatting and document processing.

Working with templates

The citation template specified in the file inTextCitationTag.txt defines the content and delimiters of the in-text "working citations" that are pasted into Pages when a reference is inserted by script or copied or dragged from BibDesk (both the author-date and numbered scripts can use the same working citation template). Although the built-in TeX citation command that is the default drag format from BibDesk can also be used for in-text citations, there are several drawbacks to this (see notes below). The citation template file inTextCitationTag.txt contains:

 [* <$publications.citeKey.@componentsJoinedByComma/> *]

This string uses "square bracket - asterisk - space" for the leading working citation delimiter and the reverse for the trailing delimiter. There is a space before the first character so that a space will be inserted when citations are dropped directly behind a text character. If other delimiters are desired, this file can be edited in a text editor to replace the default delimiters: be sure to save as plain text and change the script properties tagStart and tagEnd to match the starting and ending delimiters in each script that will process in-text citations inserted with this template. Delimiters must be unique strings dedicated to marking citations but need not be the reverse of each other. Start and end delimiters for working citations must be different from each other and must be different from those for final formatted citations. The command in the angle brackets inside the delimiters specifies a list of one or more BibDesk cite keys separated by commas. It should not be changed because the scripts assume this format for working citations. The format of the final citations is not controlled by this template; final citations are coded into the scripts and can be varied using script properties (see below).

The format of the bibliography lists created by the numbered and author-date scripts are specified in the bibliography template files CIP-AMAstyle.rtf and CIP-APAstyle.rtf. These files provide a reasonable starting implementation of the AMA style (a modified Vancouver style widely used in biomedical science) and the APA style, respectively. As is, they provide specific templates for journal articles, books, book sections (inbook), proceedings papers, conference presentations, technical reports, electronic documents and Web pages, with a generic template for other types of references. Some notes about these templates are available at TemplateNotes.

The template files can be edited in an rtf editor such as TextEdit to add additional specific templates, modify existing templates or change text styles. The bibliography template files specify only the format of the bibliography list; as noted above, the format of the in-text citations is controlled by properties in the scripts (see script properties, below). In each CiteInPages script, the BibliographyTemplateName property contains the name of the file that is used by the script as a bibliography template; the numbered script is set to the AMA template file and the author-date script is set to the APA template file by default. To use another template file, place it in BibDesk's Templates folder and set the BibliographyTemplateName property of each script that should use that template to the name of the file.

Many people may ultimately want more template files (i.e., for multiple journals with different formatting requirements). To accommodate this, multiple bibliography template files with different names can be placed in the Templates folder, the CiteInPages scripts may be duplicated and their properties edited individually to use desired settings and templates, and the scripts can be renamed appropriately so that formatting alternatives are easily available and distinguishable in the BibDesk scripts menu. More information on creating export templates is available in BibDesk's help file and in the BibDesk Wiki.

Editable script properties

A number of properties (described below) are specified at the top of each script so that they may be edited easily, if desired, to adjust in-text citation styles, replace templates or accommodate non-English settings. To edit a property, double-click a script to open it in the Script Editor, change the text string that is assigned to the property (the text after the colon) and save. If quotes are present, be sure not to remove them. Script properties can also be modified on-the-fly using a special XML tag inserted into the Pages document (see Usage, below). Editing script properties is optional. Both scripts for numbered in-text citations have the same list of properties; the author-date script shares some of these properties and also has some unique properties. If a property is defined only in the numbered or author-date scripts, that is noted after the property name. Because Applescript functionality is limited in Pages 5.2, fewer properties are available for user adjustment in CiteInPages5.

tagStart: Specifies the initial delimiter string that will be recognized as starting an in-text "working citation" that will be replaced by CiteInPages. This must match the initial delimiter specified in the citation template (see above) and should be unique to working citations within the document. It should be different from CitationStartChar (below), the initial character of the final formatted in-text citation. The default is square bracket - asterisk - space. If you're interested in using TeX commands for citations (of the form \cite{citeKeyList}), see note #12 below.

tagEnd: Specifies the trailing delimiter string ending in-text "working citations." As above, this must match the trailing delimiter specified in the citation template (see above), it should also be unique to citations within the document and it doesn't need to be similar to tagStart (though most people will probably want symmetrical start and end delimiters for visual reasons). The default is space - asterisk - square bracket.

CitationStartChar: Specifies the character or string that will be the leading delimiter for the in-text citations after replacement of the working citation. It should be different from tagStart. The default is a square bracket.

CitationEndChar: Specifies the character or string that will be the trailing delimiter for in-text citations after replacement. It should be different from tagEnd. The default is a square bracket.

superscriptCitations (numbered only, not in CiteInPages5): Default false. Set to true to superscript the in-text citations. Normally, you would also set CitationStartChar and CitationEndChar to "" (the empty string) when you're using superscripts. The AMA style usually uses superscript in-text citations, but for the moment CiteInPages numbered ships with full-size in-text citations because confirming their accuracy seems easier. Switching to superscripts when needed is simple.

italicCitations (numbered only, not in CiteInPages5): Default false. If true, full-sized numbered citations in text (including delimiters) will be italicized. Superscript in-text citations are not affected.

inCitationSeparator (author-date only): Default comma-space. This defines the character(s) that will separate author names from year in the in-text citations

betweenCitationSeparator (author-date only): Default semicolon-space. This defines the character(s) that will separate citations from each other when several citations are included together within parentheses.

initialsLast (author-date only): Default false. This determines whether initials will precede (the default) or follow the first authors name in in-text citations when references have similar last author names and years, but the author initials differ.

initialPunctuation (author-date only): Default true. This determines whether in-text citations that include first author initials will use punctuation with the initials. With punctuation, the initials are followed by periods and separated by a space, and if initials follow the last name there is a comma after the last name. Without punctuation, periods, spaces between the initials, and commas if the initials follow the last name are suppressed.

maxTagLength: If an in-text citation is longer than this, CiteInPages will identify it as an error (this can catch tags with missing or malformed trailing delimiters). The default is 700 characters, but it can be changed as desired.

BibliographyTemplateName: Contains the name of the template file that will be used to format the bibliography list. As of BibDesk version 1.3.13, a file name rather than a template name may be specified here, which avoids the need to install a template in BibDesk's preferences. By default, the value of the template name is "plainTemplateNonNumbered.txt" so if the supplied bibliography template file is to be used, and is copied to BibDesk's Template folder as directed above, no further configuration is necessary.

useNumberedListStyle (numbered only, not in CiteInPages5): If set to "true" (no quotes needed), CiteInPages will set the span of the bibliography to the Numbered List style in Pages, so that Pages will number the bibliography list. In this case, the BibDesk template should not itself number the references. If having BibDesk number the references is preferred (i.e., a special numbering style such as numbers in square brackets is required), this property can be set to "false" and numbering and leading tabs can be specified in the BibDesk template. Note that the author-date script should not use a template that specifies numbering. By default, this property is "true" and the supplied bibliography template does not include numbering. Either way is fine; if the latter is used, a final simple adjustment of the Pages ruler will be required to get nice hanging indents.

listStyleName (numbered only, not in CiteInPages5): This property specifies the Pages list style that will be applied to the bibliography if useNumberedListStyle is true. It is set to "Numbered list" by default, which is a default list style in English installations of Pages. With other languages, or if a special numbering style is defined, this value can be set to another style name. Note that special numbering styles, such as square-bracketed numbers, can be created within Pages. If a special Pages list style is used, this property should be set to its name, which should be visible in the list styles popup at the right of the format bar in Pages.

insertString: By default, CiteInPages appends the bibliography at the end of the Pages document. If desired, the bibliography can be inserted anywhere else in the document by placing a special unique string (specified by insertString) in the document that is replaced by the bibliography after the whole document has been processed. This can be useful when the bibliography should be inserted prior to figure legend and table pages. The default value of the insertString is "insert bibliography here" enclosed in angle brackets, but this can be edited to any value desired. CiteInPages can also insert multiple independent bibliographies per document (see note #14).

hangingIndent (author-date only, not in CiteInPages5): Allows the user to set a hanging indent width for author-date bibliographies. Default is 0.25 (assumes an inch-based ruler); adjust as desired or for other metrics.

bibSpacing: Not in CiteInPages5. Extra vertical spacing in points between individual entries in the bibliography. Default 6 points.

matchDocumentFontAndSize: Not settable in CiteInPages5 but functions as "True." Determines whether bibliography lists will acquire the font and font size of the point at which they are inserted in a document, or whether they will retain the font and font size specified in the rtf template. Default is true (font and size will match the document). Other styles such as bold, italic, underlining, etc., are always as specified in the template.

Usage

Temporary "working citations" containing cite keys are dragged or copy/pasted from BibDesk into a Pages document, or are selected in BibDesk and placed at the insertion point in Pages using the included text citation script (not CiteInPages5). The working citations represent the bibliographic references while the document is being written and edited. Cite keys are (typically) unique representations for references in a BibTeX library file. They may be generated in several ways and are usually recognizable combinations of author name, year, and possibly other information about a reference. When editing is complete, the CiteInPages numbered or author-date script is run from BibDesk to duplicate the Pages document, replace the cite key citations in the duplicate with numbered or author-date citations, and insert or append a formatted bibliography to the duplicate file. Note that if a cite key is not unique, CiteInPages will replace it with the first reference with that cite key, so generating or confirming unique cite keys before insertion into documents is a good idea.

Adding working citations to a Pages document. For CiteInPages (not CiteInPages5) just set the insertion point in the Pages document where the citation should be inserted, select one or more citations from a BibDesk reference list and choose the text citation script from BibDesk's script menu. Alternatively and in CiteInPages5, if the citation template has been configured as the export template for dragging and copying, one or more citations can be dragged directly from BibDesk to the desired point in a Pages document or copied from BibDesk and pasted into the Pages document. Working citations should drop into Pages as comma-delimited cite keys inside the citation delimiters specified in the citation template. All citations in one Pages document should be from a single BibDesk library; it's easy to drag references between BibDesk libraries, if needed, to get them all together. Citations in Pages can be edited just like any text, but be careful not to change the delimiters and to make sure that the contents of the citation remains a comma-separated list of valid cite keys for one library file.

The text citation script in BibDesk works well with Spaces in OSX. Pages can be set up on one screen and BibDesk on a second screen. To insert a citation, just place the insertion point as desired in Pages, click BibDesk on the dock to move to BibDesk's screen, select the desired reference(s) and choose the in-text citation script (not CiteInPages5), and the screen will flip back to Pages with the citations inserted. You can also use copy/paste in this scenario.

Suppressing delimiters or superscripting for specific citations. If "d" or "s" is placed at the start of an in-text working citation, inside the initial delimiter and separated from the first cite key by a space, delimiters or superscripting will not be placed on that citation in the output file ("d" only for CiteInPages5). This allows you to refer directly to numbered references in the text. The recommended syntax is "-d", "-s", or "-ds":

[* harrison:2007 *] --> [3]
[* -d harrison:2007 *] --> 3

Setting script properties on-the-fly for a particular file. For convenience, any script properties (Editable Script Properties, above) can be set for a particular file by including a CiteInPages XML tag that specifies new values for the properties somewhere in the Pages document. The tag should be in its own paragraph, which will be deleted in the output document, and can be located anywhere in the document. Capitalization of property names is not significant, and quotation marks can be "curly" or straight. The script will show the properties that are being changed and their new values in a dialog, with the option to continue or cancel the script. If a property that is not in the script is referenced, a dialog with that property name and a message requesting a correction will appear and the script will terminate. The tag should be of the form:

Replacing working citations and generating the bibliography. Open the Pages file you wish to process, make sure it's the frontmost Pages file and that change tracking is turned off (see Note #6 below), open the BibDesk library that you wish to use and make sure it's the frontmost library in BibDesk, and choose the desired CiteInPages script from BibDesk's scripts menu. The Pages file is saved (in case unsaved changes are present) and duplicated to a file with "-bib" appended to its name in the same location as the initial file. The initial file remains open underneath, but is not touched by the script. A progress box or bar will appear in the new Pages document to provide feedback as in-text working citations are replaced by numbered or author-date citations. The formatted bibliography is appended to the Pages document (by default) or can be inserted anywhere else in place of the defined insertString (see Configuration, above). Finally, some feedback is provided in a dialog box before the script exits. Author-date bibliography entries that have the same authors and years will have a note in red text appended to them indicating the letter that the user should append to the year of that entry to distinguish it (for example "a" or "b"). The corresponding letters have already been appended to the in-text citations (see Note #3 below for more detail).

Error alerts

CiteInPages tries to be intelligent and helpful about common errors related to files and working citations in documents:
  1. The script will check to make sure both a Pages document and BibDesk library are open at the start of the run, and will exit with an explanation if they are not.
  2. If there is a file name conflict during the initial duplication of the Pages document (i.e., a file with the document's name plus "-bib" already present in the document's folder), the script will display a dialog with an option to move the conflicting file to the trash or open the folder and highlight the conflicting file.
  3. If the bibliography template file specified in the script property BibliographyTemplateName is not in either ~/Library/Application Support/BibDesk/Templates or /Library/Application Support/BibDesk/Templates, CiteInPages will exit with a warning indicating that the template file was not found and providing the name of the expected template file.
  4. The script will issue specific alerts if no working citations are found in the Pages document or if none of the cite keys are found in the BibDesk library.
  5. If a working citation has a missing or malformed start or end delimiter, or if a working citation appears to be too long (longer than maxTagLength, see Configuration above), the script will issue an alert, scroll the duplicate Pages document that is being processed to display the problem citation (CiteInPages5 doesn't automatically scroll), and mark the recognizable end of the citation in red.
  6. If cite keys are present in the document that are not contained in the BibDesk library, alerts will be provided. The scripts will halt processing when they encounter an unknown cite key, report the cite key in a dialog box, and highlight and display the working citation containing the unknown cite key.
  7. Problems with templates that cause missing or concatenated entries in the bibliography list (see note #13 below) can cause the list to contain fewer apparent references than it should. CiteInPages compares the number of unique references with the number of paragraphs (i.e., list elements) added to the document and alerts to a discrepancy, with an option to continue the script and correct the bibliography manually after the script finishes. The number of unique citations shown in the dialog at the end of the script will be correct, but there may be fewer numbered citations if some are concatenated or missing. This alert will help in tracking down template problems and/or correcting bibliographies with minor problems. For example, just insert returns between concatenated citations in a numbered list, and the numbers will correct themselves.

Notes

  1. CiteInPages is no speed demon but hardware keeps getting faster so this is less of an issue than it used to be. The author-date script is slower than numbered references due to the need to identify name and year overlaps for special handling (see below). Of course, it's a lot faster than the manual alternative and a lot cheaper than commercial alternatives. Note: EndNote integrates with Pages now, and Sente and Bookends have some ability to work within Pages documents in versions prior to 5. You should take a look at these alternatives and see what best fits your workflow and budget.
  2. The CiteInPages numbered script will hyphenate numbers to create citation ranges in citations with multiple references, including citations that have a mix of citation ranges and single citations. The alpha-numbered script sorts citations with multiple references in numerical order, but does not hyphenate sequential numbers.
  3. The author-date script tries to handle different references that have the same names and years in a manner consistent with APA guidelines. Briefly, for papers in the same year that have matching first author last names but different initials, if there is not a difference in the names and numbers of other authors that would distinguish standard in-text citations, first author initials are used in the citations. If the first author is identical and the papers would not otherwise be distinguished by other author names and numbers, in-text citations are distinguished by appending "a", "b", "c", etc. to the year. Because there's no way to provide information from the script to BibDesk prior to the templating process to communicate whether and which letters should be appended to the year in the final bibliography entries, the script adds a note at the end of any entries in the bibliography list that need a letter appended to their year, indicating what the letter should be, and alerts the user in a dialog at the end of formatting that one or more references need to be manually edited. In CiteInPages5, the note is in red. This manual correction is usually a minimal effort, as there are normally few if any references with both name and year overlaps.
  4. Embedded images in the Pages document are no problem.
  5. Text in tables, footnotes, embedded text boxes and embedded images is not processed. Thus if you have working citations in any of this "non-body" text, you'll need to change them to final citations manually. This may be desirable in some cases, as formatting citations in text boxes would change their size, the external word wrap and so forth. If citations appear only in tables, footnotes or embedded graphics, they will not be included in the bibliography. A workaround is to place working citations in the main text at about the point where the table, figure or footnote will appear, and then transfer the final citations manually to the table, figure or footnote after processing the file. Of course figure legends that are part of regular page text, as necessary for most journal submissions, are handled fine. However, be aware that in those cases citations that are numbered sequentially will acquire numbers based on their location in the main body text, which may not be desired for citations appearing for the first time in a figure legend (for example, when figures are presented together at the end of a manuscript). In those cases, putting temporary citations in the body text at the desired location will allow the references to be numbered correctly.
  6. Do not run CiteInPages with change tracking turned on in Pages. Tracking responds to the changes the script creates as it processes a document, slowing things to a crawl, and the display of deleted text confuses the script. Even pausing change tracking is problematic, though it is possible that paused tracking, in combination with the right choice of display options, might work--but I don't recommend it. Using change tracking while working on the document and adding citations is fine, as long as it's turned off when the script is run.
  7. Inserted comments are fine, and are not processed. If a comment is placed on a citation tag or cite keys within the tag, it will be deleted when the tag is replaced with the final citation. To make a comment survive the replacement process, just include a few characters before or after the tag in the comment's target character span.
  8. In limited testing it appears that both footnotes and automatic tables of contents can be used with Pages 5.2 and CiteInPages5. Previously, bugs in text offset index calculations cause in-text citation errors for citations following footnotes in Pages 3. The footnotes bug was fixed in Pages 4 but a similar bug caused in-text citation errors for citations following automatic tables of contents in Pages 4.
  9. CiteInPages does not constrain cite key styles. I find that the author:year style works well for in-text citations during writing and editing, as the citations are fairly short but recognizable. If there are several references from the same first author in the same year in a BibDesk file, BibDesk will append one or a few characters to the end of the year to make the cite key unique when a cite key is generated for that file (for convenience, it's a good idea to regenerate cite keys before starting to use a BibDesk file with a new manuscript, in case you've imported cite keys from elsewhere that may not be unique or may have an alternative style). The few extra characters don't add much to the length of the cite key or affect usability, and the short "author:year" cite key style is more compact and attractive to my eye then other cite key styles.
  10. BibDesk and BibTeX libraries are great for sharing with a manuscript that is being written collaboratively. Since BibDesk is free, easy to use and has very good import/export facilities, there's no penalty for all contributing authors using it even if some use other bibliographic software. The library files are small, when they are limited to the references in use for a particular manuscript, and easy to share along with the document. Any of the authors can add new references to the library and to the document provided all authors use the same working citation template (see above under Installation). It would probably also be most convenient if all authors used the same BibDesk cite key setting (in BibDesk Cite Key preferences).
  11. A CiteInPages script targets one bibliographic template and final in-text citation style. If multiple citation and/or bibliography styles are needed, e.g., for submissions to journals with different style requirements, it would be reasonable to create duplicate versions of the script in the Scripts folder containing references to the various template files and citation delimiters needed, and name the scripts appropriately. Then the desired style could be chosen easily from BibDesk's scripts menu.
  12. BibDesk's built in TeX cite commands can be used for in-text citations, but they are awkward-looking to my eye. If you wish to do this, remember to use two backslashes in the string assigned to tagStart that denotes the initial delimiter of the working citations, eg, "\\cite{", because the backslash is an escape character in Applescript. Also, because the trailing delimiter is just a closing brace, using braces anywhere else in the document will cause an error. It would be possible for me to avoid these types of errors with appropriate scripting, but I believe the result would be slower and you would lose the ability to easily recognize a tag with a malformed or missing initial delimiter but an intact trailing delimiter. By requiring both the initial and trailing delimiter strings to be unique, you can identify situations in which either delimiter has a problem. I thought this was worthwhile.
  13. If not all references are displayed in the bibliography even though they appear to process correctly, make sure the BibDesk bibliography template being used has entries for all reference types cited, or includes a generic entry for reference types that don't match the specific templates (the provided files are written this way). Also, if a syntax error exists in a template, that template will stop processing a reference at the error point and the next reference in the bibliography will concatenated with the problematic one. This is an issue that occurs when developing and debugging templates, and is recognizable by references in the list that are made up of several reference fragments. Prior to CiteInPages 1.03 this problem could yield formatting or paragraph index errors. This is now handled such that an alert is generated to a discrepancy in length between the number of unique citations and the inserted reference list, and errors are avoided by confining processing to the text actually inserted.
  14. CiteInPages can be used to generate multiple independent internal bibliographies in a single document, which restart numbering from 1 in each bibliography. Just use a different set of working citation delimiters for each bibliography list and run the script multiple times over the document, changing the tagStart and tagEnd strings with each iteration and relocating the insertString to the point in the document where the next bibliography should be inserted. Each time the script passes through the document, only working citations that match tagStart and tagEnd will be processed.
  15. Problems have been reported in the past when file name extensions are hidden in the Finder. It's recommended that file name extensions be set to display when CiteInPages is used, though this hasn't been retested with recent versions of OSX and Pages. To display file name extensions, make sure "Show all file name extensions" is checked in Finder Preferences > Advanced.
  16. Any advice regarding the various workarounds, kludges and generally amateurish programming strategies in the script is welcome at my address below. It's also fine to add improvements and redistribute the script, consistent with the BSD license; I'd appreciate notification and the opportunity to use and learn from the improved script.

Cheers!

Jim Harrison
University of Virginia
james-dot-harrison-at-virginia-dot-edu


subtopics:
This page was last edited 1 month ago by harrison. View page history
Subject:


Comment:


    with signature

Powered by Zwiki, Zope, Python, and Mac OSX