Author: Diego Hernangómez

# BibTeX and CFF

### A potential crosswalk

#### Diego Hernangómez

Abstract

This article introduces a crosswalk between BibTeX and the Citation File Format (CFF) (Druskat et al. 2021), as implemented by the cffr package (Hernangómez 2021). The crosswalk aims to facilitate seamless translation between these two reference formats. Specifically, it proposes various crosswalk models tailored to different BibTeX entry types (Patashnik 1988). Additionally, the article includes practical examples using real BibTeX entries and offers tips for developers interested in implementing this crosswalk across various programming languages.

## Disclaimer

This article was reviewed and updated in 2024, along with the release of cffr v1.0.0.

## Citation

Please cite this article using this BibTeX entry:

    @article{hernangomez2022,
        title        = {{BibTeX} and {CFF}, a potential crosswalk},
        author       = {Diego Hernangómez},
        year         = 2022,
        journal      = {The {cffr} package},
        volume       = {Vignettes},
        doi          = {10.21105/joss.03900},
        url          = {https://docs.ropensci.org/cffr/articles/bibtex_cff.html}
    }

## BibTeX and R

BibTeX is a well-known format for storing references created by Oren Patashnik and Leslie Lamport back in 1985. BibTeX can be reused by other software, such as LaTeX, to add references to scholarly works. An example structure of a BibTeX entry would be:

    @book{einstein1921,
        title        = {Relativity: The Special and the General Theory},
        author       = {Einstein, A.},
        year         = 1920,
        publisher    = {Henry Holt and Company},
        address      = {London, United Kingdom},
        isbn         = 9781587340925
    }

In this case, the entry (identified as `einstein1921`) refers to a book. This entry can then be used in a document to include references to it. In R (R Core Team 2021), we can replicate this structure using the `bibentry()` and `toBibtex()` functions:

    entry <- bibentry("book",
      key = "einstein1921",
      title = "Relativity: The Special and the General Theory",
      author = person("A.", "Einstein"),
      year = 1920,
      publisher = "Henry Holt and Company",
      address = "London, United Kingdom",
      isbn = 9781587340925,
    )

    toBibtex(entry)
    #> @Book{einstein1921,
    #>   title = {Relativity: The Special and the General Theory},
    #>   author = {A. Einstein},
    #>   year = {1920},
    #>   publisher = {Henry Holt and Company},
    #>   address = {London, United Kingdom},
    #>   isbn = {9781587340925},
    #> }

The final results of the entry as a text string would be coerced as1:

Einstein A (1920). Relativity: The Special and the General Theory. Henry Holt and Company, London, United Kingdom. ISBN 9781587340925.

Additionally, the cffr package (Hernangómez 2021) incorporates the following capabilities that can be used to read and transform BibTeX format into different formats:

- `cff_read_bib()` reads *.bib files.
- `cff_read_bib_text()` can read BibTeX entries that are already stored in a variable.
- A S3 method `toBibtex.cff()` that converts from `cff` objects to Bibtex objects (see `utils::tpBibtex()`).

    string <- "@book{einstein1921,
        title        = {Relativity: The Special and the General Theory},
        author       = {Einstein, A.},
        year         = 1920,
        publisher    = {Henry Holt and Company},
        address      = {London, United Kingdom},
        isbn         = 9781587340925}"

    # To cff
    library(cffr)
    cff_format <- cff_read_bib_text(string)

    cff_format
    #> - type: book
    #>   title: 'Relativity: The Special and the General Theory'
    #>   authors:
    #>   - family-names: Einstein
    #>     given-names: A.
    #>   year: '1920'
    #>   publisher:
    #>     name: Henry Holt and Company
    #>     address: London, United Kingdom
    #>   isbn: '9781587340925'

    # To BibTeX with S3 method
    toBibtex(cff_format)
    #> @Book{einstein:1920,
    #>   title = {Relativity: The Special and the General Theory},
    #>   author = {A. Einstein},
    #>   year = {1920},
    #>   publisher = {Henry Holt and Company},
    #>   address = {London, United Kingdom},
    #>   isbn = {9781587340925},
    #> }

## BibTeX Definitions

Patashnik (1988) provides a comprehensive explanation of the BibTeX formats. Let’s distinguish between Entries and Fields.

### Entries

Each entry type defines a different type of work. The 14 entry types defined in BibTeX are:

1. @article: An article from a journal or magazine.
2. @book: A book with an explicit publisher.
3. @booklet: A work that is printed and bound, but without a named publisher or sponsoring institution.
4. @conference: Equivalent to @inproceedings, included for Scribe compatibility.
5. @inbook: A part of a book, which may be a chapter (or section) and/or a range of pages.
6. @incollection: A part of a book having its own title.
7. @inproceedings: An article in conference proceedings.
8. @manual: Technical documentation.
9. @mastersthesis: A Master’s thesis.
10. @misc: Use this type when nothing else fits.
11. @phdthesis: A PhD thesis.
12. @proceedings: The proceedings of a conference.
13. @techreport: A report published by a school or other institution, usually numbered within a series.
14. @unpublished: A document having an author and title, but not formally published.

Other implementations similar to BibTeX, such as BibLaTeX (Kime, Wemheuer, and Lehman 2023), expand the definitions of entries to include other types such as online resources, software, or datasets. In BibTeX, these entries should be reclassified as @misc.

In R, the `bibentry()` base function does not implement @conference. However, we can use @inproceedings, instead given that the definition is identical.

### Fields

Similar to the Entries, Patashnik (1988) also provides definitions for each of the possible standard BibTeX fields. While an entry must include certain required fields, it can also include additional fields that might be ignored in the raw implementation of BibTeX. Let’s explore some of these fields:

