---
title: "getting-started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{getting-started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# Intro to ottrpal

`ottrpal` contains tools and functions to be used with an [OTTR repository](https://github.com/jhudsl/OTTR_Template) course.
It converts an [OTTR course](https://github.com/jhudsl/OTTR_Template/wiki) (Open-Source Tools for Training Resources) into a files ready for upload to Massive Open Online Courses (MOOCs): [Coursera](https://www.coursera.org/) and [Leanpub](https://leanpub.com/).

- Go to the [main OTTR guide](https://github.com/jhudsl/OTTR_Template/wiki) for how to start creating courses with OTTR.
- [Read the ottrpal package documentation here](https://jhudatascience.org/ottrpal/docs/index.html).

## Installing ottrpal:

You can install `ottrpal` from CRAN or from GitHub.

## Optional input files:

- [a `Book.txt` file](https://leanpub.com/lfm/read#leanpub-auto-booktxt-sampletxt-and-manuscript-files) which lists the order of the chapters/quiz files (this can be autogenerated with `ottrpal`) (see [example file](https://github.com/jhudsl/OTTR_Template/blob/main/manuscript/Book.txt)).  
- a directory containing quizzes in the form of `.md` files which have been written using the [Markua formatting specifications](https://leanpub.com/markua/read#leanpub-auto-quizzes-and-exercises) (see [example folder](https://github.com/jhudsl/OTTR_Quizzes/tree/main/quizzes)).  
- A TSV file specifying `url`,	`chapt_title`,	`img_path` See this (https://github.com/jhudsl/OTTR_Template/blob/main/resources/chapt_screen_images/chapter_urls.tsv).

## Set up an OTTR GitHub repository

Follow the [instructions here](https://github.com/jhudsl/OTTR_Template/wiki/Start-a-new-course) to set up your own OTTR GitHub repository for a new course.

## Running ottrpal

In the base of your OTTR repository, you can run this command to set up a Leanpub version of your course.
The `ottrpal` package converts your files using this base function, where `base_url` is where the OTTR course pages are published, the GitHub pages URL.

```
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/")
```

By default, `ottrpal` will re-run a `bookdown::render_book("index.Rmd")` rendering of your chapters first before converting the files to the Leanpub ready format.
However, if you wish to skip this step, you can set `render = FALSE` when running the `ottrpal::bookdown_to_embed_leanpub()` function.

## About the Book.txt file:

Leanpub requires a [`Book.txt`](https://leanpub.com/lfm/read#leanpub-auto-booktxt-sampletxt-and-manuscript-files) file to know what order the chapters/quizzes should be published.

By default, your `Book.txt` file will _not_ be autogenerated but `ottrpal` will look in your given directory for an existing `Book.txt` file which it will copy over to the output directory.

You can create a `Book.txt` file manually, or if your quizzes and chapters are numbered, `ottrpal` can create the `Book.txt` file based on the numbers going from low to high and quizzes following chapters of the same number.
(e.g. `quiz_03.md` will be placed after `03-some_chapter_file.Rmd`).

To have `ottrpal` attempt to autogenerate this file, set `make_book_txt` to `TRUE`.

```
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/",
                                   make_book_txt = TRUE)
```

If no `Book.txt` file is found and `make_book_txt` is set to `FALSE` (this is the default setting), `ottrpal` will fail.

A `ottrpal` autogenerated `Book.txt` file might look something like this:
```
index.Rmd
01-chapter.Rmd
quiz_1.md
02-chapter.Rmd
quiz_2.md
about.Rmd
```
Also note that any `index.Rmd` will always be placed first and any `about.Rmd` file will be placed last.

## Setting up quizzes:

By default, ottrpal will look for a folder called `quizzes/` to find your quiz `.md` files.
If your quizzes are located somewhere else, you will need to use the `quiz_dir` argument to specify that:

```
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/",
                                   make_book_txt = TRUE,
                                   quiz_dir = "some_directory")
```

If you don't have quizzes, you can say `quiz_dir = NULL` to skip all quiz steps.

## About the output files

Leanpub's Github writing mode will look for a directory called `manuscript` to publish from.
You should not edit the files in `manuscript/` by hand since a re-run of `ottrpal` will cause your changes to be overwritten.

## Adding footer text:

If there is text you would like added to the end of each chapter (like a link to a feedback survey for example), you can supply a character string to the `footer_text` argument in the main `ottrpal::bookdown_to_leanpub()` function.

```
# Set up a character string
survey_link <- "Please provide any feedback you have by filing a GitHub issue [here](https://github.com/jhudsl/OTTR_Template/issues)"

# Supply the footer text in the main function
ottrpal::bookdown_to_embed_leanpub(base_url = "https://jhudatascience.org/OTTR_Template/",
                                   make_book_txt = TRUE,
                                   footer_text = survey_link)
```

```{r}
sessionInfo()
```