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

    sessionInfo()

    ## R version 4.4.0 (2024-04-24)
    ## Platform: x86_64-apple-darwin20
    ## Running under: macOS 15.3.2
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] digest_0.6.37     R6_2.5.1          fastmap_1.2.0     xfun_0.50
    ##  [5] cachem_1.1.0      knitr_1.49        htmltools_0.5.8.1 rmarkdown_2.29
    ##  [9] lifecycle_1.0.4   cli_3.6.3         sass_0.4.9        jquerylib_0.1.4
    ## [13] compiler_4.4.0    rstudioapi_0.17.1 tools_4.4.0       evaluate_1.0.3
    ## [17] bslib_0.8.0.9000  yaml_2.3.10       rlang_1.1.5       jsonlite_1.8.9