1. address: Typically represents the address of the publisher or another institution. In the case of @conference, @inproceedings and @proceedings this field indicates where the conference was held.
2. annote: An annotation. Although not used by standard bibliography styles, it may be relevant for producing annotated bibliographies.
3. author: Contains the name(s) of the author(s), following the format described in the LaTeX book (Lamport 1986).
4. booktitle: Refers to the title of a book, part of which is being cited. For @book entries, use the title field instead.
5. chapter: Indicates a chapter (or section) number.
6. crossref: Refers to the database key of the entry being cross-referenced.
7. edition: Specifies the edition of a @book, e.g., `"Second"`. The ordinal should have the first letter capitalized; standard styles convert to lowercase when necessary.
8. editor: Contains the name(s) of editor(s), following the conventions in the LaTeX book (Lamport 1986). If there is also an author field, the editor field specifies the editor of the book or collection where the reference appears.
9. howpublished: Describes how something unusual has been published. The first word should be capitalized.
10. institution: Represents the sponsoring institution of a technical report.
11. journal: Refers to the name of a journal.
12. key: Used for alphabetizing, cross-referencing, and creating a label when author information is missing.
13. month: Indicates the month in which the work was published or, for an unpublished work, when it was written. Use the standard three-letter abbreviation (e.g., `jan`, `feb`, `mar`) as described in Appendix B.1.3 of the LaTeX book (Lamport 1986).
14. note: Provides any additional information that can assist the reader. The first word should be capitalized.
15. number: Represents the number of a journal, magazine, technical report, or a work in a series. An issue of a journal or magazine is usually identified by its volume and number. Organizations issuing technical reports often assign them numbers, and sometimes books are given numbers within a named series.
16. organization: Refers to the organization that sponsors a @conference or publishes a manual.
17. pages: Specifies one or more page numbers or a range of numbers (e.g., `42--111` or `7,41,73--97` or `43+`).
18. publisher: Indicates the publisher’s name.
19. school: Provides the name of the school where a thesis was written.
20. series: Specifies the name of a series or set of books. When citing an entire book, the title field gives its title, and an optional series field provides the name of a series or multi-volume set in which the book is published.
21. title: Represents the work’s title.
22. type: Describes the type of a technical report (e.g., “Research Note”).
23. volume: Refers to the volume of a journal or multi-volume book.
24. year: Indicates the year of publication or, for an unpublished work, the year it was written. Generally, it should consist of four numerals (e.g., `1984`).

As in the case of the Entries, other implementations such as BibLaTeX recognize additional fields.

In BibTeX, there exists a strict relationship between Entries and Fields. Depending on the type of entry, certain fields are required, while others are optional or even ignored.

The following table summarizes the relationship between Entries and Fields in BibTeX. Required fields are flagged as x, and optional fields are flagged as o. For more detailed information, refer to Patashnik (1988).

BibTeX, required fields by entry
field | @article | @book | @booklet | @inbook | @incollection | @conference, @inproceedings
--- | --- | --- | --- | --- | --- | ---
address |  | o | o | o | o | o
annote |  |  |  |  |  |
author | x | x | o | x | x | x
booktitle |  |  |  |  | x | x
chapter |  |  |  | x | o |
crossref |  |  |  |  |  |
edition |  | o |  | o | o |
editor |  | x |  | x | o | o
howpublished |  |  | o |  |  |
institution |  |  |  |  |  |
journal | x |  |  |  |  |
key |  |  |  |  |  |
month | o | o | o | o | o | o
note | o | o | o | o | o | o
number | o | o |  | o | o | o
organization |  |  |  |  |  | o
pages | o |  |  | x | o | o
publisher |  | x |  | x | x | o
school |  |  |  |  |  |
series |  | o |  | o | o | o
title | x | x | x | x | x | x
type |  |  |  | o | o |
volume | o | o |  | o | o | o
year | x | x | o | x | x | x

(cont) BibTeX, required fields by entry
field | @manual | @mastersthesis, phdthesis | @misc | @proceedings | @techreport | @unpublished
--- | --- | --- | --- | --- | --- | ---
address | o | o |  | o | o |
annote |  |  |  |  |  |
author | o | x | o |  | x | x
booktitle |  |  |  |  |  |
chapter |  |  |  |  |  |
crossref |  |  |  |  |  |
edition | o |  |  |  |  |
editor |  |  |  | o |  |
howpublished |  |  | o |  |  |
institution |  |  |  |  | x |
journal |  |  |  |  |  |
key |  |  |  |  |  |
month | o | o | o | o | o | o
note | o | o | o | o | o | x
number |  |  |  | o | o |
organization | o |  |  | o |  |
pages |  |  |  |  |  |
publisher |  |  |  | o |  |
school |  | x |  |  |  |
series |  |  |  | o |  |
title | x | x | o | x | x | x
type |  | o |  |  | o |
volume |  |  |  | o |  |
year | o | x | o | x | x | o

It can be seen that only a subset of fields is necessary for any entry. For instance, title, year, and author are either required or optional in almost every entry, whereas crossref, annote, or key are never mandatory.

## Citation File Format

Citation File Format (CFF) (Druskat et al. 2021) consists of plain text files containing both human- and machine-readable citation information for software and datasets. Within CFF, there are two important keys: `preferred-citation` and `references`, which play a crucial role in citing and referring to related works:

- `preferred-citation`: Refers to another work that should be cited instead of the software or dataset itself.
- `references`: Includes reference(s) to other creative works related to the software or dataset. Similar to a list of references in a scholarly paper, these references may encompass papers describing the abstract concepts of the software or algorithms implemented in the software version.

These two keys are expected to be `definition.reference objects`, as defined in the Guide to Citation File Format schema version 1.2.0, and they may contain the following keys:

