---
title: "manual"
output:
  html_document:
    toc: true
vignette: >
  %\VignetteIndexEntry{manual}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

# General manual

This manual is a work in progress. In the meantime, please read the function documentation and refer to the documentation of [the companion package, `asar`](https://github.com/nmfs-ost/asar).

## Updating alternative text and captions

When a plotting function (e.g., `plot_biomass()`, `table_indices()`, `exp_all_figs_tables()`) is run, placeholders within the plot's associated alternative text and captions are replaced with key quantities (see the [`asar` package's Accessibility vignette](https://nmfs-ost.github.io/asar/articles/accessibility_guide.html) and/or the [`satf::write_captions()` function](https://github.com/nmfs-ost/satf/blob/master/R/write_captions.R) for more details).

As stated in the [Accessibility vignette's "Your to-do list" section](https://nmfs-ost.github.io/asar/articles/accessibility_guide.html#your-to-do-list), **you should always:**

**1. Check that these alternative texts and captions have been assembled correctly.**

**2. Write the final component of each figure’s alt text.**

Here's how to alter the alternative text and/or captions in `satf`, depending on what you wish to change:

### Add or Remove Text

Directly edit the rda's caption or alt_text objects. To do so, assign a new value to the text you wish to change. For example:

1. Locate your rda file. It may be called something like "biomass_figure.rda".

2. Load it into your R environment. You can do this by clicking the file or by using a command like this: `load("biomass_figure.rda")`. It will probably be called `rda`.

3. If you want to change the caption to "my new caption", you'd enter the following command: `rda[["cap"]] <- "my new caption"`. To change the alt text, you'd change "cap" to "alt_text" (e.g., `rda[["alt_text"]] <- "my new alt text"`.).

4. Save the changes to the rda's file (most likely you'll want to overwrite your original rda) by entering the following command: `save(rda, file = 'biomass_figure.rda')`.


**NOTE: Your edits will be lost if:**

- You regenerate (overwrite) the captions_alt_text.csv file
- You rerun `exp_all_figs_tables()` or that plot's function with the `make_rda` argument = T after regenerating the captions_alt_text.csv file.

We recommend saving a version of your altered text elsewhere to ensure you can reuse it if it were to be overwritten.

### Change/Update Arguments or Key Quantities

#### `exp_all_figs_tables()`

1.  Delete the captions_alt_text.csv file

2.  Rerun `exp_all_figs_tables()` with the correct arguments

**NOTE**: It is possible to directly edit the captions_alt_text.csv file to change the caption or alternative text. However, if you wish to do anything besides adding or removing text, we recommend using the two-step workflow, above, to avoid potential issues where an incorrect argument was used to calculate other (now incorrect) key quantities. For instance, `end_year` may be used to calculate values associated with F, which are then used to calculate other values.

#### Individual functions (e.g., `plot_biomass()`)

1. Open your function's R file and find the `topic_label` object. If you set the `relative` argument to TRUE, then choose the `topic_label` with "relative" in it (e.g., "relative.biomass").

2. Open your caps_alt_text.csv file.

3. Find the row in the caps_alt_text.csv file where the "label" column is the `topic_label`. Delete it.

4. Open the inst/resources/captions_alt_text_template.csv file. Find the row where the "label" column is the `topic_label`. Copy that row.

5. Paste the row into the caps_alt_text.csv file.

6. Rerun the function so that the key quantities are replaced correctly.

This process ensures that only the alt text and/or captions for your specific function are being changed, and not those associated with other plotting functions.