diff --git a/doc/public/course_data_formats/course_xml.rst b/doc/public/course_data_formats/course_xml.rst
index fe25aa92f2..56d831d972 100644
--- a/doc/public/course_data_formats/course_xml.rst
+++ b/doc/public/course_data_formats/course_xml.rst
@@ -550,15 +550,84 @@ If you want to customize the courseware tabs displayed for your course, specify
*********
Textbooks
*********
-Support is currently provided for image-based and PDF-based textbooks.
+Support is currently provided for image-based and PDF-based textbooks. In addition to enabling the display of textbooks in tabs (see above), specific information about the location of textbook content must be configured.
Image-based Textbooks
-^^^^^^^^^^^^^^^^^^^^^
+=====================
+
+Configuration
+-------------
+
+Image-based textbooks are configured at the course level in the XML markup. Here is an example:
+
+.. code-block:: xml
+
+
+
+
+
+
+
+
+
+Each `textbook` element is displayed on a different tab. The `title` attribute is used as the tab's name, and the `book_url` attribute points to the remote directory that contains the images of the text. Note the trailing slash on the end of the `book_url` attribute.
+
+The images must be stored in the same directory as the `book_url`, with filenames matching `pXXX.png`, where `XXX` is a three-digit number representing the page number (with leading zeroes as necessary). Pages start at `p001.png`.
+
+Each textbook must also have its own table of contents. This is read from the `book_url` location, by appending `toc.xml`. This file contains a `table_of_contents` parent element, with `entry` elements nested below it. Each `entry` has attributes for `name`, `page_label`, and `page`, as well as an optional `chapter` attribute. An arbitrary number of levels of nesting of `entry` elements within other `entry` elements is supported, but you're likely to only want two levels. The `page` represents the actual page to link to, while the `page_label` matches the displayed page number on that page. Here's an example:
+
+.. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Linking from Content
+--------------------
+
+It is possible to add links to specific pages in a textbook by using a URL that encodes the index of the textbook and the page number. The URL is of the form `/course/book/${bookindex}/$page}`. If the page is omitted from the URL, the first page is assumed.
+
+You can use a `customtag` to create a template for such links. For example, you can create a `book` template in the `customtag` directory, containing:
+
+.. code-block:: xml
+
+ 
More information given in the text.
+
+The course content can then link to page 25 using the `customtag` element:
+
+.. code-block:: xml
+
+
-TBD.
PDF-based Textbooks
-^^^^^^^^^^^^^^^^^^^
+===================
+
+Configuration
+-------------
PDF-based textbooks are configured at the course level in the policy file. The JSON markup consists of an array of maps, with each map corresponding to a separate textbook. There are two styles to presenting PDF-based material. The first way is as a single PDF on a tab, which requires only a tab title and a URL for configuration. A second way permits the display of multiple PDFs that should be displayed together on a single view. For this view, a side panel of links is available on the left, allowing selection of a particular PDF to view.
@@ -566,20 +635,51 @@ PDF-based textbooks are configured at the course level in the policy file. The
"pdf_textbooks": [
{"tab_title": "Textbook 1",
- "url": "https://www.example.com/book1.pdf" },
+ "url": "https://www.example.com/thiscourse/book1/book1.pdf" },
{"tab_title": "Textbook 2",
"chapters": [
- { "title": "Chapter 1", "url": "https://www.example.com/Chapter1.pdf" },
- { "title": "Chapter 2", "url": "https://www.example.com/Chapter2.pdf" },
- { "title": "Chapter 3", "url": "https://www.example.com/Chapter3.pdf" },
- { "title": "Chapter 4", "url": "https://www.example.com/Chapter4.pdf" },
- { "title": "Chapter 5", "url": "https://www.example.com/Chapter5.pdf" },
- { "title": "Chapter 6", "url": "https://www.example.com/Chapter6.pdf" },
- { "title": "Chapter 7", "url": "https://www.example.com/Chapter7.pdf" }
+ { "title": "Chapter 1", "url": "https://www.example.com/thiscourse/book2/Chapter1.pdf" },
+ { "title": "Chapter 2", "url": "https://www.example.com/thiscourse/book2/Chapter2.pdf" },
+ { "title": "Chapter 3", "url": "https://www.example.com/thiscourse/book2/Chapter3.pdf" },
+ { "title": "Chapter 4", "url": "https://www.example.com/thiscourse/book2/Chapter4.pdf" },
+ { "title": "Chapter 5", "url": "https://www.example.com/thiscourse/book2/Chapter5.pdf" },
+ { "title": "Chapter 6", "url": "https://www.example.com/thiscourse/book2/Chapter6.pdf" },
+ { "title": "Chapter 7", "url": "https://www.example.com/thiscourse/book2/Chapter7.pdf" }
]
}
]
+Some notes:
+
+* It is not a good idea to include a top-level URL and chapter-level URLs in the same textbook configuration.
+
+Linking from Content
+--------------------
+
+It is possible to add links to specific pages in a textbook by using a URL that encodes the index of the textbook, the chapter (if chapters are used), and the page number. For a book with no chapters, the URL is of the form `/course/pdfbook/${bookindex}/$page}`. For a book with chapters, use `/course/pdfbook/${bookindex}/chapter/${chapter}/${page}`. If the page is omitted from the URL, the first page is assumed.
+
+For example, for the book with no chapters configured above, page 25 can be reached using the URL `/course/pdfbook/0/25`. Reaching page 19 in the third chapter of the second book is accomplished with `/course/pdfbook/1/chapter/3/19`.
+
+You can use a `customtag` to create a template for such links. For example, you can create a `pdfbook` template in the `customtag` directory, containing:
+
+.. code-block:: xml
+
+ More information given in the text.
+
+And a `pdfchapter` template containing:
+
+.. code-block:: xml
+
+ More information given in the text.
+
+The example pages can then be linked using the `customtag` element:
+
+.. code-block:: xml
+
+
+
+
+
*************************************
Other file locations (info and about)
*************************************