Valid keys on [CFF]{underline} `definition-reference` objects
abbreviation | abstract | authors | collection-doi | collection-title
collection-type | commit | conference | contact | copyright
data-type | database-provider | database | date-accessed | date-downloaded
date-published | date-released | department | doi | edition
editors | editors-series | end | entry | filename
format | identifiers | institution | isbn | issn
issue | issue-date | issue-title | journal | keywords
languages | license | license-url | loc-end | loc-start
location | medium | month | nihmsid | notes
number | number-volumes | pages | patent-states | pmcid
publisher | recipients | repository | repository-artifact | repository-code
scope | section | senders | start | status
term | thesis-type | title | translators | type
url | version | volume | volume-title | year
year-original |  |  |  |

These keys are equivalent to the BibTeX fields, with the exception of the key type. In CFF, this key defines the type of work2, making it analogous to the BibTeX entries.

## Proposed Crosswalk

The cffr package (Hernangómez 2021) provides utilities for converting BibTeX entries (via the R base function `bibentry()`) to CFF files and vice versa. This section describes how the conversion between both formats has been implemented. The crosswalk is partially based on Haines and The Ruby Citation File Format Developers (2021)3.

In the following two sections, I present an overview of the proposed mapping between the Entries and Fields of BibTeX and the CFF keys. After this initial mapping, I propose further transformations to enhance compatibility between both systems using different Entry Models.

For better clarity, when a field is in bold (e.g., @book, edition), it corresponds to BibTeX, and when the field is underlined (e.g., book, edition), it corresponds to CFF.

### Entry/Type Crosswalk

For converting general BibTeX entries to CFF types, the following crosswalk is proposed:

Entry/Type crosswalk: From BibTeX to CFF
BibTeX Entry | CFF key: type | Notes
--- | --- | ---
@article | article |
@book, @inbook | book | @inbook is a book with chapter and/or pages
@booklet | pamphlet |
@conference | conference-paper |
@incollection | generic | Needs additional fields
@inproceedings | conference-paper |
@manual | manual |
@mastersthesis, @phdthesis | thesis | Identified by thesis-type
@misc | generic |
@proceedings | proceedings |
@techreport | report |
@unpublished | unpublished |

The previous crosswalk has the following specifications:

- @book, @inbook, and @incollection are closely related in BibTeX4. While @inbook and @incollection both reference parts of a @book, the former is used for citing sections, chapters, pages, or other specific parts, whereas the latter is used for citing parts with a specific title. Since CFF allows keys `type:book` and `collection-type: book`, we may utilize a combination of these fields to tag each entry type in CFF accordingly.
- @mastersthesis and @phdthesis would be tagged using a combination of `type:thesis` and `thesis-type`.

Additionally, considering that CFF allows for a wide range of values5 for the type field, the following conversion would be applied from CFF to BibTeX:

Entry/Type crosswalk: From CFF to BibTeX
CFF key: type | BibTeX Entry | Notes
--- | --- | ---
book | @book, @inbook | @inbook is a book with section or start/end (reference to page number or range).
conference, conference-paper | @inproceedings |
article, magazine-article, newspaper-article | @article |
manual | @manual |
pamphlet | @booklet |
proceedings | @proceedings |
report | @techreport |
thesis | @mastersthesis, @phdthesis | Using thesis-type
unpublished | @unpublished |
generic | @misc, @incollection | @incollection is a generic with year,publisher,collection-title
<any other value> | @misc |

### Fields/Key Crosswalk

There is a significant similarity between the definitions and names of certain BibTeX fields and CFF keys. While the equivalence is straightforward in some cases, there are instances where certain keys need to be processed depending on the entry type.

BibTeX - CFF Field/Key crosswalk
BibTeX Field | CFF key | Notes
--- | --- | ---
address | Several possibilities | In BibTeX it may be the address of a publisher, conference, organization, institution or school.
annote | Not clear, won’t be mapped |
author | authors |
booktitle | collection-title |
chapter | section |
crossref | Not clear, won’t be mapped |
edition | edition |
editor | editors |
howpublished | medium |
institution, school, organization | institution | No overlapping on BibteX requirements
journal | journal |
key | Not clear, won’t be mapped |
month | month | Fallback: information in date-published
note | notes |
number | issue |
pages | start & end |
publisher | publisher |
series | collection-title if no booktitle |
title | title |
type | Won’t be mapped | This is a special key in CFF resembling the BibteX entry.
volume | volume |
year | year | Fallback: information in date-published

We provide more detail on some of the mappings presented in the table above:

- Some fields are not mapped because there is no clear equivalence with CFF keys (such as annote, crossref, and key). Regarding the type field, the CFF key type corresponds to the identifier of the work (similar to an entry in BibTeX), therefore, BibTeX type won’t be mapped. These fields are always optional in BibTeX.

- For the address field, its intended use in BibTeX varies depending on the entry type (e.g., for @inproceedings, it denotes the address of the conference, while for @mastersthesis/@phdthesis, is the address of the school, etc.). Mapping between BibTeX and CFF becomes more complex when related to institutions, resulting in varying final mappings in CFF. When converting from CFF to BibTeX, we propose to follow the same entry-based logic, using the key location as a fallback value when converting to address.

- In relation with this complexity mentioned above, institution, organization and school would be mapped to institution.

- series would be mapped to collection-title only on those entries that does not requires booktitle. In practice, this means that collection-title would correspond to booktitle for incollection and inproceedings, and in the rest of cases it would correspond to series. A consequence of this is that series information would be lost for incollection and inproceedings, but on those cases is an optional field.

- Regarding series, it would be mapped to collection-title only for those entries that do not require booktitle. In practice, this means that collection-title would correspond to booktitle for @incollection and @inproceedings, while in other cases it would correspond to series. As a consequence, series information would be lost for @incollection and @inproceedings, but in those cases, it is an optional field.

- When converting from CFF to BibTeX, we propose to use date-published as a fallback for extracting month and year fields.

- When pages is provided as a range separated by `--`, i.e, pages = {3–5} would be coerced as start: 3, end: 5 in CFF.

#### BibLaTeX

Additionally, there are other CFF keys that correspond to BibLaTeX fields. We propose to include these fields in the crosswalk6, even though they are not part of the core BibTeX fields definition.

