A Citation Style Language (CSL) v1.0.1 processor for .NET.
C#
Latest commit 0960bb8 Jul 13, 2016 @fouke-boss Updated the binaries.

readme.md

CiteProc-.NET

CiteProc-.NET is a Citation Style Language (CSL) v1.0.1 processor written in C#.

Getting started

To start using CiteProc-.NET, create a new project in Visual Studio and add a reference to the CiteProc.dll assembly. Then start generating bibliographies and citations with just a few lines of code:

public void Example()
{
    // Load a style from disk (or use one of the overloads for reading
    // from a stream, a text reader or an xml reader).
    var style = File.Load("harvard-cite-them-right.csl");

    // Compile the style to get a processor instance.
    var processor = Processor.Compile(style);

    // Data of the referenced items (books, articles, etc.) is accessed
    // through the IDataProvider interface. CiteProc.NET comes with a
    // default implementation of this interface that supports the
    // CSL JSON format.
    processor.DataProviders = DataProvider.Load("items.json", DataFormat.Json);

    // Now, you are ready to render citations and bibliographies using
    // the selected style:
    var entries = processor.GenerateBibliography();

    // The result is an instance of a CiteProc.Formatting.Run class.
    // This instance can then be converted to the desired format. CiteProc
    // supports plain text and HTML out-of-the-box; the CiteProc.WpfDemo
    // project contains an example of how to show the result in a WPF
    // TextBlock. Other formats can be added easily.

    // Austen, J. (1995) Pride and Prejudice. New York, NY: Dover Publications.
    var plainText = entries.First().ToPlainText();

    // Austen, J. (1995) <i>Pride and Prejudice</i>. New York, NY: Dover Publications.
    var html = entries.First().ToHtml();
}

Dependencies

The CiteProc.dll assembly targets .NET framework 4.5, although I'm guessing it could be made to target earlier versions without much recoding. CiteProc.dll does not depend on any third-party components, and only a small number of System assemblies:

  • System.dll
  • System.Core.dll
  • System.Xml.dll

As it does not depend on any specific .NET language or UI technology, CiteProc-.NET can be used together with ASP.NET, WinForms, Windows Presentation Foundation, etc., in either C# or Visual Basic.NET.

CSL Compatibility

CiteProc-.NET aims to implement version 1.0.1 of the CSL specification, and currently supports the larger part of this specification. There is same more work ahead however, as the following features (marked in code by the FeatureNotSupportedException) are not yet supported (as of july 13, 2016):

  • Bibliography-specific options
  • Disambiguation
  • Cite grouping
  • Cite collapsing
  • Citation-specific options
  • Display attribute
  • Position and disambiguate conditions
  • Removing multiple spaces and punctuation
  • (not part of the CSL spec): parsing of raw dates and roman numbers in CSL JSON
  • (not part of the CSL spec): inline html in CSL JSON

CiteProc.Test

CiteProc-.NET comes with a CiteProc.Test.exe assembly, which contains:

  • A couple of code tests, for testing specific parts of the C# code.
  • A set of basic tests (not yet complete) for systematically testing the processing of each individual element and attribute of the CSL specification.
  • The CiteProc Test Suite as provided by Frank Bennett, the author of citeproc-js.

Running the CiteProc.Test.exe shows the results of these tests in the console. It also generates a log file (in the same folder as the CiteProc.Test.exe), which contains additional info on the failing tests, including a summary, showing the unsupported features (and the number of test cases failing because of them).

Currently, 416 of the available 826 test cases pass, while 92 of them fail (some more than others). The remaining 318 test cases fail because of features that are not yet supported, 153 of which because of unsupported test sections like CITATIONS, BIBSECTIONS and BIBENTRIES.

CiteProc.WpfDemo

CiteProc-.NET also comes with a small WPF demo that mimics the CSL style code editor. Currently, it's main goal is to demonstrate how to use CiteProc-.NET with Windows Presentation Foundation (WPF), but it might one day become a fully functional CSL editor.

Running this demo (by double clicking Binaries\CiteProc.WpfDemo.exe) gives you a first impression of the current capabilities and shortcomings of CiteProc-.NET.

Roadmap

Now that this first version is made public, the following work remains to be done:

  • Implementing the remaining unsupported features, at least the ones that are part of the CSL specification.
  • Completing the basic test set.
  • Add support for BibTeX and other formats.
  • Documentation, documentation, documentation.
  • Enhancing and expanding the CiteProc.WpfDemo project.