New Citation Style HowTo

Prerequisites

• java SDK 6
• svn
• maven
• jEdit

Preparations

1. $svn co https://subversion.mpdl.mpg.de/repos/common/trunk/common_services

2. $cd common_services/citationmanager

3. check whether checkout can be compiled:

   $mvn clean install

4. $cd src/main/resources/CitationStyles

5. $cp -r Default/ Test/; rm -rf Test/.svn

6. changes in src/main/resources/Schemas/explain-styles.xml
   1. add new citation style Test
   2. define output-formats (e.g., pdf and escidoc_snippet)

7. $cd src/test/resources/CitationStyles

8. $cp -r Default/ Test/; rm -rf Test/.svn

9. get nice items-list XML from PubMan live,
   • e.g. book chapter and journal article
10. save nice items-list XML into src/test/resources/CitationStyles/Test/TestCollection.xml

Citation Style specifications

See APA and AJP pages (the discussion pages as well) as an example of the citation style specifications and discussions.

The test item list XML has two types of publication items, namely Article and Book Chapter, thus Test citation style will have two different layout representations (so-called Citation Style Layout Definitions, CSLDs). Authors and Year blocks will be common for both CSLDs.

Authors

• family name, initials (blank separated), e.g.: Morfill, G. E.
• if there are two authors, connect them with " and ", e.g.: Morfill, G. E. and Khrapak S. A.
• if there are more than 3 authors: commas separate author names, while the last author name is preceded by ", and ". E.g.: Kernis, M. H., Cornell, D. P., Sun, C. R., Berry, A., and Harlow, T.

Year

issued or published online. issued has higher priority.

Article

Author, A. A., Author, B. B., and Author, C. C. (Year). Title of article. Title of Periodical, volume(issue number), pages.

Book Chapter

Author, A. A. and Author, B. B. (Year). Title of book chapter. In Title of book. Source.Place of Publication: Source.Name of Publisher.

Citation style configuration

Citation style is configured by means of set of XML files, they are all located in src/main/resources/CitationStyles/ directory

• global XMLs, i.e. all specified here elements can be used overall in citation styles:

  font-styles.xml: list of available font style definitions.

  functions.xml: global function definitions

  variables.xml: global variables

• citation style specific XMLs:

  Test/CitationStyle.xml: main citation style configuration file

  Test/variables.xml: local variables xml, available only in Test citation style

CitationStyle.xml structure

Root Element

Citation style specific parameters

<citation-style
   xmlns="http://www.escidoc.de/citationstyle" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.escidoc.de/citationstyle ../../Schemas/citation-style.xsd"
   name="Test" 
   read-only="no" 
   element-specific="no" 
   md-xpath="../../mdr:md-records/mdr:md-record" 
   source-placeholder-tag="prop:content-model-specific" 
   citation-placeholder-tag="dcterms:bibliographicCitation" 
   include-global-default-variables="yes" 
   include-default-variables="no"
>

• md-path is xpath to the publication metadata location, relative to source-placeholder-tag
• citation-placeholder-tag is target tag for the generated snippet citation
• include-global-default-variables, i.e. variables.xml
• include-default-variables, i.e. Test/variables-xml

Variables

List of predefined citation style variables which can be multiply used in the citation style. Variables contain only values but not formatting information, like font-styles, prefix/postfix strings, localization tags, etc.

 <variables> 
	<!-- ### objid should be always defined!!! ### -->
	<variable name="objid">../../@objid</variable>
	<variable name="genre">pub:publication/@type</variable>
	<variable name="hasPublication" type="xs:boolean">exists(pub:publication)</variable>
	<variable name="authorsCount">count(pub:publication/eterms:creator[@role=$l_author])</variable>
	<!-- localization -->		
	<variable name="in">'In'</variable>
	<variable name="date"> 
		if (pub:publication/dcterms:issued)
		then func:get_year(pub:publication/dcterms:issued) 
		else if (pub:publication/eterms:published-online) 
		then func:get_year(pub:publication/eterms:published-online) 
		else ''
	</variable>
 </variables>

Predefined Layout Elements

Layout element is an formatted unit of the citation. The following formatting attributes (layout elements parameters) can be applied:

