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)

::: {#imp-collapsed .callout-important 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

::: {#nte-annex-b .callout-note 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

::: {#tip-annex-b .callout-tip 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

::: {#cau-annex-b .callout-caution 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

::: {#wrn-annex-b .callout-warning 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

::: {#imp-annex-b .callout-important 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

### Bullet list unnumbered

::::: my-bullet-list
::: my-bullet-list-header
Title for bullet list
:::

::: my-bullet-list-container
Here include bullet list
:::
:::::

### Bullet list numbered `#bul-`

:::::: {#bul-ID-text}
::::: my-bullet-list
::: my-bullet-list-header
Title for bullet list
:::

::: my-bullet-list-container
Here include bullet list
:::
:::::

Title for bullet list
::::::

### Package description

::::: my-package
::: my-package-header
Package Name
:::

::: my-package-container
Here include package description
:::
:::::

### Package description example

:::::: my-package
::: my-package-header
cranlogs: Download Logs from the 'RStudio' 'CRAN' Mirror
:::

:::: my-package-container

------------------------------------------------------------------------

{**cranlogs**}: [Download Logs from the RStudio CRAN Mirror](https://r-hub.github.io/cranlogs/) [@cranlogs]

------------------------------------------------------------------------

::: {layout="[10, 30]" layout-valign="center"}
![](img/chap05/logoi/logo-cranlogs-min.png){width="176"}

`r glossary("APIx", "API")` to the database of `r glossary("CRAN")` package downloads from the RStudio CRAN mirror. The database itself is at <http://cranlogs.r-pkg.org>, see <https://github.com/r-hub/cranlogs.app> for the raw API.
:::

RStudio publishes the download logs from their CRAN package mirror daily at http://cran-logs.rstudio.com.

This R package queries a web API maintained by R-hub that contains the daily download numbers for each package.

The RStudio CRAN mirror is not the only CRAN mirror, but it’s a popular one: it’s the default choice for RStudio users. The actual number of downloads over all CRAN mirrors is unknown.

{**cranlogs**}: Download Logs from the 'RStudio' 'CRAN' Mirror
::::
::::::

------------------------------------------------------------------------

::: {layout="[10, 30]" layout-valign="center"}
This is the first line.

And this is the second line.
:::

------------------------------------------------------------------------

And here is normal text again.

### TODO (checklist)

::::: my-checklist
::: my-checklist-header
TODO
:::

::: my-checklist-container
Here include checklist text
:::
:::::

Numbered TODO list (checklist) `#tdo`

:::::: {#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
:::
:::::

## Generating new box types

::: {#nte-test2 .callout-note}
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 cross reference on this page: @rep-test

See cross reference in another chapter: @sec-tidyselect