---
title: "Spreadsheet terminology"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Spreadsheet terminology}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# Purpose

This vignette provides a quick lookup of spreadsheet nomenclature, as used in the {aftables} package.

# Terminology

Certain language and conventions are used in the package to talk about spreadsheets.

A _workbook_ is a spreadsheet-like structure. It contains _tabs_ that are each named with a unique _tab title_. Each tab contains a _sheet_.

Sheets can be one of four _sheet types_ that dictate their content, layout and style:

1. A _cover_ sheet contains the title of the _workbook_ and information about the data it contains, who has produced it, etc
2. A _contents_ sheet contains a table showing the contents of the _workbook_ at a glance, with one row per _sheet_ (not including the cover or itself)
3. A _notes_ sheet contains a table with a lookup of note codes (e.g. '[note 1]') to their explanations
4. One or more _tables_ sheets contain statistical tables (the main purpose for the existence of the spreadsheet) or annexes of supporting information

The _cover_, _contents_ and _notes_ sheets can be considered _meta sheets_ because they provide contextual information about the _workbook_ and its contents.

_Sheets_ themselves are composed of inserted _elements_ that appear in the following row order (if present):

* a _sheet title_ to be displayed at the top of the sheet (user-provided)
* a _table count_ so users know how many tables are in the sheet (auto-generated)
* a _notes statement_ that declares if a table contains _notes_ (if applicable, auto-generated)
* a _blank cells statement_ that indicates the meaning behind any blank cells in a table (if applicable, user-provided)
* a _source statement_ to explain where the data came from (if applicable, user-provided)
* a _table_ that contains information as rows and columns (user-provided) and has a _table name_ (auto-generated) which appears as the 'name' of the marked-up table

# Example

This is an example xlsx output from the {aftables} package:

<div class="figure">
<img src="../man/figures/table-sheet-markup.png" alt="A spreadsheet produced by the aftables package. Four things have been marked with numbers. 1 points to the current tab, named Table_1. 2 points to the sheet title. 3 points to four rows of elements below the title and below the table, which refer to the number of tables in the sheet, the presence of notes, the meaning of blank cells and the data source. 4 points to the table." width="100%"/>
</div>

The labels in the image above highlight:

1. The _tabs_ and their _tab titles_, open on a _sheet_ called 'Table_1' (with each of the _meta sheets_ currently hidden).
2. The _sheet title_.
3. Several _elements_: the _table count_, the _notes statement_ (because the table contains notes), the _blank cells statement_ (because the table contains blank cells) and a _source statement_ for the data.
4. A marked-up _table_, which contains suppressed values (i.e. '[c]') and notes (e.g. '[note 1]').

# Contribute

To contribute, please add [an issue](https://github.com/best-practice-and-impact/aftables/issues) or [a pull request](https://github.com/best-practice-and-impact/aftables/pulls) after reading [the code of conduct](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CODE_OF_CONDUCT.md) and [contributing](https://github.com/best-practice-and-impact/aftables/blob/main/.github/CONTRIBUTING.md) guidance.