97-callout-boxes.qmd

# Callout Boxes {#sec-annex-callout}

::: {.callout-note style="color: blue;"}
## This page is still under construction
:::


## Introduction

I am using five different types of cross references. Many numbered links refer to three different types of callout boxes:

1. [Quarto callout blocks](https://quarto.org/docs/authoring/callouts.html): These are five standard small callout boxes: Note, Tip, Important, Caution, and Warning. In contrast to the other two types of callout boxes I am not using menu tabs inside these boxes. (@sec-annex-callout-blocks)
2. [Theorems](https://quarto.org/docs/authoring/cross-references.html#theorems-and-proofs): These boxes are the commonly used theorems in articles and books in mathematics. There are ten theorem variations supported, each with their own label prefix: Theorem, Lemma, Corollary, Proposition, Conjecture, Definition, Example, Exercise, Solution, and Remark. I have changed most of these labels to highlight certain text types of my personal notes. Some of the theorems variation are used (partly with different name / label) as a collection of related R code chunks.
3. [Custom boxes](https://quarto.org/docs/authoring/cross-references-custom.html): As I needed more text types I have added several custom boxes. In contrast to the theorems and callout blocks is the numbering and title not in header but in an extra line above or under the box.
4. [Special cases](https://quarto.org/docs/authoring/cross-references.html#overview): Figures, Tables and Listings have special treatments. They are used inside R code chunks, have special  and have routines in {{< latex >}} to [generate listings](https://quarto.org/docs/authoring/cross-references.html#lists). You can also generate dynamic captions and labels. Unfortunately there is still a glitch in Quarto version 1.4.549 with `#lst-` for code listing: If you are using it inside the code chunk then the code is always visible, e.g., your `code-fold: true` argument does not work. I have therefore used the listings --- similar as custom boxes --- with the header as an extra top line.
5. [Citations](https://quarto.org/docs/authoring/footnotes-and-citations.html): I am using [Zotero](https://www.zotero.org/) to organize my citations and have all references collected into the `references.bib` file. 

## Quarto callout blocks {#sec-annex-callout-blocks}

In Quarto there are [five predefined callout blocks](https://quarto.org/docs/authoring/callouts.html#callout-types): note, tip, caution, warning and important. Callout boxes have different features.

### Default

#### With default title

::: {.callout-important}
This is the default mode for a callout block, in this case for callout type `important`.
:::

You can change the default title in `_quarto.yml`, for instance, with the line
`callout-important-title: "Your default title"`



#### With Header

::: {.callout-important}
## Callout with header
This is still the default mode for a callout block, but in this case with a header specified by you. 
:::

For this to happen you have either to provide the first line as a markdown header (e.g., `## Your default title`) or to add `title="Your default title"` in the definition line of the callout.

### Changing appearances

There are several ways to change the appearance of the callout.

#### Collapsed / Expanded (default)

::: {.callout-important #imp-collapsed collapse=true}
This is the default mode for a callout block of type `important`, but in this case collapsed.
:::

There is the expanded default mode but with `collapse=true` you can fold and therefore hide the text inside the callout. With clicking on the header users can open the callout box and read the text.

I haven't used the collapse mode in this book, because the text inside a closed box cannot be found with a browser search.

See cross-reference: @imp-collapsed


- If the first text line is a header starting with a sequence of `#` than the content of the header is included into the header of the callout block.
- If the definition line does not contain the code for cross references (starting with `{#nte-}`) than the box is not numbered. If you have provided a different title for the block (for instance in `_quarto.yml`) than this title will appear unnumbered at the block header.
- If you include `style="color: <color>;"` in the definition line, than the block text will be colored. You can use Hex code for the colors or color names, but --- as far as I know --- only the first color of the different 78 boxes in [R Charts Colors](https://r-charts.com/colors/) works, e.g. colors without a number behind the name.

I have used the [Quarto callout blocks](https://quarto.org/docs/authoring/callouts.html) in this book for the following purposes:

### Callout Note

::: {.callout-note #nte-annex-b style="color: blue;"}
### Differences between book and my notes {.unnumbered}

I am using this box to specify and rationalize my code changes with respect to the book’s code patterns.

For more theoretical or personal thoughts I have used the theorem variation "Remark."

There is a second usage of callout note without numbering: In this case it highlights the wording for the null and alternate hypotheses with the title "Wording for H0 and HA".
:::


See cross-reference: @nte-annex-b

### Callout Tip


::: {.callout-tip #tip-annex-b style="color: darkgreen;"}
### Until now (chapter 9, 2023-04-11) not used in this book {.unnumbered}

So far I haven't used the "Tip" callout box with numbering. As I have provided many theorems with different names I haven’t needed the tip box so far. Most of the tips are links collected under the theorem variation "Lemma" with the label "Resource". Sometimes I have written essential reminders for my learning activities into the "Important" box.

In the future, I will use it as a reminder for my own learning. It could contain also some links, but this box is not a link collection as the `resource` callout, but an argumentation and description what to learn.

But I have used this box without numbering with the label "Report". Under this heading I have summarized the analysis of data, mostly taken the text from the book. Sometimes I had to refer to another "Report" box to compare some wording. In this case I have added the custom box `#rep-` with the label "Report". 
:::

### Callout Caution

::: {.callout-caution #cau-annex-b style="color: darkgoldenrod;"}
### When to use the caution box? {.unnumbered}

> Caution is typically used to indicate a potential hazard that may cause minor injuries or damage if not taken seriously. It serves as a reminder to be careful and exercise caution in order to prevent accidents. ([Caution versus Warning](https://thisvsthat.io/caution-vs-warning))

In the context of this book I am using the caution box to draw attention to something. If you don't mind it will result in more complex work, results or other issues one should prevent. If you don't pay attention to the caution box then the chances for errors will grow.

So far I haven’t applied this callout box. But I have used very heavily the custom unnumbered box "Watch Out" (35x) with the same --- resp. similar --- purpose. I am planning to transfer these paragraphs to a numbered alternative either as custom box or as a caution callout box.
:::


### Callout Warning

::: {.callout-warning #wrn-annex-b style="color: darkorange;"}
### When to use the warning box? {.unnumbered}

> Warning is used to indicate a more serious and immediate danger that could result in severe injuries or even death if not heeded. It implies a higher level of urgency and demands immediate attention and action to avoid potential harm. ([Caution versus Warning](https://thisvsthat.io/caution-vs-warning))

In the context of this book I am using the warning box to prevent a mistake, a wrong procedure. If you don't mind it will result in an error or other glitch that will lead to  wrong results. If you don't pay attention to the warning blunder will occur.

So far I have used this callout box only 3 times. I have to check if these applications conforms with the purpose of the box.
:::




### Callout Important

::: {.callout-important #imp-annex-b style="color: red;"}
### Essential statements and take home messages {.unnumbered}

This box indicates crucial points, very often reminder to me to observe something or to learn something in greater detail or more thoroughly.

So far I haven't used this callout box, instead,I have applied an unnumbered custom box alternative 22 times. Again I am planning an transfer to a numbered alternative, possibly to this callout box.
:::


### Plain `callout` class 

::: {.callout}
## Exercise

You can also use a plain `callout` class to get a simple callout treatment.
:::


### Summary

|  Callout  |   Code  | CSS-style                     | Code Purpose / without Code       |
|:---------:|:-------:|-------------------------------|-----------------------------------|
|    Note   | `#nte-` | [style="color: blue;" ]{.nte} | Book differences / H0-HA          |
|    Tip    | `#tip-` | [style="color: darkgreen;"]{.tip}   | Learning reminder / Report  |
|  Caution  | `#cau-` | [style="color: darkgoldenrod;"]{.cau} | Pay attention             |
|  Warning  | `#wrn-` | [style="color: darkorange;"]{.wrn}    | Prevent mistake           |
| Important | `#imp-` | [style="color: red;"]{.imp}. | Crucial observations, definitions  |
: Purpose and appearances of callout boxes {#tbl-purpose-callout}


## Theorems and variations

All `theorem` boxes are provided in two forms: numbered and unnumbered.  They use the provided cross-reference code for numbering but their names are often changed for my purposes.

In the following collection I have provided the header with the following seqeunce:

- original name of `theorem` variant
- name in the output in parenthesis
- cross reference code

"Solution" and "Remark" are somewhat different as the other Theorems variants: They have a cursive header name.

### Conjecture (R Code) `#cnj-`

:::::{.my-r-code}
:::{.my-r-code-header}
:::::: {#cnj-ID-text}
: Numbered R Code Title
::::::
:::
::::{.my-r-code-container}
```{r}
#| label: code-chunk-name

1 + 1
```

::::
:::::


### Corollary (Assessment) `#cor-`

:::::{.my-assessment}
:::{.my-assessment-header}
:::::: {#cor-assess}
: Numbered Assessment Title
::::::
:::
::::{.my-assessment-container}
Here include  assessment text
::::
:::::


### Definition (Experiment) `#def-`

:::::{.my-experiment}
:::{.my-experiment-header}
:::::: {#def-experiment-text}
: Numbered Experiment Title
::::::
:::
::::{.my-experiment-container}
Here include text for experiment
::::
:::::

### Example (Example) `#exm-`
:::::{.my-example}
:::{.my-example-header}
:::::: {#exm-ID-text}
: Numbered Example Title
::::::
:::
::::{.my-example-container}
Here include example text
::::
:::::

### Exercise (Exercise) `#exr-`

:::::{.my-exercise}
:::{.my-exercise-header}
:::::: {#exr-ID-text}
: Numbered Exercise Title
::::::
:::
::::{.my-exercise-container}
Here include exercise text
::::
:::::



### Lemma (Resource) `#lem-`

:::::{.my-resource}
:::{.my-resource-header}
:::::: {#lem-resource-text}
: Numbered Resource Title
::::::
:::
::::{.my-resource-container}
Here include text for the resource
::::
:::::




### Proposition (Procedure) `#prp-`

:::::{.my-procedure}
:::{.my-procedure-header}
:::::: {#prp-ID-text}
: Numbered Procedure Title
::::::
:::
::::{.my-procedure-container}
Here include procedure text
::::
:::::

### Remark (*Remark*) `#rem-`

:::::{.my-remark}
:::{.my-remark-header}
:::::: {#rem-remark}
: Numbered Remark Title
::::::
:::
::::{.my-remark-container}
Here include remark text
::::
:::::


### Solution (*Solution*) `#sol-`

:::::{.my-solution}
:::{.my-solution-header}
:::::: {#sol-solution-text}
: Numbered Solution Title
::::::
:::
::::{.my-solution-container}
Here include text for the solution
::::
:::::



### Theorem (Formula) `#thm-`

:::::{.my-theorem}
:::{.my-theorem-header}
:::::: {#thm-theorem-text}
: Numbered Theorem Title
::::::
:::
::::{.my-theorem-container}
$$
\begin{align*}
\text{Here include text for the theorem}
\end{align*}
$$ {#eq-chapXY-formula}
::::
:::::

See @thm-theorem-text

## Custom boxes

:::::{.my-bullet-list}
:::{.my-bullet-list-header}
Title for bullet list
:::
::::{.my-bullet-list-container}
Here include bullet list
::::
:::::

***

:::::{.my-package}
:::{.my-package-header}
Package Name
:::
::::{.my-package-container}
Here include package description
::::
:::::


:::::{.my-checklist}
:::{.my-checklist-header}
TODO
:::
::::{.my-checklist-container}
Here include checklist text
::::
:::::



:::::: {#tdo-ID-text}
:::::{.my-checklist}
:::{.my-checklist-header}
Numbered TODO title
:::
::::{.my-checklist-container}
Here include checklist text
::::
:::::
Title for TODO List
:::



::: {#obj-chapXX}
:::::{.my-objectives}
:::{.my-objectives-header}
Objectives for Chapter XX
:::
::::{.my-objectives-container}
Here include solution text
::::
:::::
Achievements for chapter XX
:::


:::::: {#wat-ID-text}
:::::{.my-watch-out}
:::{.my-watch-out-header}
Numbered watch-out title
:::
::::{.my-watch-out-container}
Here include watch-out text
::::
:::::
Title for watch-out text
:::    



:::::: {#ipt-ID-text}
:::::{.my-important}
:::{.my-important-header}

Numbered important title
:::
::::{.my-important-container}
Here include important text
::::
:::::
Title for important text
:::


:::::{.my-typo}
:::{.my-typo-header}
Typo Title
:::
::::{.my-typo-container}
Here include typo text
::::
:::::




my-definition


## Generating new box types

::: {.callout-note #nte-test2}
Standard Box to compare.
:::


### Callout blocks with pre-defined name


::: {.solutionbox }

::::{.solutionbox-header} 
::::: {.solutionbox-icon}
:::::
::::::  {#sol-test}
:::::: 
This is my test for a new kind of solution box 
::::

:::: {.solutionbox-body } 
It uses a with pre-defined cross reference `#exm-`

And here comes some other content inside of it
::::

:::



::: {.solutionbox}

::::{.solutionbox-header} 
::::: {.solutionbox-icon}
:::::

This is my test solution box without numbering
::::

:::: {.solutionbox-body} 
And some content inside of it
::::

:::


See: @sol-test

### Callout block with custom name

::: {.my-bulletbox }

::::{.my-bulletbox-header} 
::::: {.my-bulletbox-icon}
:::::
::::::  {#bul-test}
:::::: 
: This is my test for a new kind of bullet list box 
::::

:::: {.my-bulletbox-body } 
It uses a with pre-defined cross reference `#bul-`

Ass you can see the generated number has a different header style
::::

:::

See: @bul-test

### Callout box with custom name


::: {.my-reportbox}

::::{.my-reportbox-header} 
::::: {.my-reportbox-icon}
:::::
::::::  {#rep-test}
:::::: 
: This is my test for a theorem box 
::::

:::: {.my-reportbox-body } 
I use a custom cross reference `#rep-`.

The percentage of uninsured residents in a county is a statistically significant predictor of the distance to the nearest syringe program (b = 7.82; p < .05) in our sample. For every 1% increase in uninsured residents in a county, the predicted distance to the nearest syringe program increases by 7.82 miles.

And here comes some other content inside of it
::::

:::


See: @rep-test