README

PHP library for validating, converting, and enhancing JATS (Journal Article Tag Suite) XML documents with advanced reference processing capabilities.

Features

JATS XML Validation: Validate against JATS schema (v1.3 supported)
Reference Management:
- Check for missing references and add placeholders
- Reorder references sequentially based on citation order
- Split combined references (e.g., [3,4] → [3] [4])
- Process bracketed citations and convert to proper JATS xref elements

Installation

composer require withanage/jats-converter

Requirements

PHP 8.0 or higher
DOM extension
libxml extension
(Optional) doi2jats package for DOI enhancement

Quick Start

Basic Usage

Command Line Interface

cd /vendor/withanage/
# list Help
php jats-converter/bin/jats-converter --help 

# Basic conversion
php jats-converter/bin/jats-converter input.xml output.xml

# With reference checking
php jats-converter/bin/jats-converter input.xml output.xml --reference-check

# Reorder references sequentially
php jats-converter/bin/jats-converter input.xml output.xml --reorder-references

# Split combined references
php jats-converter/bin/jats-converter input.xml output.xml --split-references

# Process bracketed citations
php jats-converter/bin/jats-converter input.xml output.xml --process-brackets

# Combine multiple features
php jats-converter/bin/jats-converter input.xml output.xml \
    --reorder-references \
    --split-references \
    --process-brackets \
    --reference-check \
    --detailed

Processing Modules

1. Reference Check

Validates that all citations in the document have corresponding references in the reference list and optionally adds placeholders for missing ones:

<!-- Before: Document has citations without references -->
<body>
  <p>Recent studies <xref ref-type="bibr" rid="ref1">[1]</xref> have shown that 
  climate change <xref ref-type="bibr" rid="ref2">[2]</xref> affects biodiversity 
  <xref ref-type="bibr" rid="ref3">[3]</xref>.</p>
</body>

<back>
  <ref-list>
    <ref id="ref1">
      <element-citation publication-type="journal">
        <article-title>Climate Study</article-title>
      </element-citation>
    </ref>
    <!-- ref2 and ref3 are missing! -->
  </ref-list>
</back>

<!-- After: Missing references detected and placeholders added -->
<back>
  <ref-list>
    <ref id="ref1">
      <element-citation publication-type="journal">
        <article-title>Climate Study</article-title>
      </element-citation>
    </ref>
    <ref id="ref2">
      <element-citation publication-type="placeholder">
        <person-group person-group-type="author"></person-group>
        Placeholder for missing reference: ref2. Please add appropriate citation details.
      </element-citation>
    </ref>
    <ref id="ref3">
      <element-citation publication-type="placeholder">
        <person-group person-group-type="author"></person-group>
        Placeholder for missing reference: ref3. Please add appropriate citation details.
      </element-citation>
    </ref>
  </ref-list>
</back>

Validation Output:

Found 3 citations, 1 references, 2 missing references

Missing reference(s): "ref2", "ref3"
  • Missing "ref2" → Line 45: [2] in context: ...climate change **[[2]]** affects biodiversity...
  • Missing "ref3" → Line 45: [3] in context: ...affects biodiversity **[[3]]**....

Added 2 placeholder references

2. Bracketed Citation Processor

Converts plain text bracketed citations into proper JATS xref elements:

<!-- Before -->
<p>Recent studies [1000] have shown...</p>

<!-- After -->
<p>Recent studies <xref ref-type="bibr" rid="ref1000">[1000]</xref> have shown...</p>

3. Reference Splitter

Splits combined reference citations:

<!-- Before -->
<xref ref-type="bibr" rid="ref3 ref4">[3,4]</xref>

<!-- After -->
<xref ref-type="bibr" rid="ref3">[3]</xref>
<xref ref-type="bibr" rid="ref4">[4]</xref>

4. Reference Reorderer

Renumbers references sequentially based on order of appearance:

<!-- Before: citations appear as [5], [2], [3] in text -->
<!-- After: renumbered as [1], [2], [3] with back-references reordered -->

CLI Options

Option	Description
`--schema-version, -s`	JATS schema version (default: 1.3)
`--reference-check, -c`	Check for missing references and add placeholders
`--reorder-references, -r`	Reorder references sequentially
`--split-references, -p`	Split combined references
`--process-brackets, -b`	Process bracketed citations
`--detailed, -d`	Display detailed conversion information
`--log-file, -l`	Log file path

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, questions, or contributions, please visit the GitHub repository.

Acknowledgments

Marco Grönewold (TIB)

Development

Dulip Withanage (TIB)

withanage / jats-converter

Maintainers

Package info

Statistics

Security