BibLaTeX - CFF Field/Key crosswalk
BibLaTeX Field | CFF key
--- | ---
abstract | abstract
date | date-published
doi | doi
file | filename
isbn | isbn
issn | issn
issuetitle | issue-title
keywords | keywords
pagetotal | pages
translator | translators
url | url
urldate | date-accessed
version | version

## Entry Models

This section presents the specific mapping proposed for each of the BibTeX entries, providing further information on how each field is treated. Examples are adapted from the xampl.bib file provided with the bibtex package (Patashnik and Berry 2010).

### @article

The crosswalk of @article does not require any special treatment.

@article Model
BibTeX | CFF | Notes
--- | --- | ---
@article | type: article, magazine-article, newspaper-article |
author (required) | authors |
title (required) | title |
journal (required) | journal |
year (required) | year |
volume | volume |
number | issue |
pages | start and end |
month | month |
note | notes |

Examples

BibTeX entry

    @article{article-full,
        title        = {The Gnats and Gnus Document Preparation System},
        author       = {Leslie A. Aamport},
        year         = 1986,
        month        = jul,
        journal      = {{G-Animal's} Journal},
        volume       = 41,
        number       = 7,
        pages        = {73+},
        note         = {This is a full ARTICLE entry}
    }

CFF entry

    - type: article
      title: The Gnats and Gnus Document Preparation System
      authors:
      - family-names: Aamport
        given-names: Leslie A.
      year: '1986'
      month: '7'
      journal: G-Animal's Journal
      volume: '41'
      issue: '7'
      notes: This is a full ARTICLE entry
      start: 73+

From CFF to BibTeX

    @Article{aamport:1986,
      title = {The Gnats and Gnus Document Preparation System},
      author = {Leslie A. Aamport},
      year = {1986},
      month = {jul},
      journal = {G-Animal's Journal},
      volume = {41},
      number = {7},
      pages = {73+},
      note = {This is a full ARTICLE entry},
    }

### @book / @inbook

In terms of the fields required in BibTeX, the primary difference between @book and @inbook is that @inbook requires a chapter or page field, while @book does not even allow these fields as optional. Therefore, we propose that an @inbook entry in CFF be treated as a @book with the following supplementary fields:

1. section: To denote the specific chapter within the book.
2. start-end: To indicate the range of pages covered by the section.

Additionally, note that in CFF, the series field corresponds to collection-title, and the address field represents the publisher’s address. By last, the key collection-type would be populated with book-series.

@book / @inbook Model
BibTeX | CFF | Notes
--- | --- | ---
@book, @inbook | type: book | If section or start-end informed, it would be treated as @inbook
author (required) | authors | At least one of author,editor required
editor (required) | editors | At least one of author,editor required
title (required) | title |
publisher (required) | publisher |
year (required) | year |
chapter (required in @inbook only) | section | Not even optional in @book
pages (required in @inbook only) | start and end | Not even optional in @book
volume | volume |
number | issue |
series | collection-title |
address | address property of publisher |
edition | edition |
month | month |
note | notes |
type | Ignored | Only optional in @inbook

There are notable differences in how BibTeX and BibLaTeX handle the @inbook entry (further discussed in the Appendix A). We propose to treat a BibLaTeX @inbook as a BibTeX @incollection.

Examples: @book

BibTeX entry

    @book{book-full,
        title        = {Seminumerical Algorithms},
        author       = {Donald E. Knuth},
        year         = 1981,
        month        = 10,
        publisher    = {Addison-Wesley},
        address      = {Reading, Massachusetts},
        series       = {The Art of Computer Programming},
        volume       = 2,
        note         = {This is a full BOOK entry},
        edition      = {Second}
    }

CFF entry

    - type: book
      title: Seminumerical Algorithms
      authors:
      - family-names: Knuth
        given-names: Donald E.
      year: '1981'
      month: '10'
      publisher:
        name: Addison-Wesley
        address: Reading, Massachusetts
      collection-title: The Art of Computer Programming
      collection-type: book
      volume: '2'
      notes: This is a full BOOK entry
      edition: Second

From CFF to BibTeX

    @Book{knuth:1981,
      title = {Seminumerical Algorithms},
      author = {Donald E. Knuth},
      year = {1981},
      month = {oct},
      publisher = {Addison-Wesley},
      address = {Reading, Massachusetts},
      series = {The Art of Computer Programming},
      volume = {2},
      note = {This is a full BOOK entry},
      edition = {Second},
    }

Examples: @inbook

BibTeX entry

    @inbook{inbook-full,
        title        = {Fundamental Algorithms},
        author       = {Donald E. Knuth},
        year         = 1973,
        month        = 10,
        publisher    = {Addison-Wesley},
        address      = {Reading, Massachusetts},
        series       = {The Art of Computer Programming},
        volume       = 1,
        pages        = {10--119},
        note         = {This is a full INBOOK entry},
        edition      = {Second},
        type         = {Section},
        chapter      = {1.2}
    }

CFF entry

    - type: book
      title: Fundamental Algorithms
      authors:
      - family-names: Knuth
        given-names: Donald E.
      year: '1973'
      month: '10'
      publisher:
        name: Addison-Wesley
        address: Reading, Massachusetts
      collection-title: The Art of Computer Programming
      collection-type: book
      volume: '1'
      notes: This is a full INBOOK entry
      edition: Second
      section: '1.2'
      start: '10'
      end: '119'

From CFF to BibTeX

    @InBook{knuth:1973,
      title = {Fundamental Algorithms},
      author = {Donald E. Knuth},
      year = {1973},
      month = {oct},
      publisher = {Addison-Wesley},
      address = {Reading, Massachusetts},
      series = {The Art of Computer Programming},
      volume = {1},
      pages = {10--119},
      note = {This is a full INBOOK entry},
      chapter = {1.2},
      edition = {Second},
    }

### @booklet

In @booklet address is mapped to location.

@booklet Model
BibTeX | CFF | Notes
--- | --- | ---
@booklet | type: pamphlet |
title (required) | title |
author | authors |
howpublished | medium |
address | location |
month | month |
year | year |
note | notes |

Examples

BibTeX entry

    @booklet{booklet-full,
        title        = {The Programming of Computer Art},
        author       = {Jill C. Knvth},
        date         = {1988-03-14},
        month        = feb,
        address      = {Stanford, California},
        note         = {This is a full BOOKLET entry},
        howpublished = {Vernier Art Center}
    }

CFF entry

    - type: pamphlet
      title: The Programming of Computer Art
      authors:
      - family-names: Knvth
        given-names: Jill C.
      date-published: '1988-03-14'
      month: '2'
      location:
        name: Stanford, California
      notes: This is a full BOOKLET entry
      medium: Vernier Art Center
      year: '1988'

From CFF to BibTeX

    @Booklet{knvth:1988,
      title = {The Programming of Computer Art},
      author = {Jill C. Knvth},
      year = {1988},
      month = {feb},
      address = {Stanford, California},
      note = {This is a full BOOKLET entry},
      howpublished = {Vernier Art Center},
      date = {1988-03-14},
    }

### @conference / @inproceedings

Note that in this case, organization is mapped to institution. Additionally, series would be ignored as there is not clear mapping on CFF for this field.

@conference / @inproceedings Model
BibTeX | CFF | Notes
--- | --- | ---
@conference / @inproceedings | type: conference-paper, conference |
author (required) | authors |
title (required) | title |
booktitle (required) | collection-title and conference | Additionally collection-type would be populated as “proceedings”
year (required) | year |
editor | editors |
volume | volume |
number | issue |
series | Ignored |
pages | start and end |
address | address property of conference |
month | month |
organization | institution |
publisher | publisher |
note | notes |

Examples

BibTeX entry

    @inproceedings{inproceedings-full,
        title        = {On Notions of Information Transfer in {VLSI} Circuits},
        author       = {Alfred V. Oaho and Jeffrey D. Ullman and Mihalis Yannakakis},
        year         = 1983,
        month        = mar,
        booktitle    = {Proc. Fifteenth Annual ACM Symposium on the Theory of Computing},
        publisher    = {Academic Press},
        address      = {Boston},
        series       = {All ACM Conferences},
        number       = 17,
        pages        = {133--139},
        editor       = {Wizard V. Oz and Mihalis Yannakakis},
        organization = {The OX Association for Computing Machinery}
    }

CFF entry

    - type: conference-paper
      title: On Notions of Information Transfer in VLSI Circuits
      authors:
      - family-names: Oaho
        given-names: Alfred V.
      - family-names: Ullman
        given-names: Jeffrey D.
      - family-names: Yannakakis
        given-names: Mihalis
      year: '1983'
      month: '3'
      collection-title: Proc. Fifteenth Annual ACM Symposium on the Theory of Computing
      collection-type: proceedings
      publisher:
        name: Academic Press
      issue: '17'
      editors:
      - family-names: Oz
        given-names: Wizard V.
      - family-names: Yannakakis
        given-names: Mihalis
      institution:
        name: The OX Association for Computing Machinery
      start: '133'
      end: '139'
      conference:
        name: Proc. Fifteenth Annual ACM Symposium on the Theory of Computing
        address: Boston

From CFF to BibTeX

    @InProceedings{oaho_etall:1983,
      title = {On Notions of Information Transfer in VLSI Circuits},
      author = {Alfred V. Oaho and Jeffrey D. Ullman and Mihalis Yannakakis},
      year = {1983},
      month = {mar},
      booktitle = {Proc. Fifteenth Annual ACM Symposium on the Theory of Computing},
      publisher = {Academic Press},
      address = {Boston},
      editor = {Wizard V. Oz and Mihalis Yannakakis},
      number = {17},
      pages = {133--139},
      organization = {The OX Association for Computing Machinery},
    }

### @incollection

As booktitle is a required field, we propose to map that field to collection-title and the type to generic. Therefore, an @incollection is a type: generic with a collection-title key.

Additionally, series and type would be ignored as there is not clear mapping on CFF for this field.

@incollection Model
BibTeX | CFF | Notes
--- | --- | ---
@incollection | type: generic | Including a collection-title value
author (required) | authors |
title (required) | title |
booktitle (required) | collection-title | Additionally collection-type would be populated as “collection”
publisher (required) | publisher |
year (required) | year |
editor | editors |
volume | volume |
number | issue |
series | Ignored |
type | Ignored |
chapter | section |
pages | start and end |
address | address property of publisher |
edition | edition |
month | month |
note | notes |

Examples

BibTeX entry

    @incollection{incollection-full,
        title        = {Semigroups of Recurrences},
        author       = {Daniel D. Lincoll},
        year         = 1977,
        month        = sep,
        booktitle    = {High Speed Computer and Algorithm Organization},
        publisher    = {Academic Press},
        address      = {New York},
        series       = {Fast Computers},
        number       = 23,
        pages        = {179--183},
        note         = {This is a full INCOLLECTION entry},
        editor       = {David J. Lipcoll and D. H. Lawrie and A. H. Sameh},
        chapter      = 3,
        type         = {Part},
        edition      = {Third}
    }

CFF entry

    - type: generic
      title: Semigroups of Recurrences
      authors:
      - family-names: Lincoll
        given-names: Daniel D.
      year: '1977'
      month: '9'
      collection-title: High Speed Computer and Algorithm Organization
      collection-type: collection
      publisher:
        name: Academic Press
        address: New York
      issue: '23'
      notes: This is a full INCOLLECTION entry
      editors:
      - family-names: Lipcoll
        given-names: David J.
      - family-names: Lawrie
        given-names: D. H.
      - family-names: Sameh
        given-names: A. H.
      section: '3'
      edition: Third
      start: '179'
      end: '183'

From CFF to BibTeX

    @InCollection{lincoll:1977,
      title = {Semigroups of Recurrences},
      author = {Daniel D. Lincoll},
      year = {1977},
      month = {sep},
      booktitle = {High Speed Computer and Algorithm Organization},
      publisher = {Academic Press},
      address = {New York},
      editor = {David J. Lipcoll and D. H. Lawrie and A. H. Sameh},
      number = {23},
      pages = {179--183},
      note = {This is a full INCOLLECTION entry},
      chapter = {3},
      edition = {Third},
    }

### @manual

As in the case of @conference / @inproceedings, organization is mapped to institution.

@manual Model
BibTeX | CFF | Notes
--- | --- | ---
@manual | type: manual |
title (required) | title |
author | authors |
organization | institution |
address | address property of organization | On missing organization mapped to location
edition | edition |
month | month |
year | year |
note | notes |

Examples

BibTeX entry

Note that month can’t be coerce to a single integer in the range `1--12` as required on CFF, so it is ignored to avoid validation errors.

    @manual{manual-full,
      title        = {The Definitive Computer Manual},
        author       = {Larry Manmaker},
        year         = 1986,
        month        = {apr-may},
        address      = {Silicon Valley},
        note         = {This is a full MANUAL entry},
        organization = {Chips-R-Us},
        edition      = {Silver}
    }

CFF entry

    - type: manual
      title: The Definitive Computer Manual
      authors:
      - family-names: Manmaker
        given-names: Larry
      year: '1986'
      month: '4'
      notes: This is a full MANUAL entry
      institution:
        name: Chips-R-Us
        address: Silicon Valley
      edition: Silver

From CFF to BibTeX

    @Manual{manmaker:1986,
      title = {The Definitive Computer Manual},
      author = {Larry Manmaker},
      year = {1986},
      month = {apr},
      address = {Silicon Valley},
      note = {This is a full MANUAL entry},
      edition = {Silver},
      organization = {Chips-R-Us},
    }

### @mastersthesis / @phdthesis

In terms of field required on BibTeX, it is identical for both @mastersthesis and @phdthesis.

We propose here to identify each type of thesis using the key thesis-type So if thesis-type contains a regex pattern `(?i)(phd)` it would be recognized as @phdthesis.

Additionally, school would be mapped to institution.

@mastersthesis / @phdthesis Model
BibTeX | CFF | Notes
--- | --- | ---
@mastersthesis, @phdthesis | type: thesis | Use also thesis-type for identifying the thesis type.
author (required) | authors |
title (required) | title |
school (required) | institution |
year (required) | year |
type | Ignored |
address | address property of institution |
month | month |
note | notes |

Examples: @mastersthesis

BibTeX entry

    @mastersthesis{mastersthesis-full,
        title        = {Mastering Thesis Writing},
        author       = {Edouard Masterly},
        year         = 1988,
        month        = jun,
        address      = {English Department},
        note         = {This is a full MASTERSTHESIS entry},
        school       = {Stanford University},
        type         = {Master's project}
    }

CFF entry

    - type: thesis
      title: Mastering Thesis Writing
      authors:
      - family-names: Masterly
        given-names: Edouard
      year: '1988'
      month: '6'
      notes: This is a full MASTERSTHESIS entry
      institution:
        name: Stanford University
        address: English Department
      thesis-type: Master's Thesis

From CFF to BibTeX

    @MastersThesis{masterly:1988,
      title = {Mastering Thesis Writing},
      author = {Edouard Masterly},
      year = {1988},
      month = {jun},
      address = {English Department},
      note = {This is a full MASTERSTHESIS entry},
      school = {Stanford University},
    }

Examples: @phdthesis

BibTeX entry

    @phdthesis{phdthesis-full,
        title        = {Fighting Fire with Fire: Festooning {F}rench Phrases},
        author       = {F. Phidias Phony-Baloney},
        year         = 1988,
        month        = jun,
        address      = {Department of French},
        note         = {This is a full PHDTHESIS entry},
        school       = {Fanstord University},
        type         = {{PhD} Dissertation}
    }

CFF entry

    - type: thesis
      title: 'Fighting Fire with Fire: Festooning French Phrases'
      authors:
      - family-names: Phony-Baloney
        given-names: F. Phidias
      year: '1988'
      month: '6'
      notes: This is a full PHDTHESIS entry
      institution:
        name: Fanstord University
        address: Department of French
      thesis-type: PhD Thesis

From CFF to BibTeX

    @PhdThesis{phonybaloney:1988,
      title = {Fighting Fire with Fire: Festooning French Phrases},
      author = {F. Phidias Phony-Baloney},
      year = {1988},
      month = {jun},
      address = {Department of French},
      note = {This is a full PHDTHESIS entry},
      school = {Fanstord University},
    }

### @misc

The crosswalk of @misc does not require any special treatment. This entry does not require any field.

Note also that it is mapped to type: generic as @incollection, but in this case booktitle is not even an option, so the proposed definition should cover both @misc and @incollection without problems.

@misc Model
BibTeX | CFF | Notes
--- | --- | ---
@misc | type: generic |
author | authors |
title | title |
howpublished | medium |
month | month |
year | year |
note | notes |

Examples

BibTeX entry

    @misc{misc-full,
        title        = {Handing out random pamphlets in airports},
        author       = {Joe-Bob Missilany},
        year         = 1984,
        month        = oct,
        note         = {This is a full MISC entry},
        howpublished = {Handed out at O'Hare}
    }

CFF entry

    - type: generic
      title: Handing out random pamphlets in airports
      authors:
      - family-names: Missilany
        given-names: Joe-Bob
      year: '1984'
      month: '10'
      notes: This is a full MISC entry
      medium: Handed out at O'Hare

From CFF to BibTeX

    @Misc{missilany:1984,
      title = {Handing out random pamphlets in airports},
      author = {Joe-Bob Missilany},
      year = {1984},
      month = {oct},
      note = {This is a full MISC entry},
      howpublished = {Handed out at O'Hare},
    }

### @proceedings

The proposed model is consistent with @conference / @inproceedings. Note that @proceedings does not prescribe a author field. On this cases, as authors is required on CFF, we would use anonymous7 when converting to CFF and omit it on the conversion from CFF to BibTeX.

@proceedings Model
BibTeX | CFF | Notes
--- | --- | ---
@proceedings | type: proceedings |
title (required) | title and conference |
year (required) | year |
editor | editors |
volume | volume |
number | issue |
series | collection-title | Additionally collection-type would be populated as “proceedings”
address | address property of conference |
month | month |
organization | institution |
publisher | publisher |
note | notes |

Examples

BibTeX entry

    @proceedings{proceedings-full,
        title        = {Proc. Fifteenth Annual ACM Symposium on the Theory of Computing},
        year         = 1983,
        month        = mar,
        publisher    = {Academic Press},
        address      = {Boston},
        series       = {All ACM Conferences},
        number       = 17,
        note         = {This is a full PROCEEDINGS entry},
        editor       = {Wizard V. Oz and Mihalis Yannakakis},
        organization = {The OX Association for Computing Machinery}
    }

CFF entry

    - type: proceedings
      title: Proc. Fifteenth Annual ACM Symposium on the Theory of Computing
      authors:
      - name: anonymous
      year: '1983'
      month: '3'
      publisher:
        name: Academic Press
      collection-title: All ACM Conferences
      collection-type: proceedings
      issue: '17'
      notes: This is a full PROCEEDINGS entry
      editors:
      - family-names: Oz
        given-names: Wizard V.
      - family-names: Yannakakis
        given-names: Mihalis
      institution:
        name: The OX Association for Computing Machinery
      conference:
        name: All ACM Conferences
        address: Boston

From CFF to BibTeX

    @Proceedings{oz_etall:1983,
      title = {Proc. Fifteenth Annual ACM Symposium on the Theory of Computing},
      year = {1983},
      month = {mar},
      publisher = {Academic Press},
      address = {Boston},
      editor = {Wizard V. Oz and Mihalis Yannakakis},
      series = {All ACM Conferences},
      number = {17},
      note = {This is a full PROCEEDINGS entry},
      organization = {The OX Association for Computing Machinery},
    }

### @techreport

The crosswalk of @techreport does not require any special treatment.

@techreport Model
BibTeX | CFF | Notes
--- | --- | ---
@techreport | type: report |
author (required) | authors |
title (required) | title |
institution (required) | institution |
year (required) | year |
type | Ignored |
number | issue |
address | address property of institution |
month | month |
note | notes |

Examples

BibTeX entry

    @techreport{techreport-full,
        title        = {A Sorting Algorithm},
        author       = {Tom Terrific},
        year         = 1988,
        month        = oct,
        address      = {Computer Science Department, Fanstord, California},
        number       = 7,
        note         = {This is a full TECHREPORT entry},
        institution  = {Fanstord University},
        type         = {Wishful Research Result}
    }

CFF entry

    - type: report
      title: A Sorting Algorithm
      authors:
      - family-names: Terrific
        given-names: Tom
      year: '1988'
      month: '10'
      issue: '7'
      notes: This is a full TECHREPORT entry
      institution:
        name: Fanstord University
        address: Computer Science Department, Fanstord, California

From CFF to BibTeX

    @TechReport{terrific:1988,
      title = {A Sorting Algorithm},
      author = {Tom Terrific},
      year = {1988},
      month = {oct},
      address = {Computer Science Department, Fanstord, California},
      number = {7},
      note = {This is a full TECHREPORT entry},
      institution = {Fanstord University},
    }

### @unpublished

The crosswalk of @unpublished does not require any special treatment.

@unpublished Model
BibTeX | CFF | Notes
--- | --- | ---
@unpublished | type: unpublished |
author (required) | authors |
title (required) | title |
note (required) | notes |
month | month |
year | year |

Examples

BibTeX entry

    @unpublished{unpublished-minimal,
        title        = {Lower Bounds for Wishful Research Results},
        author       = {Ulrich Underwood and Ned Net and Paul Pot},
        note         = {Talk at Fanstord University (this is a minimal UNPUBLISHED entry)}
    }

CFF entry

    - type: unpublished
      title: Lower Bounds for Wishful Research Results
      authors:
      - family-names: Underwood
        given-names: Ulrich
      - family-names: Net
        given-names: Ned
      - family-names: Pot
        given-names: Paul
      notes: Talk at Fanstord University (this is a minimal UNPUBLISHED entry)

From CFF to BibTeX

    @Unpublished{underwood_etall,
      title = {Lower Bounds for Wishful Research Results},
      author = {Ulrich Underwood and Ned Net and Paul Pot},
      note = {Talk at Fanstord University (this is a minimal UNPUBLISHED entry)},
    }

## Appendix A: @inbook in BibTeX and BibLaTeX

The definition of @inbook and @incollection in BibTeX (Patashnik 1988) is as follows:

> - @inbook: A part of a book, which may be a chapter (or section) and/or a range of pages. Required fields: author or editor, title, chapter and/or pages, publisher, year (…)

> - @incollection: A part of a book having its own title. Required fields: author, title, booktitle, publisher, year (…)

Whereas BibLaTeX (Kime, Wemheuer, and Lehman 2023) specifies:

> - @inbook: A part of a book which forms a self-contained unit with its own title. Note that the profile of this entry type is different from standard BibTeX, see § 2.3.1. Required fields: author, title, booktitle, year/date (…).

When considering required fields, an important difference is booktitle requirement in BibLaTeX. Notably, BibTeX @incollection requires also this field. Moreover, both BibTeX @incollection and BibLaTeX @inbook emphasize its reference to “a part of a book (…) with its own title”.

In this document, the proposed crosswalk ensures full compatibility with BibTeX. Hence, we propose to consider a BibLaTeX @inbook entry as equivalent to a BibTeX @incollection, given the congruence in their definitions and field requirements.

Examples

BibTeX entry

    @inbook{inbook-biblatex,
        author       = {Yihui Xie and Christophe Dervieux and Emily Riederer},
        title        = {Bibliographies and citations},
        booktitle    = {{R} Markdown Cookbook},
        date         = {2023-12-30},
        publisher    = {Chapman and Hall/CRC},
        address      = {Boca Raton, Florida},
        series       = {The {R} Series},
        isbn         = 9780367563837,
        url          = {https://bookdown.org/yihui/rmarkdown-cookbook},
        chapter      = {4.5}
    }

CFF entry

    - type: generic
      title: Bibliographies and citations
      authors:
      - family-names: Xie
        given-names: Yihui
      - family-names: Dervieux
        given-names: Christophe
      - family-names: Riederer
        given-names: Emily
      collection-title: R Markdown Cookbook
      collection-type: collection
      date-published: '2023-12-30'
      publisher:
        name: Chapman and Hall/CRC
        address: Boca Raton, Florida
      isbn: '9780367563837'
      url: https://bookdown.org/yihui/rmarkdown-cookbook
      section: '4.5'
      year: '2023'
      month: '12'

From CFF to BibTeX

    @InCollection{xie_etall:2023,
      title = {Bibliographies and citations},
      author = {Yihui Xie and Christophe Dervieux and Emily Riederer},
      year = {2023},
      month = {dec},
      booktitle = {R Markdown Cookbook},
      publisher = {Chapman and Hall/CRC},
      address = {Boca Raton, Florida},
      isbn = {9780367563837},
      url = {https://bookdown.org/yihui/rmarkdown-cookbook},
      chapter = {4.5},
      date = {2023-12-30},
    }

## Appendix B: CFF key:type values

From Druskat et al. (2019) Table 4: Complete list of CFF reference types.

Complete list of CFF reference types.
Reference type string | Description
--- | ---
art | A work of art, e.g., a painting
article |
audiovisual |
bill | A legal bill
blog | A blog post
book | A book or e-book
catalogue |
conference |
conference-paper |
data | A data set
database | An aggregated or online database
dictionary |
edited-work | An edited work, e.g., a book
encyclopedia |
film-broadcast | A film or broadcast
generic | The fallback type
government-document |
grant | A research or other grant
hearing |
historical-work | A historical work, e.g., a medieval manuscript
legal-case |
legal-rule |
magazine-article |
manual | A manual
map | A geographical map
multimedia | A multimedia file
music | A music file or sheet music
newspaper-article |
pamphlet |
patent |
personal-communication |
proceedings | Conference proceedings
report |
serial |
slides | Slides, i.e., a published slide deck
software | Software
software-code | Software source code
software-container | A software container (e.g., a docker container)
software-executable | An executable software, i.e., a binary/artifact
software-virtual-machine | A virtual machine/vm image
sound-recording |
standard |
statute |
thesis | An academic thesis
unpublished |
video | A video recording
website |

## References

Druskat, Stephan, Jurriaan H. Spaaks, Neil Chue Hong, Robert Haines, and James Baker. 2019. “Citation File Format (CFF) - Specifications.” https://doi.org/10.5281/ZENODO.3515946.
Druskat, Stephan, Jurriaan H. Spaaks, Neil Chue Hong, Robert Haines, James Baker, Spencer Bliven, Egon Willighagen, David Pérez-Suárez, and Alexander Konovalov. 2021. “Citation File Format.” https://doi.org/10.5281/zenodo.5171937.
Haines, Robert, and The Ruby Citation File Format Developers. 2021. “Ruby CFF Library.” Zenodo. https://doi.org/10.5281/ZENODO.1184077.
Hernangómez, Diego. 2021. “cffr: Generate Citation File Format Metadata for R Packages.” Journal of Open Source Software 6 (67): 3900. https://doi.org/10.21105/joss.03900.
Kime, Philip, Moritz Wemheuer, and Philipp Lehman. 2023. “The biblatex Package.” https://osl.ugr.es/CTAN/macros/latex/contrib/biblatex/doc/biblatex.pdf.
Lamport, Leslie. 1986. LaTeX: A Document Preparation System. Reading, Mass: Addison-Wesley Pub. Co.
Patashnik, Oren. 1988. “BIBTEXTING.” https://osl.ugr.es/CTAN/biblio/bibtex/base/btxdoc.pdf.
Patashnik, Oren, and Karl Berry. 2010. “CTAN: Package Bibtex.” https://ctan.org/pkg/bibtex.
R Core Team. 2021. R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing; R Foundation for Statistical Computing. https://www.R-project.org/.
Rees, Clea F. 2017. “BibLaTeX Cheat Sheet.” https://osl.ugr.es/CTAN/info/biblatex-cheatsheet/biblatex-cheatsheet.pdf.
Xie, Yihui, Christophe Dervieux, and Emily Riederer. 2020. “Bibliographies and Citations.” In R Markdown Cookbook. The R Series. Boca Raton, Florida: Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown-cookbook.

1. By default R Pandoc would generate the cite on the Chicago author-date format (Xie, Dervieux, and Riederer 2020)↩︎

2. See a complete list of possible values of CFF type in Appendix B.↩︎

3. Note that this software performs only the conversion from CFF to BibTeX, however cffr can perform the conversion in both directions.↩︎

4. Note that BibLaTeX (Kime, Wemheuer, and Lehman 2023) handles @inbook differently, see Appendix A.↩︎

5. See Appendix B for all possible values. Information extracted from Druskat et al. (2019).↩︎

6. See Rees (2017) for a preview of the accepted BibLaTeX fields.↩︎

7. As proposed on How to deal with unknown individual authors?, (Guide to Citation File Format schema version 1.2.0)↩︎