Stylesheet contents

This page documents what a custom stylesheet is, how Edifix interprets it, and the practical limits to be aware of when adapting an existing stylesheet for use with the API.

The create_job and create_job_from_file endpoints both accept an optional stylesheet_contents body parameter. When provided, Edifix processes the job against the supplied stylesheet instead of a built-in editorial style, and the job's edit_style is recorded as custom.

For the request schema itself, see the API reference.

The canonical reference for the format is the eXtyles Advanced Processing Setup Guide.

Inheritance model

Edifix uses an inheritance model that provides a comprehensive set of built-in reference-restructuring defaults (a custom stylesheet only needs to declare the elements that differ from those defaults).

For example, to change only the punctuation after the year while inheriting all other defaults:

<Publisher name="*">
    <Definition>
        <Journal>*</Journal>
        <Reference type="jrn">
            <Struct item="Year"> Y: </Struct>
        </Reference>
    </Definition>
</Publisher>

NULL style (defaults-only behaviour)

Edifix cannot run jobs using only the built-in defaults. The closest defaults-only behaviour is the NULL (No Format) editorial style, which uses the following stylesheet:

<Publisher name="*">
<Definition>
    <Journal>*</Journal>
    <Citation Cit="1"/>
    <Citation_Punctiation>
    </Citation_Punctiation>
    <!-- Describe structure of journal reference -->
    <Reference type="*">
        <Restruct reference="no"/>
        <ChapterPunct type="." drop="no" move="out"/>
        <BookPunct type="." drop="no" move="out"/>
    </Reference>
    <Reference type="jrn">
        <Struct item="Reference">ZA. YTJVP.UWD</Struct>
        <Jrnl convert="abbr" dot="yes"/>
        <AuthorLim check="no"/>
        <LastPage required="no"/>
        <Authors insert-missing="yes"/>
        <ArticlePunct type="." drop="no" move="out"/>
    </Reference>
</Definition>
</Publisher>

Practical differences from an eXtyles RefStr.XSP file

If you are adapting a stylesheet for use with the Edifix API, two behaviours differ from a local XSP stylesheet file.

The API does not support INCLUDE directives in submitted stylesheets

The XSP stylesheet format supports <INCLUDE> directives that pull in another XSP file by path, for example:

<INCLUDE path="SomeOtherStyle.xsp"/>

<INCLUDE> is not supported in submitted stylesheets. Flatten your stylesheet into a single self-contained document before submitting it.

You must flatten any stylesheet before submitting by resolving all <INCLUDE> directives into a single document:

• Detect every <INCLUDE> directive at every level of nesting.
• Inline the referenced content while preserving order.
• Honour the duplicate-prevention behaviour of the format (reuse="yes" allows the same file to be inlined more than once).
• Submit a single self-contained XML document.

External data-file dependencies on the Jrnl element

The <Jrnl> element supports several attributes that point at external data files. Edifix's support for these is mixed.

The min-year-warn and max-year-warn attributes on <Jrnl> trigger warnings when a reference year falls outside a journal's known publication date range. Edifix evaluates these attributes against its built-in journal data, and the resulting warnings appear in the job_results JATS XML as <p content-type="warning"> elements inside each reference's <annotation> block.

basic-abbr-file, jrn-wrd-file, and jrn-param-file are all supported, but Edifix ignores their value and always uses its own built-in journal-abbreviation, journal-word, and journal-parameter data instead. add-abbr-file is not supported: it points to a customer-specific data file that the API cannot accept in the request.

Validation behaviour

The stylesheet_contents parameter accepts a single XML document in the XSP reference-restructuring format. A valid stylesheet must include <Publisher>, <Definition>, and <Reference> elements. An invalid or unparseable value returns error 0015. Supplying stylesheet_contents overrides any edit_style value in the request; Edifix records the job's edit_style as custom.

If stylesheet_contents is blank or omitted, you must specify edit_style (see Editorial styles).