chapter-writing-guidelines.qmd

---
title: Chapter Writing Guidelines
author: James A. Fellows Yates
bibliography: assets/references/chapter-writing-guidelines.bib
---

You're currently reading an introduction section of this page that demonstrates the standardised formatting that all chapters should follow to ensure consistency.
You do not need a specific section header for 'introduction'.

The main title of the page should go in the Markdown header at the top in the title section.
Your name should also go, as well as a distinct `bibliography` file that you should generate and place `bibtex` references in.
This file should be placed in the `assets/references` directory with exactly the same name as the name of this `.qmd` file but with the `.bib` extension.
The end of the introduction should cover the 'learning objectives' of the chapter.

## Language

The following language guidance is being displayed in a bullet point list using the hyphen character to indicate each item:

- All spelling should be in British English.
- Full stops should come after closing parentheses. 
    - For example (the full stop comes after the closing parenthesis).
- Voice should be in a 'collective' first person, as in 'we' or 'our'.

## Section Headings

All chapters should use section headings, up to a maximum of two sub-levels.
The heading above corresponds to the second level.

Mandatory headings are

- The title (specified in the markdown header block, by default a highest level)
- Summary (second-level header, indicated by two `##`)
- References (second-level header, indicated by two `##`)

### Sub-section heading

This header here corresponds to the maximum heading depth you can get to.
The purpose of this is to ensure that the document is easy to navigate and read.
You will see therefore that we never go further than three numbers in header references, e.g. 20.03.1

## Formatting

Generally, Quarto follows standard Markdown with some extra 'syntax' sugar. A Markdown cheatsheet can be found [here](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).

### General Markdown

- One sentence per line.
    
    i.e., this is bad:
    
    ```{verbatim}
    For example this is the first sentence. Here is the second sentence. This makes reviewing on GitHub harder.
    ```

    This is good:
    
    ```{verbatim}
    For example this is the first sentence.
    Here is the second sentence.
    This makes reviewing on GitHub easier.
    ```
- New paragraphs should be separated by a blank line.
    
    ```{verbatim}
    This would be a first sentence.
    Then a second sentence.

    Then a new paragraph.
    And so on.
    ```

To continue

- _Italic formatting_ should be used with a single underscore `_` and should be used for emphasis
- If required, **Bold formatting** should be used with double asterisks `**`. This should not be used for emphasis
    - Bold formatting should be used to indicate words for inclusion in a glossary, or to indicate the first word of bullet lists
