August 2008 Archives

Sente in the Kleper Report on Digital Publishing

| No Comments
A review of Sente has just appeared in the Kleper Report on Digital Publishing, a newsletter for the publishing industry.  Current issues are available only to subscribers, but here are some excerpts:

Sente 5 is an application that supports the management of academic references by enabling access to hundreds of worldwide on-line databases. Users simply input keywords into a search field and are returned a listing of matching references, some of which contain notes, full text, or PDF files of the reference content. PDFs can be downloaded and managed locally, on the user's computer. It is the ultimate tool for maintaining daily updates on new contributions to the literature in a given field or on a given subject. [...]


A series of informative videos (http://www.thirdstreetsoftware.com/site/videos.html) show how easily and quickly the program can gather valuable research references and content. Sente is the complete solution for scholarly and everyday research needs.


[Reprinted with permission from The Kleper Report on Digital Publishing <http://www.printerport.com/kdp>, copyright 2008, Graphic Dimensions, Lauderdale by the Sea, FL.]



Unlearning "occurrences"

| No Comments
People who either created or modified bibliography formats in older versions of Sente had to understand what we called "occurrences" in order to accomplish many goals.  Unfortunately, this concept now needs to be "unlearned" to use the new version of the bibliography format editor.  This article is intended to help people make the transition from the concept of "occurrences" to the ideas that replace it.

One of the problems that both the old and new approaches are addressing is the fact that the more complicated formats (like APA, Chicago, etc.) require that references be formatted differently depending on the context in which they appear.  For example, some formats call for a complete version of the reference the first time it appears in a document, and an abbreviated version everywhere else.  Some formats want the in-text citation to use only the author name, but in contexts where this is not sufficient to identify the correct reference, they include the title (or a portion thereof).

Prior versions of Sente supported this by allowing you to specify exactly which contexts, or occurrences, a style cared about (most only cared about a few) and then it allowed / required you to create completely different formats for each one.  For example, if a format required different contents for the first vs. subsequent occurrences of a reference, one would add the "subsequent" occurrence to the format definition, and then specify exactly how references should appear in this case.  Often the definitions for many occurrences were very similar, differing in only a few details.

We have now changed this approach fundamentally.  Now, instead of a potentially large number of "occurrences," a bibliography format in Sente only includes one in-text and one bibliography format for each reference type.  And the format definition for each of these can contain elements whose appearance is conditional, based on the context in which the reference appears.  That is, there is one in-text format for journal articles in each bibliography format definition.  This single format might include, say, two versions of the author list: one for the first appearance and the second for all other appearances, but all of the other details are specified only once.  This approach eliminates a lot of redundant work, and I know from experience just how hard it was to keep this redundant information in sync.

Here is another way to look at it.  If you read my last post (about customizing the preview display), you will see that it is possible to set things up so that there are two different versions of the in-text format displayed.  (My example in that post was first and subsequent appearances.)  In the old version of Sente, these would have been specified completely independently.  In the new version, they are each a version of the single, in-text format specification.  Because this specification contains some elements that appear and disappear based on the context conditions, the specification can result in two or more very different outputs for any one reference, thus the need for two different previews.

Now when you want to modify a format to behave slightly differently in a different context, you can leave untouched all of the elements that stay the same, and only apply conditions to those elements that should be different from one context to the next.

While it may take some time to adjust to this new approach, having personally recreated the most complex formats using the new approach, I can say that I think the new approach is much better than the old one.  This change, along with all of the other recent changes to the bibliography format editor, makes creating and maintaining complex formats much easier than it has even been before.

Customizing the Bibliography Format Preview

| No Comments

In the new version of the bibliography format editor in Sente, you can customize what gets shown in the preview pane so that you can more easily see how a given format will behave when it is used on a document.

For an example, let's look at the Chicago 15 N (Notes) format. In this format, one does not normally include a bibliography at the end of the document, so all of the important bibliographic detail has to appear in the first occurrence of a citation. After that, a much shorter version of the citation can be used.

In this article I am not going to talk about exactly how one defines a format to work in this way. Instead, I am just going to show you how you can customize the preview pane to help you preview this behavior.

By default, the preview pane includes one version of the in-text format and one of the bibliography format. For the Chicago format in question, this would look like this:

▼ Journal Article (JA)

[edit sample data]

In-Text

John Allen Smith and others, "Fractals in Biological Systems," J Biol Chem 151, no. 22 (1999): doi:10.1006/ceth.2003.1354. http://www.jbiolchem.com/article/doi/10.1006/alpha.23.45 (accessed February 1, 2003).

Bibliography

Smith, John Allen, Randall Benjamin Jones, Alfred Carlyle Black, and Susan D. White. "Fractals in Biological Systems." J Biol Chem 151, no. 22 (1999): doi:10.1006/ceth.2003.1354. http://www.jbiolchem.com/article/doi/10.1006/alpha.23.45 (accessed February 1, 2003).


But this does not show you how the format will display a reference the second (or later) time it appears in your document. You could create a test document and scan it using this format, but that would be tedious. Instead, Sente lets you modify the preview to include an example of the in-text format when it appears in a subsequent occurrence.

To modify the previews, switch to the Advanced tab in the bibliography format editor drawer, where you will see something like this:

Picture 10.png

Here you can see that I have renamed the default In-Text context to "In-Text, first occurrence" and, using the Context Conditions pop-up menu, I set the active condition to be "first occurrence." I also created a second in-text preview and set the context to be "subsequent occurrence." One can create a preview with any combination of conditions, and the sample data will be displayed as they would appear in a real document when those conditions are encountered. When I create a preview with the condition "first occurrence in document," any element whose presence or absence depends on this condition will be turned on or off as specified.

I could have also removed the bibliography preview, given that one does not normally include a bibliography in Chicago Notes format, but I left it here in case someone finds it useful.

With these changes, the preview looks like this:

▼ Journal Article (JA)

[edit sample data]

In-Text, first occurrence

John Allen Smith and others, "Fractals in Biological Systems," J Biol Chem 151, no. 22 (1999): doi:10.1006/ceth.2003.1354. http://www.jbiolchem.com/article/doi/10.1006/alpha.23.45 (accessed February 1, 2003).

In-text, subsequent occurrence

Smith and others, "Fractals," 943-949.

Bibliography

Smith, John Allen, Randall Benjamin Jones, Alfred Carlyle Black, and Susan D. White. "Fractals in Biological Systems." J Biol Chem 151, no. 22 (1999): doi:10.1006/ceth.2003.1354. http://www.jbiolchem.com/article/doi/10.1006/alpha.23.45 (accessed February 1, 2003).


Now it is much easier to be sure that citations will be formatted correctly in the different contexts in which they appear.

You can create as many of these preview contexts as you want, and they are created on a format-by-format basis because different formats care about different things.

Using Conditional Elements: Example 2

| No Comments

Here is another example of how using conditional elements in bibliography definitions can save a lot of time, and produce better results than you are likely to get without them.

In APA 5 (APA, Fifth Edition), like all of the author-date formats, in-text citations typically look something like this: (Smith, 1997). But things get more complicated, depending on the details of the reference. For example, these are also valid in-text citations in APA 5:

  1. (Smith, Jones, Black, White, and Grey, 1996) for the first occurrence of a reference, and
  2. (Smith et al., 1996) for the same reference in subsequent occurrences
  3. ("Summer Solstice," 1972) when there are no authors for an article
  4. (Western Slope Inns, 1981) when there are no authors for a book

There are many other variations, of course, but these will do for this example. Rather than talk about all of the details of APA in-text citations, I am going to focus on the use of different author list formats for the first and subsequent occurrences, and the substitution of titles for authors.

First, the rules for in-text citations are essentially the same for all reference types, so I created a component for the complete in-text citation that I then just use for all reference types. This means that I only have to get the details right in one place.

Next, just to keep things a little clearer in my head, I created a sub-component to handle the author names and titles. This component has four elements:

  • One Primary Contributors element (like an Authors element, but see elsewhere for more information) with the proper name formatting for the first occurrence of a reference in a document (e.g., up to 5 authors, then et al.). This element is set ti be used only under the condition that this is the first occurrence of the reference in the document.
  • A second Primary Contributor, with the name formatting set up properly for all subsequent occurrences (e.g., up to two authors, followed by et al.), and dependent upon it not being the first occurrence.
  • An Article Title element to be included only if there are no primary contributors, but there is an article title.
  • A Publication Title to be included only if there are no primary contributors and no article title.

That is really the core of the strategy. The component uses which ever version of the Primary Contributors element is appropriate in context (first occurrence or subsequent occurrence), and a fall-back cascade to use article title or publication title as appropriate if there are no primary contributors.

One side note, by using Primary Contributors instead of Authors, I automatically get whatever contributors are flagged as "primary." For most journal articles and books, this would be the authors. But for any reference where I have indicated that some other contributor should be considered "primary," those contributors will automatically be used both here in the in-text citation as well as in the bibliography. So when I decide to cite a particular recording by conductor rather than composer, the format automatically handles it for me.

Using Conditional Elements, Example 1

| No Comments

To help people who need to create or modify bibliography formats, I will be posting some examples of how to handle the complexities one actually encounters in real-world bibliography formats.

Here is an example of how you can use conditional elements when creating or modifying a bibliography format in Sente.

In Chicago 15 AD (author-date), the formatting of volume, issue and pages for a journal article can get a bit complicated. Here are some examples of how this information can appear (in each case below ABCD=journal, volume=12, issue=34, pages=56-78):

  1. ABCD 12:56-78.
  2. ABCD 12 (34): 56-78.
  3. ABCD, no. 34:56-78.
  4. ABCD 12: doi:10.1006/berd.2006.2345.
  5. ABCD, no. 34.
There are a couple of interesting twists that make this format a bit tricky:
  • there should not be a space after the colon, unless both volume and issue exist
  • issue is formatted differently, and is separated from the journal name by a comma, if there is no volume
  • page numbers are replaced by the DOI if there is one

One way of implementing this using conditional elements would be to create a component and add the following elements to this component (in order):

  1. Volume, with a prepended space
  2. Issue (prepend: " (" and append: ")"), if there is a volume
  3. Issue (prepend: ", no. " and append: nothing), if there is not a volume
  4. static text: ": " (colon with a space), if volume, issue and pages all exist
  5. static text: ":" (just a colon), if pages exist, and at least one of, but not both of, issue and volume exist
  6. pages (no prepend or append text), if there is no DOI
  7. DOI (no prepend or append text)
  8. static text "." without conditions

This probably seems more complicated that it really is, and once this has been placed in a component, it can simply be used as a unit anywhere this is needed. And should you get it wrong in one detail or another, there is only one place where you would need to make the correction.

Now, you might be thinking that this all seems kind of complex, and you would be right. It is not as bad as it might seem, but it definitely is a bit complex. But the bottom line is that the Chicago format specification is complex, and this is about what it takes to handle it correctly.

As a point of comparison, I ran a few tests on a competing reference manager to see how it handles this very same format, and here is what I found for each of the examples above:

  1. ABCD 12 56-78. (space instead of colon)
  2. ABCD 12 (34): 56-78. (correct)
  3. ABCD (34): 56-78. (wrong issue format)
  4. ABCD 12 56-78. (missing colon, no substitution of DOI)
  5. ABCD (34): (wrong issue format, extra colon, missing period)

I suspect that the format definition in this other software could be improved with a bit of tinkering (I was using the format as distributed with the product), but I wonder whether this software can be made to handle complexities like this.

Of course, Sente's built-in formats are not perfect, but we are committed to making them as accurate as we can, so we keep adding features that enable us to handle the remarkable complexities we find in the world of bibliography formats.

Introducing Bibliography Format "Components"

| No Comments
One of the most powerful new features in the bibliography format editor in Sente 5.6, is the ability to create and use "components."

Components are just like format specifications for any reference type, except that, once created, components can be used in other format specifications just like the built-in elements.

For example, most formats have a standard way of presenting publication details such as the name of the publisher, the place of publication and the year of publication.  In Chicago NB (Notes + Bibliography) it looks like this:

New York: Columbia Univ. Press, 1926.

The rule for even this rather simple set of information get a little complicated (e.g., how do you format it if you do not know the place of publication?), and the format is used for most reference types.

In prior versions of Sente, you would have had to specify all of the rules each time you wanted this information to appear.  This was very tedious.

In the new version of Sente, you can create a component called, say, "Publication Details" and simply include that component wherever you want this information to appear.

Not only does this greatly speed up the creation of consistent formats, but should you find a problem in the definition of a component, all you need to do is to modify the component and the new version will be automatically used everywhere.

It takes some time to figure out exactly what should be a component, but the new versions of APA, MLA and Chicago make extensive use of components, so you can look at the for some ideas about how components can be used.

MLA 3: Why is "Print." at the end of each entry?

| No Comments
If you have used the new MLA style that we started shipping with Sente 5.6.5, you will have no doubt noticed that most of your bibliography entries end with "Print." and I'll bet that many of you have wondered why this is there.

Here is an example:

Gerber, Alan S., and Donald P. Green. "Social Pressure and Voter Turnout: Evidence From a Large-Scale Field Experiment." American Political Science Review 102 (2008): 33-48. Print.


This new version of MLA is based on the recently-released MLA Style Manual and Guide to Scholarly Publishing, 3rd Edition. This new version of the book updates the MLA style to better indicate exactly what version of an article, book, etc. was consulted during research.  If you retrieved a PDF of the above article from JSTOR, the bibliography entry would look like this:

Gerber, Alan S., and Donald P. Green. "Social Pressure and Voter Turnout: Evidence From a Large-Scale Field Experiment." American Political Science Review 102 (2008): 33-48. JSTOR. Web. 13 Jan. 2008


To support this, we added a new field in Sente 5.6.5 called "Web data source."  In the case above, this field should be populated with "JSTOR" and the Date Retrieved filled in appropriately, and the output would change to what you see above.

For more information on this change to the MLA style, see Section 6.7 in the MLA Style Manual.


Chicago 15 and DOIs

| 2 Comments

We have recently released an updated version of the Chicago styles (in Sente 5.6.5).  There is one aspect of these new styles that I believe we have handled correctly, but which I expect users to dislike; namely the handling of DOIs in bibliography entries.  I am hoping to generate some feedback from some users of the Chicago styles.


The Chicago Manual of Style (15th Edition) (CMOS) only mentions DOIs in two sections:


  • Section 17.14 talks at a high level about how the University of Chicago Press considers DOI "promising" as a tool for easily identifying articles.

  • Section 17.181 (under the heading of Electronic Journals) says: "If there is a digital object identifier (DOI) for the source (see 17.14), include it in place of page numbers or other locators."  (Emphasis added.)


This means that a proper Chicago 15 bibliography entry for a journal article with a DOI would include journal name, volume number plus DOI -- no page numbers.  This means that instead of this:


Gerber, Alan S., and Donald P. Green. "Social Pressure and Voter Turnout: Evidence From a Large-Scale Field Experiment." American Political Science Review 102 (2008): 33-48.


the new version of Chicago 15 NB (Notes + Bibliography) produces this:


Gerber, Alan S., and Donald P. Green. "Social Pressure and Voter Turnout: Evidence From a Large-Scale Field Experiment." American Political Science Review 102 (2008): doi:10.1017/S000305540808009X.


This rule applies to all three of the Chicago styles.


According to the CMOS, there is no way to include both page numbers and a DOI; the only supported options are to present either one or the other.


(By the way, one might argue that because 17.181 falls under the heading of Electronic Journals, this rule would not apply to articles that also appear in print journals.  But in the first paragraph of 17.181, the authors seem to indicate that their discussion of page numbers below covers journals that have a print version as well as on-line versions.)


Now, DOIs are very important for Sente.  They are by far the best identifier for uniquely identifying a reference, so we want to have them in the reference whenever possible.  But, according to CMOS, when we have them we should not include page numbers in the bibliography entries.


Personally, I think that omitting page numbers in favor of a DOI is a bad design decision, and I would like to see the format modified to support the inclusion of both items, but that is not our decision to make.


The best option I see is to change the logic of the Chicago format to favor page numbers, but to include the DOI if the reference does not have page numbers.  This would mean that most references would have page numbers in the bibliography rather than a DOI (which is certainly a loss), but in cases where the user was working from a PDF where the page numbers are meaningless (e.g., "1-6") the DOI would be used instead.  This contradicts the literal interpretation of the CMOS, but it would produce legal output.


Before I make such a change to our built-in Chicago formats, I would like to get some feedback from anyone who regularly uses these styles.  Would you prefer that the styles work the way they do now (i.e., following the letter of the law), or would you prefer us to change them along the lines of my proposal?  Or do you have another idea about how this issue should be handled?

Introducing "Primary Contributors"

| No Comments
Sente 5.6 introduced a new concept used in defining bibliography styles, called "Primary Contributors," that I would like to explain.

Most formats (like APA, MLA, Chicago, etc.) are flexible about exactly which contributor(s) should be placed first in bibliography entries.  For example, when citing a movie, one could list it by director, producer, screen writer, actors, or just by title, depending on the purpose of the citation.

In the past, Sente handled this by requiring the user to place these contributors in the Author role in the list of contributors, and (in most cases) the authors were placed first in the bibliography entry.  This approach has many obvious problems and in this round of revisions we introduced the concept of Primary Contributor to address them.

In this new version, one would enter all of the contributors that you care about in the reference in Sente.  Then, select the Role that you want to be considered "primary" in the Primary Contributor Role pull-down menu (e.g., "Director").  

Then, if your selected bibliography style has been designed to use Primary Contributors, the names with the specified role will be listed first in the bibliography entry for that reference.

For example, here are two versions of one reference in MLA 3 format.  The only change that was made between generating these two entries was to change the value selected in the Primary Contributor Role menu.

Here is the entry with Composer as primary:

Sondheim, Stephen, comp. Passion. Cond. Paul Gemignani. Orch. Jonathan Tunick. Perf. Donna Murphy, Jere Shea, and Marin Mazzie. Angel, 1994. CD.


And here is the same reference with Conductor as primary:

Gemignani, Paul, cond. Passion. Comp. Stephen Sondheim. Orch. Jonathan Tunick. Perf. Donna Murphy, Jere Shea, and Marin Mazzie. Angel, 1994. CD.


Note that in each case, the list of other contributors does not include the primary contributor.  This behavior is automatically handled by Sente (i.e., if the style uses Primary Contributor, and the selected primary role is "Editors," then any regular Editors element will not render any content.

When creating a bibliography format, instead of starting each bibliography format with, say, an Authors element, use a Primary Contributors element instead.  For most references this will default to being the same thing as Authors, but when a reference has a different primary contributor role specified, that will be used instead.

The text "comp." and "cond." are style-specific and so must be provided by the user in the Primary Role Description field.  We should be able to automate this in a future release, but for now this is how it is handled.

In general, I would recommend that you always define styles in terms of Primary Contributor, rather than specific author roles like Authors, Editors, etc.  Used in combination with components (described elsewhere) this makes it possible to create very flexible bibliography formats with little effort.

Welcome to the Sente blog

| 1 Comment

Welcome to the Sente blog.


Over time I (and possibly others here at Third Street Software) will be writing articles about various topics related to Sente, academic reference managers, bibliographies, etc. and posting them here.  


I decided to start this blog because I know from our support email and public forums that there are quite a few people out there who think about these topics a lot, and I wanted a better place than the support forum for initiating discussions on these subjects.


Many of the topics that I expect to write about at first will be bibliography-related, due mostly to the fact that I have been spending so much time lately on this aspect of Sente.  We have introduced a number of important new features in this area of the program and, while the manual will soon be updated to document these new features, I think some are important enough to be discussed here.


I expect to expand the range of topics to include anything related to the discovery, acquisition, organization and use of academic literature, because these are all central to the purpose and design of Sente.


I hope that you find something of interest here, and I would like to welcome you to comment on any of the posts.  (Unfortunately, you will need to create yet another account for the blog, even if you already have one for our forums, because they are built using different software packages and we do not want to take the time to make them use the same list of accounts.  Sorry for the inconvenience, but this will let us focus our development time on Sente.)


Also, if you have any suggestions for topics you would like to see discussed here, please let us know either through the forums or our support address.


Michael