installation.qmd

---
title: "Installation"
engine: knitr
lightbox: true
---

```{r}
#| echo: false
tt <- function(x, y) {
    paste0('<a href="#" data-toggle="tooltip" title="',y,'">',x,'</a>')
}
```


Installing apaquarto is not hard, but it takes a bit more effort than installing a standalone program. There are four main steps:

1. Install Quarto
2. Install a programming language (e.g., R, Python, Julia)
3. Install a programming environment (e.g., RStudio, VS Code, Jupyter) 
4. Install apaquarto


## Install Quarto

The current stable version of Quarto can be installed [here](https://quarto.org/docs/get-started/). 

If you use a recent version of [RStudio](https://posit.co/download/rstudio-desktop/), Quarto is already installed. If you are not sure if your version of Quarto is recent enough, there is no harm in re-installing it.

:::{.callout-note collapse=true}
## How to check which version of Quarto is installed

In a [terminal](https://docs.posit.co/ide/user/ide/guide/tools/terminal.html), run

```{bash}
#| eval: false
#| filename: "Terminal"
quarto --version
```


:::

## Install a Programming Language 

Your primary options are

1. [R](https://www.r-project.org/)
2. [Python](https://www.python.org/)
3. [Julia](https://julialang.org/)
 

:::{.callout-tip collapse=true}

### What if I do not want to use any programming languages?

If you just want to use apaquarto to make APA-style documents, but do not plan to do any analyses, install R and RStudio. You do not need R for anything, but the Quarto experience will be easier in RStudio with R installed.
:::


## Install your programming environment

At the [same link for installing Quarto](https://quarto.org/docs/get-started/), there are links for selecting an environment for using Quarto. Your options include:

1. [RStudio](https://posit.co/download/rstudio-desktop/) will probably give the smoothest experience to anyone new to data analysis. It is made by Posit, the same company that makes Quarto.
2. [VS Code](https://code.visualstudio.com/) works for any language. Some R users really like VS Code. 
3. [Jupyter](https://jupyter.org/), as its name indicates, works with `Ju`lia, `Pyt`hon, and `R`.
4. [Neovim](https://neovim.io/), a hyperextensible Vim-based text editor
5. [Any text editor](https://quarto.org/docs/get-started/hello/text-editor.html) will do. Everyone has options---Quarto won't box you in.

# Install apaquarto

What do you wish to do with apaquarto? You can create a new template file in a new project folder, or you can add the apaquarto format to an existing Quarto file.

There are two ways to install Quarto extensions like apaquarto: If you are an R user, you might prefer the R console method. Anyone, including R users, can use the terminal method.


:::: {.panel-tabset .nav-pills}

### Via the terminal

First open the the terminal and navigate to the folder where you want to install apaquarto.




:::{.panel-tabset .nav.pills}

#### To create a new file

Run this in the terminal:

```{bash}
#| filename: "Terminal"
#| eval: false
quarto use template wjschne/apaquarto
```

#### Convert an existing document

Run this in the terminal:

```{bash}
#| eval: false
#| filename: "Terminal"
quarto add wjschne/apaquarto
```

:::

Entering the command above will prompt a question about whether you trust [the author](https://wjschne.github.io/) of the extension to not run malicious code. If you answer Yes, you will be prompted to name a new folder where the extension will be installed. Do not enter a complete file path. Just supply a folder name. This folder will be created in the folder you have navigated to.

:::{.callout-note collapse=true}

#### What is the terminal?

A terminal is an interface for telling your computer what to do. A terminal can be pulled up on most programming environments. For example, In RStudio, the terminal is in a tab next to the console (see @fig-console). If you cannot see a terminal tab next to the console, use the keyboard shortcut Alt-Shift-R to make a terminal appear (or  select *Tools &rarr; Terminal &rarr; New Terminal.* in the RStudio menu).

![RStudio terminal. It is okay if your console looks different from mine.](img/terminal.png){#fig-terminal}

Alternatively, you can open a terminal directly on any computer:

1. [Mac](https://support.apple.com/en-in/guide/terminal/welcome/mac): Click the Launchpad icon in the Dock, type Terminal in the search field, then click Terminal.
2. [Windows](https://www.wikihow.com/Open-Terminal-in-Windows): Click the Windows Start Icon (or press the {{< kbd Win >}} key), type `cmd`, select Command Prompt.
3. [Linux](https://www.wikihow.com/Open-a-Terminal-Window-in-Ubuntu): Press {{< kbd Ctrl+Alt+T >}}

:::

:::{.callout-note collapse=true}

#### How to nagivate to a folder

Suppose there is a folder on your computer at this location:

`C:/Users/myname/Documents/MyProject/`

The `cd` command means "change directory." Thus, entering this command will "navigate" you to your desired folder:

```{bash}
#| eval: false
#| filename: "Terminal"
cd "C:/Users/myname/Documents/MyProject/"
```


:::


:::{.callout-note collapse=true}

## Pasting commands into the terminal

In many terminals, the "paste" shortcut is different from what you might be used to (i.e., {{< kbd Ctrl+Shift+V >}} instead of {{< kbd Ctrl+V >}}). If that does not work, try right-clicking and selecting `paste`. If all else fails, just type the command.

:::

### Via the R console

If you are an R user, you can install extensions with the [quarto package](https://quarto-dev.github.io/quarto-r/) using the R Console. 

1. Set the working directory to the folder where you want the template to be installed. 
2. In the R console, run this code:

::: {.panel-tabset .nav-pills}

#### Create a new file

```{r consoletemplate}
#| eval: false
quarto::quarto_use_template("wjschne/apaquarto")
```


#### Convert an existing document

```{r}
#| eval: false
quarto::quarto_add_extension("wjschne/apaquarto")
```

:::



A prompt will ask if you trust  [the author](https://wjschne.github.io/) not to place malicious code on your machine. To proceed, answer `Yes` or just `Y`.



:::{.callout-note collapse=true}

#### What is the R Console?

The console is for entering R commands.  In RStudio, it is in the lower left pane by default. See @fig-console. It is okay if your console looks different from mine.

![RStudio console](img/console.png){#fig-console}

To use the console, type a command and press {{< kbd Enter >}}.
:::

:::{.callout-note collapse=true}

#### What is the quarto package?

The quarto package is not Quarto itself, but it provides convenient functions to  interact with Quarto. You will need a recent version of the quarto package (version 1.4 or higher).

If the quarto package is not installed, you can can install it by running this code in the console:

```{r installquartopackage}
#| eval: false
install.packages("quarto")
```

Alternatively, in RStudio's lower right pane:

1. Select the **Packages** tab.
2. Click the **Install** button.
3. Enter "quarto" in the input box.
4. Click **Install**.

:::

:::{.callout-note collapse=true}

## How to set the working directory

Suppose there is a folder on your computer at this location:

`C:/Users/myname/Documents/MyProject/`


You can set the working directory in the R console with this command

```{r setworkingdirectory}
#| eval: false
setwd("C:/Users/myname/Documents/MyProject/")
```


Alternatively, you can set the working directory in the RStudio menu:

1. Select *Session &rarr; Set Working Directory &rarr; Choose Directory*

![Set Working Directory Via RStudio Menu](img/menuworkingdirectory.png)

2. Navigate to a folder where you want to create a new folder.


:::



:::{.callout-note collapse=true}

#### How to skip the prompts

Run the `quarto_use_template` function with the `no_prompt` option set to `TRUE`:

```{r skipprompts}
#| eval: false
quarto::quarto_use_template("wjschne/apaquarto", no_prompt = TRUE)
```

:::

:::{.callout-note collapse=true}

#### How to inspect the code before installing it

The apaquarto source code is in [this repository](https://github.com/wjschne/apaquarto). Installing the extension will install the contents of the `_extensions/apaquarto` folder. If you install the template, it will install the `template.qmd` file and rename it to the name of the folder you install the template to. In addition, these files will be installed:

- bibliography.bib
- README.md
- example.qmd

:::



::::

### After installing apaquarto



If you made a...

#### A new file

If you create a new apaquarto file, you will see a template file in the folder you select. The template file will have the same name as the folder you installed the template to and ends with `.qmd`. 


The example.qmd file has most of the options already filled out and explains how and why to change them. It also has a examples of how to use the extension in the text.

It is recommended for RStudio users to use apaquarto inside a project. To create project for an existing directory, see  [here](https://support.posit.co/hc/en-us/articles/200526207-Using-RStudio-Projects). 


#### An existing file

Once the extension is installed, you still need to change the output format of your document. You can select one or more of three formats: .docx, .pdf, or .html. You can add all of these formats or any combination of them:

To include all four formats, add this to your .qmd file's yaml `format` option:

``` yaml
format:
  apaquarto-docx: default
  apaquarto-html: default
  apaquarto-pdf: default
  apaquarto-typst: default
```

When writing, I prefer to output to .html, because it renders quickly. Then I switch to .docx or .pdf, depending on where I need to submit the paper.


Here is a minimal example of what the YAML metadata might look like:

``` yaml
---
title: "My Paper's Title: A Full Analysis of Everything"
shorttitle: "My Paper's Title"
author:
  - name: W. Joel Schneider
    corresponding: true
    orcid: 0000-0002-8393-5316
    email: schneider@temple.edu
    affiliations:
      - name: Temple University
        department: College of Education and Human Development
        address: 1301 Cecil B. Moore Ave.
        city: Philadelphia
        region: PA
        postal-code: 19122-6091
abstract: "This is my abstract."
keywords: [keyword1, keyword2]
author-note:
  disclosures:
    conflict of interest: The author has no conflict of interest to declare.
bibliography: mybibfile.bib     
format:
  apaquarto-docx: default
  apaquarto-html: default
  apaquarto-pdf: default
  apaquarto-typst: default
---

```