- URLs should be both hyperlinked around a relevant bit of text
    - For example, for visit the [SPAAM Website](https://www.spaam-community.org/) this should be rendered visit the`[SPAAM Website](https://www.spaam-community.org/)`
    - This is to make sure URLs in printed copies of the textbook are still visible
- Bullet point lists must start with a capital letter and _not_ end with a full stop

### Notes and tips

For side nodes, tips, warnings, etc. you should [Quarto callout](https://quarto.org/docs/authoring/callouts.html#collapse) blocks.

For example.

```{verbatim}
::: {.callout-warning}
We reserve some callout formatting for specific objects!
:::
```

Gets rendered like this.

::: {.callout-warning}
We reserve some callout formatting for specific objects!
:::

See the [Chapter Content](#chapter-content) for the reserved formatting. Note: I rendered that within-page link with `[Chapter Content](#chapter-content)` syntax, where `#chapter-content` is the name of the header in all lowercase and all punctiation replaced with `-`.

### Code

Single backticks for inline code should only be used for single words such as tool names, e.g. `samtools`, file extensions such as `.txt`, or single paths `<path>/<to>/<here>`.

Any form of commands or code should be formatted as code in a syntax-named _triple_ backtick block.
Execution should be turned off by default for those languages that may auto-execute (i..e, R, with `eval=FALSE` in a code block header block), unless has a very low computational overhead and can be rendered on the fly.
Language should be specified.

For example, this is a bash code block that has a whole command.

```verbatim
    ```bash
    echo "SPAAM rules!"
    ```
```

And gets rendered as like this.

```bash
echo "SPAAM rules!"
```

If you wish to display _large_ output from a code block that _does_ get executed, you should turn off the command execution printing in the code block itself, and use a collapsible callout block with a 'Expand to see output' title immediately after the code block itself that contains.
The content of the output should also be in a triple backtick block, with the the `verbatim` syntax specified.

```bash
echo "SPAAM rules!"
```
::: {.callout-note collapse="true"}
## Expand see output

```bash
SPAAM rules!
```
:::

This was generated with

Another example, with setting `eval=FALSE` for R.

`````verbatim
```{.r eval=FALSE}
print('SPAAM Rules!')
```
`````

::: {.callout-note collapse="true"}
## Expand see output
`````verbatim
```{.r eval=FALSE}
[1] "SPAAM Rules!"
```
`````
:::

Additional guidance is as follows:

- Sentences prior a _code block_ must end in a full stop and not a colon
- All code blocks must have a language specified
- Do _not_ include leading `$` or other prompt indicators at the beginning of code blocks
    - This makes copy pasting harder
- Any paths to should ideally be relative to the 'working' directory of that chapter
    - This ensures portability of code between different systems and readers
- If paths require placeholders they should be in `<angle brackets>` 
- Any code that should not actually be run by the user should be wrapped in a 'warning' [callout block](#notes-and-tips)
- Optional 'self-guided' sections (i.e. sections that require user setup and would normally be already prepared for users by summer school organisers prior the summer school), should have be in a collapsed self-guided `.callout-note` with a title prefixed with `Self guided: `

### Figures

Figures should be included in the `assets/images/chapters/<your-chapter>/` directory.

They can be inserted into a chapter either with typical markdown syntax or with the HTML (e.g. for centering purposes).

Regardless of the method used, the image should be given a caption, and a quarto label with the `fig` prefix (`{#fig-<chapternamewithnopunctiation>-<imageidwithnopunctuation>}`) for referencing the figure in the text.

For example, the following.

```verbatim
![A mock up of a possible full-book jacket for this textbook. The left hand side includes a blurb and a list of contributors, and hte SPAAM logo. The right hand side includes the title of the book, a sankey diagram, and an 'edited by' section.](assets/images/jacket.png){#fig-chapterwritingguidelines-jacket}
```

Would be rendered as as follows.

![A mock up of a possible full-book jacket for this textbook. The left hand side includes a blurb and a list of contributors, and hte SPAAM logo. The right hand side includes the title of the book, a sankey diagram, and an 'edited by' section.](assets/images/jacket.png){#fig-chapterwritingguidelines-jacket}

It is important for the caption to be as descriptive as possible to account for accessibility reasons.

All figures should be referenced in the text using the quarto label, and without a leading 'Figure' (this is rendered for you) e.g,.

```{verbatim}
 "@fig-chapterwritingguidelines-jacket shows an example figure"
```

Gets rendered as:

"Figure @fig-chapterwritingguidelines-jacket shows an example figure".


### Tables

Much like figures, all markdown tables must have a caption and referenced in text.
To copy the quarto documentation example.

```{verbatim}
| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

: Demonstration of pipe table syntax {#tbl-chapterwritingguidelines-exampletable1}
```

Gets rendered as in @tbl-chapterwritingguidelines-exampletable1.

| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

: Demonstration of pipe table syntax {#tbl-chapterwritingguidelines-exampletable1}

This also applies to code-block generated tables e.g. as in @tbl-chapterwritingguidelines-examplecodetable2. For example the next code block (if wrapped in the triple-backticks with `r` syntax, not shown here).

```{verbatim}
    
    #| label: tbl-chapterwritingguidelines-examplecodetable2
    #| echo: false
    #| results: 'asis'
    #| tbl-cap: "Your caption goes here."
    #| tbl-cap-location: top
    library(tidyverse)
    library(pander)
    tibble(a = 1, b = 2) %>%
        pandoc.table(., split.tables = Inf)
    
```

Gets rendered as follows.

```{r, echo = F, message = F}
#| label: tbl-chapterwritingguidelines-examplecodetable2
#| echo: false
#| results: 'asis'
#| tbl-cap: "Your caption goes here."
#| tbl-cap-location: top
library(tidyverse)
library(pander)
tibble(a = 1, b = 2) %>%
    pandoc.table(., split.tables = Inf)
```

<!--
TODO fix
If your table is _too wide_, you may load the table and use some R code render the table in a more readable format.

To do so, place the CSV file in the `assets/images/chapters/<your-chapter>/` directory.
Then use the following template to render the table in your chapter. `.qmd` file.

```{verbatim}
#| label: tbl-<chaptername>-<figure id>
#| echo: false
#| warning: false
#| results: 'asis'
#| tbl-cap: <CAPTION_GOES_HERE>
#| tbl-cap-location: top

library(tidyverse)
library(gt)
# Load the data from CSV
data <- read_csv("assets/images/chapters/<chapter-name>/<filename>.csv")

# Create the table with gt
data %>%
    gt() %>%
    tab_options(
        table.width = pct(100),
        table.layout = "fixed",
        container.overflow.x = "scroll"
    )
```
-->

## Chapter Content

### Questions and Exercises

The end of every main section of the chapter (e.g. every second-level header) _should_ have a little 'task' or question to test the reader's understanding of the content.

These should be formatted as a Quarto callout block, with a renamed `callout-tip` class. 
This should be rendered in this 'reserved' call out block format.

```
::: {.callout-tip title="Question" appearance="simple"}
Your question(s) goes here.
:::

::: {.callout-note collapse="true" title="Answer"}
The answer(s) goes here, in a by-default 'hidden' block the reader can open to view.
:::
```

Gets rendered as

::: {.callout-tip title="Question" appearance="simple"}
Your question(s) goes here.
:::

::: {.callout-note collapse="true" title="Answer"}
The answer(s) goes here, in a by-default 'hidden' block the reader can open to view.
:::

### Data

There should be no data for practical tasks used on the chapter within the website repository.

All data should be be on Zenodo, or DOI-citable repository, and linked to from the chapter.
Institutional Nextcloud or other cloud storage solutions are not acceptable for data storage.
In most cases this will be stored for you by the course coorindator.

## Bibliography

Each chapters that use citations must have a '`References`' header as the last line of the document. 

Citations can be specified in the text using the `[@citation_key]` syntax.
This will automatically format the in text citation _with_ parentheses.
You _should not_ use 'free text' or write manual citations. 
The references and keys themselves should be stored in the `.bib` (`bibtex`) file that you have created and specified in the markdown header of the page.

For example this textbook is @Fellows-Yates2024-tg, or we really like AncientMetagenomeDir [@Fellows_Yates2021-rp].
For more citation styles please see the [Quarto documentation](https://quarto.org/docs/authoring/footnotes-and-citations.html).
All references made in text will be by default rendered at the _end_ of the document under the [References](#references) header.

## Summary

All chapters should have a summary section at the end. This should:

- Summarise the key points of the chaper 
- Summarise the main takeaway points the chapter 
- Should ideally be summarised in a few bullet points

## References