This is a protected page.

Prerequisites[edit]

java SDK 6
svn
maven
jEdit

Preparations[edit]

$svn co https://zim02.gwdg.de/repos/common/trunk/common_services

```
$cd common_services/citationmanager
```
check whether checkout can be compiled:
```
$mvn clean install
```
```
$cd src/main/resources/CitationStyles
```
```
$cp rm Default Test; rm -rf Test/.svn
```
add new citation style Test in the src/main/resources/Schemas/explain-styles.xml, define output-formats
get nice items-list XML from PubMan live, create src/test/resources/testFiles/Test directory, and save the XML into it under name TestCollection.xml.
changes in src/test/java/test/TestCitationManager.java:
1. define path to the new item list in the itemListsFIleNames hash
  put("Test", "target/test-classes/testFiles/Test/TestCollection.xml");
2. create new JUnit test new ctation style testCitationStyleTest.
3. set testCitationStyles to @Ignore

Citation Style specifications[edit]

See APA and AJP pages as platform for 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 basic for both CSLDs.

Authors[edit]

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[edit]

issued or published online. issued has higher priority.

Article[edit]

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

Book Chapter[edit]

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[edit]

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

global XMLs, i.e. all specified 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[edit]

Root Element[edit]

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[edit]

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[edit]

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
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 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)[edit]

are resulting layout elements of the citation style formatting. For the Test citation style the CSLDs are publication genre specific. The CSLD isNotPublication assures

	<!-- 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 procedure[edit]

Plain tests[edit]

Debugging life circle consists of 3 consequent steps: validation, compilation and output. Compilation should always take place after any changes in citation style configuration file in order to have a correct output.

start test with
```
$mvn -Dtest=TestCitationManager test
```
1. check console output and target/surefire-reports/test.TestCitationManager.txt for errors.
2. check generated outputs in formats: pdf and escidoc_snippet in target/ directory. The outputs should not be empty and have list of rendered citations.

Substantial tests[edit]

make possible to check the citations content. It helps to avoid some by-effects due to changes in the global functions and variables. It makes sense to run the tests after the plain tests.

update
generate escidoc_snippet output
copy
update items in testFiles/Test/TestCollection.xml

start test with

$mvn -Dtest=TestCitationStylesSubstantial test

New Citation Style HowTo

Contents