Skip to content

E
edx-platform
Commit d2f9b27d by David Ormsbee
Options

Merge pull request #1611 from MITx/fix/brian/doc-pdfbook 

add textbook and pdf textbook documentation
parents 3bb108b1 9c92c92f
Showing with 112 additions and 12 deletions
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
<course>
<textbook title="Textbook 1" book_url="https://www.example.com/textbook_1/" />
<textbook title="Textbook 2" book_url="https://www.example.com/textbook_2/" />
<chapter url_name="Overview">
<chapter url_name="First week">
</course>
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
<table_of_contents>
<entry page="1" page_label="i" name="Title" />
<entry page="2" page_label="ii" name="Preamble">
<entry page="2" page_label="ii" name="Copyright"/>
<entry page="3" page_label="iii" name="Brief Contents"/>
<entry page="5" page_label="v" name="Contents"/>
<entry page="9" page_label="1" name="About the Authors"/>
<entry page="10" page_label="2" name="Acknowledgments"/>
<entry page="11" page_label="3" name="Dedication"/>
<entry page="12" page_label="4" name="Preface"/>
</entry>
<entry page="15" page_label="7" name="Introduction to edX" chapter="1">
<entry page="15" page_label="7" name="edX in the Modern World"/>
<entry page="18" page_label="10" name="The edX Method"/>
<entry page="18" page_label="10" name="A Description of edX"/>
<entry page="29" page_label="21" name="A Brief History of edX"/>
<entry page="51" page_label="43" name="Introduction to edX"/>
<entry page="56" page_label="48" name="Endnotes"/>
</entry>
<entry page="73" page_label="65" name="Art and Photo Credits" chapter="30">
<entry page="73" page_label="65" name="Molecular Models"/>
<entry page="73" page_label="65" name="Photo Credits"/>
</entry>
<entry page="77" page_label="69" name="Index" />
</table_of_contents>
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
<img src="/static/images/icons/textbook_icon.png"/> More information given in <a href="/course/book/${book}/${page}">the text</a>.
The course content can then link to page 25 using the `customtag` element:
.. code-block:: xml
<customtag book="0" page="25" impl="book"/>
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
<img src="/static/images/icons/textbook_icon.png"/> More information given in <a href="/course/pdfbook/${book}/${page}">the text</a>.
And a `pdfchapter` template containing:
.. code-block:: xml
<img src="/static/images/icons/textbook_icon.png"/> More information given in <a href="/course/pdfbook/${book}/chapter/${chapter}/${page}">the text</a>.
The example pages can then be linked using the `customtag` element:
.. code-block:: xml
<customtag book="0" page="25" impl="pdfbook"/>
<customtag book="1" chapter="3" page="19" impl="pdfchapter"/>
*************************************
Other file locations (info and about)
*************************************
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment