CSL Next (CSLN)

# CSL Next (CSLN)

**A next-generation citation styling system for the scholarly ecosystem.**

CSLN is a ground-up reimagining of the [Citation Style Language](https://citationstyles.org/) (CSL), designed to make citation styles easier to write, maintain, and reason about—while remaining fully compatible with the existing ecosystem of 10,000+ styles.

## Table of Contents

- [Why CSLN?](#why-csln)
  - [The Problem with CSL 1.0](#the-problem-with-csl-10)
  - [The CSLN Solution](#the-csln-solution)
- [Key Design Principles](#key-design-principles)
- [Project Status](#project-status)
- [Architecture](#architecture)
- [For Style Maintainers](#for-style-maintainers)
- [For Developers](#for-developers)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## Why CSLN?

CSL 1.0 has been tremendously successful. It powers citation formatting in Zotero, Mendeley, Pandoc, and countless other tools. But after 15+ years of evolution, the XML-based format has accumulated complexity that makes styles difficult to author and maintain.

### The Problem with CSL 1.0

Consider this excerpt from APA 7th edition (`apa.csl`):

```xml
<macro name="author">
  <names variable="author">
    <name and="symbol" initialize-with=". " delimiter=", "/>
    <label form="short" prefix=" (" suffix=")" text-case="capitalize-first"/>
    <substitute>
      <names variable="editor"/>
      <names variable="translator"/>
      <choose>
        <if type="report">
          <text variable="publisher"/>
          <text macro="title"/>
        </if>
        <else-if type="legal_case">
          <text variable="title"/>
        </else-if>
        <!-- ... 50 more lines of conditionals ... -->
      </choose>
    </substitute>
  </names>
</macro>
```

This is **procedural code disguised as data**. The style embeds:
- Control flow (`<choose>`, `<if>`, `<else-if>`)
- Iteration (implicit in `<names>`)
- Fallback logic (`<substitute>`)
- Type-specific overrides scattered throughout

When you multiply this across an entire style file, you get **3,000+ lines of XML** that are nearly impossible to diff, review, or extend.

### The CSLN Solution

CSLN separates **what** from **how**:

```yaml
# csln-apa.yaml
info:
  title: APA 7th Edition

options:
  processing: author-date
  substitute:
    template: [editor, translator, title]
    contributor-role-form: short
  contributors:
    display-as-sort: first
    and: symbol
    shorten:
      min: 3
      use-first: 1

citation:
  template:
    - contributor: author
      form: short
    - date: issued
      form: year

bibliography:
  template:
    - contributor: author
      form: long
    - date: issued
      form: year
      wrap: parentheses
    - title: primary
      emph: true
```

**50 lines instead of 3,000.** The same semantic information, expressed declaratively.

## Key Design Principles

### 1. Declarative Over Procedural

Instead of encoding logic in the style, CSLN styles declare *intent*. The processor implements the logic once, correctly.

| CSL 1.0 | CSLN |
|---------|------|
| `<choose><if type="book">...</if></choose>` | `overrides: { book: { emph: true } }` |
| `<names><substitute>...</substitute></names>` | `options.substitute.template: [editor, title]` |
| 20 lines of et-al logic | `shorten: { min: 3, use-first: 1 }` |

### 2. Options First

Common behaviors are extracted to configuration, not scattered through templates:

- **Contributor formatting**: initialization, sorting, et-al rules
- **Date formatting**: precision, localization
- **Substitution**: what to show when author is missing
- **Processing mode**: author-date vs. note-based

### 3. Type-Safe Schema

CSLN uses strongly-typed enums, not strings:

```rust
pub enum ContributorRole {
    Author, Editor, Translator, Director, // ...
}

pub enum TitleType {
    Primary, ParentSerial, ParentMonograph,
}
```

Typos become compile errors. Invalid combinations are impossible.

### 4. Full Backward Compatibility

Every CSL 1.0 style can be automatically migrated to CSLN. We verify correctness by comparing output against [citeproc-js](https://github.com/Juris-M/citeproc-js), the reference CSL implementation.

### 5. High-Fidelity Data

CSLN prevents data loss by supporting:
- **EDTF Dates**: ranges, uncertainty, and approximations
- **Rich Text/Math**: mathematical notation and strict Unicode handling
- **Multilingualism**: scoped fields for multi-script data

### 6. Hybrid Architecture

The engine is built for dual-mode operation:
- **Batch**: High-throughput CLI for build systems (like Pandoc)
- **Interactive**: Low-latency JSON server mode for reference managers (like Zotero)

### 7. Stability & Forward Compatibility

CSLN is built for a long-lived ecosystem:
- **Explicit Versioning**: Styles include a `version` field for unambiguous schema identification.
- **Permissive Runtime**: The engine ignores unknown fields, allowing older versions of the processor to run newer styles

... (truncated)