ReferenceEngine

Overview

• This repository contains a set of projects intended to help replace the cumbersome custom styling of BibTeX references with a simpler JSON alternative.
• Bibtex works really well with pre-built .bst files, however if you require references in a specific style which there isn't an existing .bst file for then you have to build your own.
• Unfortunately, .bst files use the complex Reverse Polish Notation that makes even the simplest changes challenging.
• Here's where ReferenceEngine can come in handy, as it can make use of simple, human readable JSON like that seen below.
• ReferenceEngine comes with a bibgen.exe executable that can then be used as a drop-in replacement for any referencing software.
• It also comes with a cross-platform User Interface to configure and save your personalised styles, which can then be exported to .style.json files.
• N.B. This is still in active development and does not yet fully support all options that Bibtex does.

Usage

• As mentioned above bibgen.exe can simply be used in place of Bibtex. It reads in a .bib file and formats it based on the contents of the .style.json file specified in the .tex file.
• The ReferenceEngine takes a collection of entry styles that look like the below sample, and applies the relevant styling to entries that match the type.

Sample JSON

{
  "Name": "Book Rule",
  "Type": "Book",
  "Fields": [
	{
	  "Type": "Field",
	  "Value": "Title",
	  "Enquote": true
	},
	{
	  "Type": "Constant",
	  "Value": "by"
	},
	{
	  "Type": "AuthorField",
	  "Format": {
		"Delimiter": ",",
		"FinalDelimiter": "and",
		"NumberOfNamedAuthors": 3,
		"TruncatedAuthorsText": {
		  "Italic": true,
		  "Value": "et al."
		}
	  },
	  "Suffix": ","
	},
	{
	  "Type": "Field",
	  "Italic": true,
	  "Value": "Pages",
	  "Prefix": "(p. ",
	  "Suffix": "),",
	},
	{
	  "Type": "Field",
	  "Value": "Year",
	  "Bold": true,
	  "Suffix": "."
	}
  ]
}

Sample Styling

Given the following Bibtex Entry:

@BOOK{
	AUTHOR = {Alice, Bob, Charlie, David and Eve},
	TITLE = {An Amazing Book},
	YEAR = {2020},
	PAGES = {20-30},
	CHAPTER = {Some Chapter}
}

The output would look like this:

[1] "An Amazing Book" by Alice, Bob, Charlie et al. (p. 20-30), 2020.

Code

ReferenceEngine.Bibtex

• A class library/nuget package to assist with parsing of .aux, and .bib files required to build a bibliography.
• ReferenceEngine.Bibtex also performs the translation to internal objects which can then be used to format entries as required.
• The highest level of abstraction is the BibliographyBuilder class, that constructs a Bibliography object which can then be written.
• The BibliographyBuilder can be instantiated as a service, as is seen in the below example, or directly by supplying objects to its constructor if preferred.

Sample Usage:

• In this example, we build a bibliography for a tex file using the default paths, though these can be overridden.
• N.B. This scenario requires the existence of the below paths. Note that the .aux file is usually generated by LaTeX.
  • C:\SomeFolder\SomeSubFolder\SomeFile.tex
  • C:\SomeFolder\SomeSubFolder\SomeFile.aux

// Build the IServiceProvider.
var serviceProvider = new ServiceCollection().AddBibliographyBuilder().BuildServiceProvider();

// Retrieves an instance of the BibliographyBuilder class from the IServiceProvider.
var bibliographyBuilder = serviceProvider.GetRequiredService<IBibliographyBuilder>();

var path = @"C:\SomeFolder\SomeSubFolder\SomeFile.tex";

// Sets properties of the Builder from the file.
var bibliography = bibliographyBuilder.FromFile(path).Build();

// Write the bibliography to "C:\SomeFolder\SomeSubFolder\SomeFile.bbl".
bibliography.Write();

ReferenceEngine.Generator

• A console app compiled into an executable called bibgen.exe, that makes use of ReferenceEngine.Bibtex to generate a bibliography for a .tex file.
• This executable can be added to the compilation process of LaTeX in place of any existing bibliography software, such as Bibtex.
• It also comes with sample .tex, .bib and .style.json files.

ReferenceEngine.Styles.UI

• An Electron.NET GUI to assist with the creation, editing and saving of different named styles.
• These configured styles can then be exported to a .style.json file which can be read by bibgen.exe and used to create the .bbl file used by LaTeX.

ReferenceEngine.Test

• An NUnit Test project containing tests for the solution.