Skip to content

An alternative to the cumbersome custom styling of BibTeX references.

License

Notifications You must be signed in to change notification settings

JustinWilkinson/ReferenceEngine

Repository files navigation

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.

Releases

No releases published

Packages

No packages published