---
title: "BibTeX and CFF"
subtitle: A potential crosswalk
bibliography: REFERENCES.bib
author: Diego Hernangómez
description: >-
  This article presents a crosswalk between BibTeX and Citation File Format, as 
  it is performed by the cffr package.
abstract: >-
  This article introduces a crosswalk between **BibTeX** and the Citation File 
  Format (CFF) [@druskat_citation_2021], as implemented by the **cffr** package 
  [@hernangomez2021]. The crosswalk aims to facilitate seamless translation 
  between these two reference formats. Specifically, it proposes various 
  crosswalk models tailored to different **BibTeX** entry types 
  [@patashnik1988]. Additionally, the article includes practical examples using 
  real **BibTeX** entries and offers tips for developers interested in 
  implementing this crosswalk across various programming languages.
link-citations: yes
documentclass: article
editor_options:
  markdown:
    wrap: 80
output: 
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{BibTeX and CFF}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = ""
)

# Load the table of tables

p2file <- system.file("extdata/crosswalk_tables.csv", package = "cffr")

table_master <- read.csv(p2file)
```

## 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:

``` bib
@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**](https://en.wikipedia.org/wiki/BibTeX) is a well-known format for
storing references created by [Oren
Patashnik](https://en.wikipedia.org/wiki/Oren_Patashnik "Oren Patashnik") and
[Leslie Lamport](https://en.wikipedia.org/wiki/Leslie_Lamport "Leslie Lamport")
back in 1985. **BibTeX** can be reused by other software, such as
[LaTeX](https://en.wikipedia.org/wiki/LaTeX), to add references to scholarly
works. An example structure of a **BibTeX** entry would be:

``` bibtex
@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_2021], we can replicate this structure using the `bibentry()` and
`toBibtex()` functions:

```{r bibentry, comment="#>"}
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)
```

The final results of the entry as a text string would be coerced as[^1]:

[^1]: By default **R** Pandoc would generate the cite on the Chicago author-date
    format [@rmarkdowncookbook2020]

```{r echo=FALSE, results='asis'}
entry
```

Additionally, the **cffr** package [@hernangomez2021] 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::toBibtex()`).

```{r cffbibread, comment="#>"}
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

# To BibTeX with S3 method
toBibtex(cff_format)
```

## BibTeX Definitions

@patashnik1988 provides a comprehensive explanation of the **BibTeX** formats.
Let's distinguish between **Entries** and **Fields**.

### Entries {#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](https://en.wikipedia.org/wiki/Scribe_(markup_language))
    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**
[@biblatexpack], 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 {#fields}

Similar to the **Entries**, @patashnik1988 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 [@lamport86latex].
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 [@lamport86latex]. 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 [@lamport86latex].
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
@patashnik1988.

```{r entry_fields1, echo=FALSE}
df_table <- table_master[table_master$table == "entry_fields", -1]

nms <- c(
  "**field**", "**\\@article**", "**\\@book**", "**\\@booklet**",
  "**\\@inbook**", "**\\@incollection**", "**\\@conference, \\@inproceedings**",
  "**\\@manual**", "**\\@mastersthesis, phdthesis**", "**\\@misc**",
  "**\\@proceedings**", "**\\@techreport**", "**\\@unpublished**"
)


df_table[is.na(df_table)] <- ""
row.names(df_table) <- NULL
t1 <- df_table[, c(1:7)]
nm1 <- nms[1:7]

knitr::kable(t1,
  col.names = nm1, row.names = NA, align = c("l", rep("c", 6)),
  caption = "**BibTeX**, required fields by entry"
)
```

```{r entry_fields2, echo=FALSE}
t2 <- df_table[, c(1, 8:13)]
nm2 <- nms[c(1, 8:13)]
knitr::kable(t2,
  col.names = nm2, row.names = NA, align = c("l", rep("c", 6)),
  caption = "(cont) **BibTeX**, required fields by entry"
)
```

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](https://citation-file-format.github.io/))
[@druskat_citation_2021] consists of plain text files containing both human- and
machine-readable citation information for software and datasets. Within
[CFF]{.underline}, 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](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#preferred-citation),
and they may contain the following keys:

```{r refkeys, echo=FALSE, message=FALSE, warning=FALSE, results='asis'}
library(cffr)

# Fill with whites
init <- paste0("[", cff_schema_definitions_refs(), "]{.underline}")

l <- c(init, rep("", 4))


refkeys <- matrix(l, ncol = 5, byrow = TRUE)

knitr::kable(refkeys,
  row.names = NA,
  caption = "Valid keys on [CFF]{underline} `definition-reference` objects"
)
```

These keys are equivalent to the **BibTeX** [fields](#fields), with the
exception of the key [type]{.underline}. In [CFF]{.underline}, this key defines
the type of work[^2], making it analogous to the **BibTeX** [entries](#0).

[^2]: See a complete list of possible values of [CFF]{.underline}
    [type]{.underline} in [Appendix B](#appendix_cff_type).

## Proposed Crosswalk

The **cffr** package [@hernangomez2021] provides utilities for converting
**BibTeX** entries (via the **R** base function `bibentry()`) to
[CFF]{.underline} files and vice versa. This section describes how the
conversion between both formats has been implemented. The crosswalk is partially
based on @Haines_Ruby_CFF_Library_2021[^3].

[^3]: Note that this software performs only the conversion from
    [CFF]{.underline} to **BibTeX**, however **cffr** can perform the conversion
    in both directions.

In the following two sections, I present an overview of the proposed mapping
between the **Entries** and **Fields** of **BibTeX** and the [CFF]{.underline}
keys. After this initial mapping, I propose further transformations to enhance
compatibility between both systems using different [Entry Models](#entrymodels).

For better clarity, when a field is in **bold** (e.g., **\@book, edition**), it
corresponds to **BibTeX**, and when the field is [underlined]{.underline} (e.g.,
[book, edition]{.underline}), it corresponds to [CFF]{.underline}.

### Entry/Type Crosswalk

For converting general **BibTeX** entries to [CFF]{.underline}
[types]{.underline}, the following crosswalk is proposed:

```{r entry_bib2cff, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "entry_bib2cff", c(2:4)]
df_table[is.na(df_table)] <- ""
# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
row.names(df_table) <- NULL

knitr::kable(df_table,
  col.names = c("**BibTeX** Entry", "[**CFF key: type**]{.underline}", "Notes"),
  row.names = NA,
  caption = "Entry/Type crosswalk: From **BibTeX** to [CFF]{.underline}"
)
```

The previous crosswalk has the following specifications:

-   **\@book**, **\@inbook**, and **\@incollection** are closely related in
    **BibTeX**[^4]. 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]{.underline} allows keys `type:book` and
    `collection-type: book`, we may utilize a combination of these fields to tag
    each entry type in [CFF]{.underline} accordingly.
-   **\@mastersthesis** and **\@phdthesis** would be tagged using a combination
    of `type:thesis` and `thesis-type`.

[^4]: Note that **BibLaTeX** [@biblatexpack] handles **\@inbook** differently,
    see [Appendix A](#appendix_inbook).

Additionally, considering that [CFF]{.underline} allows for a wide range of
values[^5] for the [type]{.underline} field, the following conversion would be
applied from [CFF]{.underline} to **BibTeX**:

[^5]: See [Appendix B](#appendix_cff_type) for all possible values. Information
    extracted from @druskat2019.

```{r entry_cff2bib, echo=FALSE,results='asis'}
df_table <- table_master[table_master$table == "entry_cff2bib", c(2:4)]
df_table[is.na(df_table)] <- ""
# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
row.names(df_table) <- NULL

knitr::kable(df_table,
  col.names = c("[**CFF key: type**]{.underline}", "**BibTeX** Entry", "Notes"),
  caption = "Entry/Type crosswalk: From [CFF]{.underline} to **BibTeX**"
)
```

### Fields/Key Crosswalk

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

```{r fields_bib2cff, echo=FALSE,results='asis'}
df_table <- table_master[table_master$table == "fields_bib2cff", c(2:4)]
df_table[is.na(df_table)] <- ""
# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
row.names(df_table) <- NULL

knitr::kable(df_table,
  col.names = c("**BibTeX Field**", "[CFF key]{.underline}", "Notes"),
  caption = "**BibTeX** - [CFF]{.underline} Field/Key crosswalk"
)
```

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]{.underline} keys (such as **annote**, **crossref**, and **key**).
    Regarding the **type** field, the [CFF]{.underline} key [type]{.underline}
    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]{.underline} becomes more complex when related to institutions,
    resulting in varying final mappings in [CFF]{.underline}. When converting
    from [CFF]{.underline} to **BibTeX**, we propose to follow the same
    entry-based logic, using the key [location]{.underline} as a fallback value
    when converting to **address**.

-   In relation with this complexity mentioned above, **institution,
    organization** and **school** would be mapped to [institution]{.underline}.

-   **series** would be mapped to [collection-title]{.underline} 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]{.underline}
    only for those entries that do not require **booktitle**. In practice, this
    means that [collection-title]{.underline} 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]{.underline} to **BibTeX**, we propose to use
    [date-published]{.underline} 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]{.underline}, [end: 5]{.underline} in
    [CFF]{.underline}.

#### BibLaTeX

Additionally, there are other [CFF]{.underline} keys that correspond to
**BibLaTeX** fields. We propose to include these fields in the crosswalk[^6],
even though they are not part of the core **BibTeX** fields definition.

[^6]: See @biblatexcheatsheet for a preview of the accepted **BibLaTeX** fields.

```{r fields_biblatex2cff, echo=FALSE,results='asis'}
df_table <- table_master[table_master$table == "fields_biblatex2cff", c(2:3)]
df_table[is.na(df_table)] <- ""
# fix links
df_table$f2 <- gsub("link_to_entry_models", "#entrymodels", df_table$f2)
row.names(df_table) <- NULL

knitr::kable(df_table,
  col.names = c("**BibLaTeX Field**", "[CFF key]{.underline}"),
  caption = "**BibLaTeX** - [CFF]{.underline} Field/Key crosswalk"
)
```

## Entry Models {#entrymodels}

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](https://tug.org/texmf-docs/bibtex/xampl.bib)
file provided with the **bibtex** package [@patashnik].

### \@article {#article}

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

```{r model_article, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_article", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@article** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE}
toBibtex(cff_read_bib_text(bib))
```

### \@book / \@inbook {#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]{.underline} be treated
as a **\@book** with the following supplementary fields:

1.  [section]{.underline}: To denote the specific **chapter** within the book.
2.  [start-end]{.underline}: To indicate the range of **pages** covered by the
    section.

Additionally, note that in [CFF]{.underline}, the **series** field corresponds
to [collection-title]{.underline}, and the **address** field represents the
[publisher]{.underline}'s [address]{.underline}. By last, the key
[collection-type]{.underline} would be populated with [book-series]{.underline}.

```{r model_book, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_book", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@book / \\@inbook** Model"
)
```

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

**Examples: \@book**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r,  echo=FALSE}
toBibtex(cff_read_bib_text(bib))
```

**Examples: \@inbook**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@booklet {#booklet}

In **\@booklet** **address** is mapped to [location]{.underline}.

```{r model_booklet, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_booklet", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@booklet** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE, }
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE, }
toBibtex(cff_read_bib_text(bib))
```

### \@conference / \@inproceedings {#conf_inproc}

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

```{r model_inproceedings, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_inproceedings", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@conference / \\@inproceedings** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@incollection {#incol}

As **booktitle** is a required field, we propose to map that field to
[collection-title]{.underline} and the [type]{.underline} to
[generic]{.underline}. Therefore, an **\@incollection** is a [type:
generic]{.underline} with a [collection-title]{.underline} key.

Additionally, **series** and **type** would be ignored as there is not clear
mapping on [CFF]{.underline} for this field.

```{r model_incollection, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_incollection", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@incollection** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@manual

As in the case of [**\@conference** / **\@inproceedings**](#conf_inproc),
**organization** is mapped to [institution]{.underline}.

```{r model_manual, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_manual", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@manual** Model"
)
```

**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.

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@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]{.underline} So if [thesis-type]{.underline} contains a [regex
pattern](https://regex101.com/r/mBWfbs/1) `(?i)(phd)` it would be recognized as
**\@phdthesis**.

Additionally, **school** would be mapped to [institution]{.underline}.

```{r model_thesis, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_thesis", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@mastersthesis / \\@phdthesis** Model"
)
```

**Examples: \@mastersthesis**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r,  echo=FALSE}
toBibtex(cff_read_bib_text(bib))
```

**Examples: \@phdthesis**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@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]{.underline} as
[**\@incollection**](#incol), but in this case **booktitle** is not even an
option, so the proposed definition should cover both **\@misc** and
**\@incollection** without problems.

```{r model_misc, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_misc", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@misc** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@proceedings

The proposed model is consistent with [**\@conference** /
**\@inproceedings**](#conf_inproc). Note that **\@proceedings** does not
prescribe a **author** field. On this cases, as [authors]{.underline} is
required on [CFF]{.underline}, we would use *anonymous*[^7] when converting to
[CFF]{.underline} and omit it on the conversion from [CFF]{.underline} to
**BibTeX**.

[^7]: As proposed on [*How to deal with unknown individual
    authors?*](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#how-to-deal-with-unknown-individual-authors),
    **(Guide to Citation File Format schema version 1.2.0)**

```{r model_proceedings, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_proceedings", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@proceedings** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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*]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@techreport

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

```{r model_techreport, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_techreport", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@techreport** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

### \@unpublished

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

```{r model_unpublished, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "model_unpublished", c(2:4)]
df_table[is.na(df_table)] <- ""

# fix links
df_table$f3 <- gsub("link_to_entry_models", "#entrymodels", df_table$f3)
df_table$f3 <- gsub("link_to_article", "#article", df_table$f3)
df_table$f3 <- gsub("link_to_booklet", "#booklet", df_table$f3)
df_table$f3 <- gsub("link_to_book", "#book-inbook", df_table$f3)

row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("**BibTeX**", "[CFF]{.underline}", "Notes"),
  caption = "**\\@unpublished** Model"
)
```

**Examples**

**BibTeX entry**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

## Appendix A: **\@inbook** in BibTeX and BibLaTeX {#appendix_inbook}

The definition of **\@inbook** and **\@incollection** in **BibTeX**
[@patashnik1988] 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** [@biblatexpack] specifies:

> -   **\@inbook:** A part of a book which forms a self-contained unit with its
>     own title. Note that the [profile]{.underline} of this entry type is
>     [different from standard BibTeX]{.underline}, 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**

``` bibtex
@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]{.underline}

```{r echo=FALSE,}
bib <- "@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_read_bib_text(bib)
```

From [CFF]{.underline} to **BibTeX**

```{r echo=FALSE,}
toBibtex(cff_read_bib_text(bib))
```

## Appendix B: [CFF key:type]{.underline} values {#appendix_cff_type}

From @druskat2019 Table 4: Complete list of [CFF]{.underline} reference types.

```{r cff_types, echo=FALSE, results='asis'}
df_table <- table_master[table_master$table == "cff_types", c(2:3)]
df_table[is.na(df_table)] <- ""
row.names(df_table) <- NULL
knitr::kable(df_table,
  col.names = c("Reference type string", "Description"),
  row.names = NA,
  caption = "Complete list of [CFF]{.underline} reference types."
)
```

## References