• valid-if is a boolean expression, which triggers the layout element
• starts-with is a layout element prefix
• ends-with is a layout element postfix
• font-style references to the font-style, which specified in the global font-styles.xml
• i18n defines localization class
• delimiter is a string, which will delimit the sub layout elements of the layout element
• internal-delimiter will be applied to the layout elements of repeatable layout elements, e.g. delimiter between family name and initials in the authors
• max-count sets the maximal number of elements for repeatable layout element. E.g. it allows to limit the number of the authors

A layout element

• can reference to the only one metadata field/xpath expression/variable
• or include a list of sub layout elements recursively

The attribute repeatable="yes" declares sub layout elements as a sequence of repeatable elements (e.g. authors variable). The all elements will be aggregated and rendered as one string. There are some specific parameters are allowed for the context: internal-delimiter and max-count. The next distinctive feature of the repeatable layout elements is usage of the different sets parameters on hand of the element position (see parameters/@position). The feature allows, for example, to implement the authors last delimiter ", and ".

<predefined-layout-elements>        
<!-- authors -->
	<layout-element name="authors">
		<parameters>
			<delimiter value="" />
		</parameters>
		<elements>
			<layout-element name="authors-NotEqual2" ref="pub:publication/eterms:creator[@role=$l_author]" repeatable="yes">
				<parameters>
					<valid-if><![CDATA[$authorsCount!=2]]></valid-if>
					<delimiter value=", " />
					<internal-delimiter value=", " />
				</parameters>
				<parameters position="last">
					<delimiter value=", and " />
				</parameters>
				<elements>
					<layout-element ref="person:person/eterms:family-name/text()" />
					<layout-element ref="func:get_initials(person:person/eterms:given-name/text())"/>
				</elements>
			</layout-element>
			<layout-element name="authors-Equal2" ref="pub:publication/eterms:creator[@role=$l_author]" repeatable="yes">
				<parameters>
					<valid-if><![CDATA[$authorsCount=2]]></valid-if>
					<delimiter value=", " />
					<internal-delimiter value=", " />
				</parameters>
				<parameters position="last">
					<delimiter value=" and " />
				</parameters>
				<elements>
					<layout-element ref="person:person/eterms:given-name/text()"/>
					<layout-element ref="func:get_initials(person:person/eterms:given-name/text())"/>
				</elements>
			</layout-element>
		</elements>
	</layout-element>
	<layout-element name="year" ref="$date">
		<parameters>
			<starts-with value=" (" />
			<ends-with value=")." />
		</parameters>
	</layout-element>
	<!-- DEBUGGING -->
	<layout-element name="debugBlock">
		<parameters>
			<font-style ref="BLUE" />
			<starts-with value="debug:" />
			<delimiter value="," />
		</parameters>
		<elements>
			<layout-element ref="$objid">
				<parameters>
					<starts-with value="OBJID:" />
				</parameters>
			</layout-element>
			<layout-element ref="$genre" />
			<layout-element ref="pub:publication/dc:title/text()" />
			<layout-element ref="pub:publication/dcterms:issued/text()">
				<parameters>
					<starts-with value="issued:" />
				</parameters>
			</layout-element>
			<layout-element ref="pub:publication/eterms:published-online/text()">
				<parameters>
					<starts-with value="published-online:" />
				</parameters>
			</layout-element>
		</elements>
	</layout-element>
</predefined-layout-elements>

Citation Style Layout Definitions (CSLD)

are resulting layout elements of the citation style formatting. CSLDs of Test citation style are publication genre specific, i.e. there are CSLD for Article and Book Chapter genres. The CSLD isNotPublication provides notification message if no publication element is available in metadata record. $debugBlock variable allows to trace some metadata values during citation style debugging.

<!-- Print warning message for non-publication items -->
<cs-layout-definition name="isNotPublication">
	<parameters>
		<valid-if><![CDATA[not($hasPublication)]]></valid-if>
		<starts-with value="## Citaion style layout is not defined for metadata record: " />
	</parameters>
	<elements>
		<layout-element ref="$objid" />
	</elements>
</cs-layout-definition>

	
<!--
	ARTICLE
-->
<cs-layout-definition name="article">
	<parameters>
		<valid-if><![CDATA[
			$genre = $l_article 
		]]></valid-if>
		<ends-with value="." />
	</parameters>
	<elements>
	
