# getting-started

# Intro to ottrpal

`ottrpal` contains tools and functions to be used with an OTTR repository course. It converts an OTTR course (Open-Source Tools for Training Resources) into a files ready for upload to Massive Open Online Courses (MOOCs): Coursera and Leanpub.

- Go to the main OTTR guide for how to start creating courses with OTTR.
- Read the ottrpal package documentation here.

## Installing ottrpal:

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

## Optional input files:

- a `Book.txt` file which lists the order of the chapters/quiz files (this can be autogenerated with `ottrpal`) (see example file).
- a directory containing quizzes in the form of `.md` files which have been written using the Markua formatting specifications (see example folder).
- 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 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` 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 in [this survey](www.some_link.org)"

    # 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)

    sessionInfo()

    ## R version 4.1.2 (2021-11-01)
    ## Platform: x86_64-apple-darwin17.0 (64-bit)
    ## Running under: macOS Big Sur 10.16
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRlapack.dylib
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] compiler_4.1.2  magrittr_2.0.1  fastmap_1.1.0   htmltools_0.5.2
    ##  [5] tools_4.1.2     yaml_2.2.1      stringi_1.7.6   rmarkdown_2.11
    ##  [9] knitr_1.37      stringr_1.4.0   digest_0.6.29   xfun_0.29
    ## [13] rlang_0.4.12    evaluate_0.14