Update custom figures/tables vignette

vignettes/accessibility_guide.Rmd

@@ -183,7 +183,7 @@ recruitment_alt_text <- new_alt_text
 
 2.  Edit figure and table captions with the same process. Just substitute mentions of alt text with caption.
 
-3.  As stated earlier, if you see text that looks like a placeholder (e.g., "The x axis, showing the year, spans from B.start.year to B.end.year..."), that means that there was at least one instance where our tool failed to extract a specific value from the model results and substitute it into the placeholder. Please make sure that your alt text and captions contain the expected values before moving forward with your report. Check out the inst/resources/captions_alt_text_template.csv file in the `stockplotr` package to view the template with placeholders. The same package's `write_captions()` function shows how values are extracted from the model results and substituted into the placeholders.
+3.  As stated earlier, if you see text that looks like a placeholder (e.g., "The x axis, showing the year, spans from B.start.year to B.end.year..."), that means that there was at least one instance where our tool failed to extract a specific value from the model results and substitute it into the placeholder. Please make sure that your alt text and captions contain the expected values before moving forward with your report. Check out the inst/resources/captions_alt_text_template.csv file in the `stockplotr` package to view the template with placeholders.
 
 4. If you add a special character (e.g., percentage sign (%) or dollar sign ($); see [full list on this wiki page](https://en.wikibooks.org/wiki/LaTeX/Special_Characters#Other_symbols)), please add two backslashes before the character to avoid issues compiling your report later on (specifically, the conversion from Quarto to LaTeX via Pandoc, and then compilation of the LaTeX report after running `add_accessibility()` or `add_alttext()`). For example, "The 95% CI" would be written as "The 95\\\\% CI".
 

vignettes/snippets/add-plots_coding.Rmd

@@ -0,0 +1,207 @@
+### Add custom tables and figures {#sec-add-plots_coding}
+
+In your 'report' folder, open your figures and tables docs (probably named something like '08_tables.qmd' and '09_figures.qmd'). Add the following code there.
+
+**IMPORTANT**: The label in your captions/alt text csv must match the label in your plot's chunk options, **MINUS the "fig-" or "tab-"**. For example, the label "custom_table1" in the csv would match up properly with the "tbl-custom_table1" label in a code chunk.
+The same rule applies for figures: "custom_figure1" in the csv would match up with "fig-custom_figure1" in the chunk options' label.
+
+#### Tables
+
+Follow the instructions in the appropriate section below based on your table classification: reg_reg, reg_long, wide_reg, wide_long, ewide_reg, or ewide_long.
+
+For all table types, add a setup chunk to define your table and its caption:
+
+````{verbatim}
+```{r}
+#| label: 'tab-setup-custom'
+#| include: false
+
+# Example dataframe
+your_df <- data.frame(
+  "x" = c(1, 2, 3),
+  "y" = c(4, 5, 6)
+)
+
+# Example table
+your_table <- gt::gt(your_df)
+
+# Define your caption
+your_cap <- "This is the caption for my custom table."
+```
+````
+
+##### Regular tables (`reg_reg`)
+
+*Portrait orientation, fits on one page.*
+
+Add this chunk to display the table:
+
+````{verbatim}
+```{r}
+#| label: 'tbl-custom1'
+#| echo: false
+#| warning: false
+#| tbl-cap: !expr your_cap
+
+your_table
+```
+````
+
+##### Wide tables (`wide_reg`)
+
+*Landscape orientation, fits on one page.*
+
+Wrap the chunk in landscape braces:
+
+````{verbatim}
+::: {.landscape}
+
+```{r}
+#| label: 'tbl-custom-wide'
+#| echo: false
+#| warning: false
+#| tbl-cap: !expr your_cap
+
+your_table |>
+  gt::tab_options(table.width = pct(100), table.layout = 'auto') |>
+  gt::cols_width(everything() ~ pct(20))
+```
+
+:::
+````
+
+##### Long tables (`reg_long` or `wide_long`)
+
+*Splits by row across multiple pages. `wide_long` uses landscape; `reg_long` uses portrait.*
+
+You will need a separate chunk for each page of the split. For example, if your table requires 2 pages, repeat this chunk twice, changing the index in `grp_pull(1)` to `grp_pull(2)`.
+
+````{verbatim}
+```{r}
+#| label: 'tbl-custom-long-p1'
+#| echo: false
+#| tbl-cap: !expr paste0(your_cap, ' (Page 1 of 2)')
+
+your_table |>
+  gt::tab_options(table.width = pct(100), table.layout = 'auto') |>
+  gt::cols_width(everything() ~ pct(20)) |> 
+  asar::gt_split(row_every_n = 38) |> # Use 28 for wide_long
+  gt::grp_pull(1)                    # Change this to 2 for the next page
+```
+````
+
+> **NOTE**: For `wide_long`, wrap the chunk in `::: {.landscape}` braces. For example:
+
+````{verbatim}
+::: {.landscape}
+# code chunk shown above
+:::
+````
+
+##### Extra-wide tables (`ewide_reg`)
+
+*Landscape orientation, split by column across multiple pages.*
+
+Because extra-wide tables are split by column, you must have already run `export_split_tbls()` to create the `_split.rda` file. Load that split file to access the list of tables:
+
+````{verbatim}
+```{r}
+#| label: 'tbl-setup-ewide-split'
+#| include: false
+# Load the list of split tables generated by export_split_tbls()
+load(file.path(tables_dir, 'example_tab_table_split.rda'))
+table_list_split <- table_list
+```
+````
+
+Then, for each split table in the list, create a landscape chunk:
+
+````{verbatim}
+::: {.landscape}
+
+```{r}
+#| label: 'tbl-custom-ewide-c1'
+#| echo: false
+#| tbl-cap: !expr paste0(your_cap, ' (Column split 1 of 3)')
+
+table_list_split[[1]] |>
+  gt::tab_options(table.width = pct(100), table.layout = 'auto') |>
+  gt::cols_width(everything() ~ pct(20))
+```
+
+:::
+````
+
+##### Extra-wide, long tables (`ewide_long`)
+
+*Landscape orientation, split by both column AND row.*
+
+This requires a nested approach using the `table_list_split` loaded above. You must create chunks for every combination of column-split and row-split.
+
+````{verbatim}
+::: {.landscape}
+
+```{r}
+#| label: 'tbl-custom-ewide-long-c1-r1'
+#| echo: false
+#| tbl-cap: !expr paste0(your_cap, ' (Column split 1 of 2, Row split 1 of 3)')
+
+table_list_split[[1]] |>
+  gt::tab_options(table.width = pct(100), table.layout = 'auto') |>
+  gt::cols_width(everything() ~ pct(20)) |>
+  asar::gt_split(row_every_n = 28) |>
+  gt::grp_pull(1)
+```
+
+:::
+````
+
+The next chunk would be identical except for a different label, caption, and would have `gt::grp_pull(2)` instead of `gt::grp_pull(1)`, for instance. When adding the second split table, add `table_list_split[[2]]` instead of `table_list_split[[1]]`, then change the label, caption, and `gt::grp_pull()` as needed.
+
+##### Final step: page break
+
+If you are adding multiple tables, insert a page break between them:
+
+```{verbatim}
+{{< pagebreak >}}
+```
+
+#### Figures
+
+The workflow for figures is very similar to the workflow for regular tables.
+
+In your figures doc, add the following chunk to display the figure in your .qmd when it's rendered:
+
+````{verbatim}
+```{r} 
+#| label: 'fig-custom1' # choose a label
+#| echo: false
+#| warning: false
+#| fig-cap: !expr This is your figure caption.
+#| fig-alt: !expr This is your figure alternative text.
+# Import your data
+your_df <- data.frame(
+  "x" = c(1, 2, 3),
+  "y" = c(4, 5, 6)
+)
+
+# Make your figure
+your_figure <- ggplot2::ggplot(
+  your_df,
+  aes(
+    x = x,
+    y = y
+  )
+) +
+  ggplot2::geom_point()
+
+# Show your figure
+your_figure
+``` 
+````
+
+If you are adding another figure, add a page break first:
+
+```{verbatim}
+{{< pagebreak >}}
+```

vignettes/snippets/add-plots_img.Rmd

@@ -0,0 +1,83 @@
+### Add custom tables and figures {#sec-add-plots_img}
+
+In your 'report' folder, open your figures and tables docs (probably named something like '08_tables.qmd' and '09_figures.qmd'). Add the following code there.
+
+
+**IMPORTANT**: The label in your captions/alt text csv must match the label in your plot's chunk options, **MINUS the "fig-" or "tab-"**. For example, the label "your_image_label_name" in the csv would match up properly with the "tbl-your_image_label_name" label in this code:
+
+``` rmd
+![Your caption here](your_image.png){width=4in #fig-your_image_label_name}
+```
+
+The same rule applies for tables: "custom_table2" in the csv would match up with "tbl-custom_table2" in the markdown's label.
+
+#### Identify page orientation
+
+If you're using this workflow, your table/figure should be at most 8" wide or can be shrunken to 8" wide and still be legible. Find the width of your image file. Would you prefer to show it on a page with a portrait orientation (can fit 5" width) or landscape orientation (can fit 8" width)?
+
+Identify the preferred width of your image. Keep it in mind for when you add your image in the next section.
+
+#### Add image
+
+Next, add your image in this format ([see this Quarto documentation for more information](https://quarto.org/docs/authoring/figures.html)):
+
+``` markdown
+![Your caption here](your_image.png){width=___in #fig-your_image_label_name}
+```
+> **NOTE**: Remember that alternative text placed in this markdown format will not be put into your final report file; it must be in the captions_alt_text.csv file. However, *you must put the caption here*.
+
+> **NOTE**: It can be a headache to specify the correct image path. We recommend placing your files in either of these places:
+
+1.  Your report folder (path = the image name, like *image.png*)
+2.  A folder within your report folder (path = the relative filepath, like *images/image.png* if there's an images folder within report)
+
+Here are some examples, using the following example folder structure setup:
+
+``` markdown
+stock_assessments_2025/
+├── captions_alt_text.csv
+├── report/
+│   ├── 01_executive_summary.qmd
+│   ├── 02_introduction.qmd
+│   ├── my_custom_figure.png
+│   ├── images/
+│   │   ├── my_custom_table.png
+```
+
+``` markdown
+# Example 1
+![Here is my caption to my example figure.](my_custom_figure.png){width=3in #fig-custom_figure1}
+```
+
+``` markdown
+# Example 2
+![Here is my caption to my example table.](images/my_custom_table.png){width=5in #tab-custom_table1}
+```
+
+#### Add landscape braces (optional)
+
+If you'd like to place your image on a landscape-oriented page, you'll add [landscape braces](https://quarto.org/docs/authoring/article-layout.html#landscape-mode) before and after your table/figure to ensure it will be displayed properly, like this:
+
+```{verbatim}
+::: {.landscape}
+```
+
+``` rmd
+![Your caption here](your_image.png){width=___in #fig-your_image_label_name}
+```
+
+Then, add three colons to close the braces:
+
+```{verbatim}
+:::
+```
+
+> **NOTE**: Landscape braces only work in [Quarto v1.6+](https://quarto.org/docs/blog/posts/2024-11-25-1.6-release/). Please read [this Discussion](https://github.com/nmfs-ost/asar/discussions/186) to learn how to check your Quarto version and update it if necessary.
+
+#### Page break
+
+If you are including more than one custom table or figure in a file, we suggest adding a page break to separate the tables/figures:
+
+```{verbatim}
+{{< pagebreak >}}
+```