<!--			<layout-element ref="$debugBlock" />-->
		
		<layout-element ref="$authors" />
		
		<layout-element ref="$year" />

		<layout-element ref="pub:publication/dc:title/text()">
			<parameters>
				<ends-with value="." />
			</parameters>
		</layout-element>

		<layout-element>
			<parameters>
				<delimiter value=", "/>
			</parameters>
			<elements>
				<layout-element ref="pub:publication/source:source[1]/dc:title/text()">
					<parameters>
						<font-style ref="ITALIC" />
					</parameters>
				</layout-element>
				<layout-element>
					<elements>
						<layout-element ref="pub:publication/source:source[1]/eterms:volume/text()">
							<parameters>
								<font-style ref="ITALIC" />
							</parameters>
						</layout-element>
						<layout-element ref="pub:publication/source:source[1]/eterms:issue/text()">
							<parameters>
								<starts-with value=" ("/>
								<ends-with value=")" />
							</parameters>
						</layout-element>
					</elements>
				</layout-element>
				<layout-element name="start-page-end-page">
					<parameters>
						<delimiter value="-" />
					</parameters>
					<elements>
						<layout-element ref="pub:publication/source:source[1]/eterms:start-page/text()" />
						<layout-element ref="pub:publication/source:source[1]/eterms:end-page/text()" />
					</elements>
				</layout-element>
			</elements>
		</layout-element>
		
	
	</elements>
</cs-layout-definition>


<!--
	BOOK-CHAPTER
-->
<cs-layout-definition name="book-chapter">
	<parameters>
		<valid-if><![CDATA[
			$genre = $l_book-item
		]]></valid-if>
		<ends-with value="."/>
	</parameters>
	
	<elements>
	
<!--			<layout-element ref="$debugBlock" />-->
		
		<layout-element ref="$authors" />
		
		<layout-element ref="$year" />

		<layout-element ref="pub:publication/dc:title/text()">
			<parameters>
				<ends-with value="." />
			</parameters>
		</layout-element>

		<layout-element>
			<parameters>
				<delimiter value=". " />
			</parameters>
			<elements>
				<layout-element>
					<elements>
						<!-- localization example -->
						<layout-element ref="$in">
							<parameters>
								<i18n ref="in"/>
							</parameters>
						</layout-element>
						<layout-element ref="pub:publication/source:source[1]/dc:title/text()">
							<parameters>
								<font-style ref="ITALIC" />
							</parameters>
						</layout-element>
					</elements>
				</layout-element>
				<layout-element>
					<parameters>
						<delimiter value=": "/>
					</parameters>
					<elements>
						<layout-element ref="pub:publication/source:source[1]/eterms:publishing-info/eterms:place/text()"/>
						<layout-element ref="pub:publication//source:source[1]/eterms:publishing-info/dc:publisher/text()"/>
					</elements>
				</layout-element>
			</elements>
		</layout-element>
	
	</elements>
</cs-layout-definition>

Debugging citation styles

Plain tests (mandatory)

Debugging life circle consists of 3 consequent steps: validation, compilation and output. Compilation should succeed any change in citation style configuration file to ensure a correct output.

1. specify plain.test.xml in Test/test.properties (e.g. plain.test.xml=Test/TestCollection.xml)
2. changes in TestCitationManager.java
   • to run all citation styles

     run

     $mvn -Dtest=TestCitationManager test

   • to run only Test citation style
   1. set testCitationStyles() to @Ignore
   2. create new JUnit test method
      @Test
      public final void testCitationStyleTest() throws Exception{
      testValidation("Test");
      testCompilation("Test");
      testOutput("Test", "pdf", "");
      testOutput("Test", "escidoc_snippet", "");
      }
   3. run

      $mvn -Dtest=TestCitationStylesSubstantial test

Substantial tests (recommended)

Substantial tests control the generation of the citations content, that may help to avoid side effects after some changes in the global functions or variables. It is recommended to run the tests after the plain tests.

1. generate escidoc_snippet output with the plain test.
2. changes in Test/test.properties: set substantial.* properties
3. copy citation snippet from the dcterms:bibliographicCitation element
4. prefix the snippet with substantial.expected.key, i.e. "TEST: "
5. changes in Test/TestCollection.xml: put prefixed snippet into the new element dcterms:abstract of the publication metadata (check location of the element in XML Schema)
6. substantial.skip.test=false
7. changes in TestCitationStylesSubstantial.java
   • to run all citation styles

     run

     $mvn -Dtest=TestCitationStylesSubstantial test

   • to run only Test citation style
   1. set testCitationStylesSnippetGeneration() to @Ignore
   2. create new JUnit test method

      @Test
      public final void testCitationStyleTestSnippetGeneration() throws Exception {
      testCitationStyleSnippetGeneration("Test");
      }

   3. run

      $mvn -Dtest=TestCitationStylesSubstantial test

TODO: Automate the generation of the substantial test XMLs.

Journal specific citation style (with an access to the CoNE journal vocabulary)

An use case for JUS citation style runs as follows: a formatting of the Article citation should depend on the journal title, where the publication has been issued. Citation style type->Journal name mapping can be put into CoNE controlled vocabulary and retrieved later via CoNE REST interface during the citation generation runtime.

• specify the CoNE call function and related parameters in the local variables.xml (i.e. src/resources/CitationStyles/Test/variables.xml)

<variables xmlns="http://www.escidoc.de/citationstyle">

	<variable name="sourceGenre">pub:publication/source:source[1]/@type</variable>        

	<!-- idType of the source of a journal. 
	If SFX is present, will be taken, otherwise the idType
	will be chosen in the following order: SFX-ISSN -->
	<variable name="idType">
		<![CDATA[
			if ($sourceGenre=$l_journal) then 
				if (pub:publication/source:source/dc:identifier[@xsi:type='eterms:CONE']) 
				then 'CONE'
				
				else if (pub:publication/source:source/dc:identifier[@xsi:type='eterms:ISSN']) 
				then 'ISSN'

				else ''
			else '']]>
	</variable>
	
	<!-- IdValue for the chosen idType -->
	<variable name="idValue">
		<![CDATA[
			if ($sourceGenre=$l_journal) then 
				if ($idType = 'CONE') 
				then normalize-space(pub:publication/source:source/dc:identifier[@xsi:type='eterms:CONE']/text())
				
				else if ($idType = 'ISSN') 
				then pub:publication/source:source/dc:identifier[@xsi:type='eterms:ISSN']/text()
				
				else ''
			else ''
		]]>
	</variable>

	<variable name="citationStyleForJournal">
		<![CDATA[
			if ($sourceGenre=$l_journal) then 
				func:getCitationStyleForJournal($idType,$idValue) 
			else ''
		]]>
	</variable>
</variables>

• define a new layout element in CSLD of Article, for instance, for Title:

<!--
	ARTICLE
-->
<cs-layout-definition name="article">
	<parameters>
		<valid-if><![CDATA[
			$genre = $l_article 
		]]></valid-if>
		<ends-with value="." />
	</parameters>
	<elements>
	
<!--			<layout-element ref="$debugBlock" />-->
		
		<layout-element ref="$authors" />
		
		<layout-element ref="$year" />

		<layout-element ref="pub:publication/dc:title/text()">
			<parameters>
				<valid-if>$citationStyleForJournal='default'</valid-if>
				<ends-with value="." />
			</parameters>
		</layout-element>
		<layout-element ref="pub:publication/dc:title/text()">
			<parameters>
				<valid-if>$citationStyleForJournal='Kurztitel_ZS_Band_Jahr'</valid-if>
				<starts-with value="[Journal-spec-title: "/>
				<ends-with value="]." />
				<font-style ref="BOLD"/>
			</parameters>
		</layout-element>
		...

• update src/test/resources/CitationStyles/Test/TestCollection.xml, line 2779 with journal CoNE id (only for testing purposes!)

  ...

  <dc:identifier xsi:type="eterms:CONE">http://dev-pubman.mpdl.mpg.de/cone/journals/resource/110978976477977</dc:identifier>

  ...

• run

  $mvn -Dtest=TestCitationManager test

Related links

• Citation Manager in Subversion.
• APA, AJP and JUS specifications
• Citation Style XML Schema
• Citation Mananager presentation for PubMan Days 2010 developer workshop.

Software Development Kit

Portable Document Format

Extensible Markup Language

Control of Named Entities

OpenURL Link Resolver

International Standard Serial Number

Control of Named Entities

Publication Management