Overview - Course Document Sets

This is an introduction to a set of tools that I have put together for managing document sets related to a course.

A document set is a collection of documents in web-browser accessible form that can cross-reference one another. The problems of cross-referencing is not as trivial as simply writing <a href=...> links within HTML web pages. That's because the links need to be specified when the documents are written, but the documents might be published on the website in any of several different formats.

This tool set supports three different input formats and 5 different output formats. Some output formats are intended for interactive viewing in a browser, others for printing. It is possible to publish a single input document in multiple output formats. In fact, I would expect that most documents would be published in two formats, one for viewing and one for printing.

The possible inputs and outputs are

The output forms "pages" and "slides" are considered to be viewing formats, because printing these would require someone to navigate from page to page, printing each one.. "pdf" is a printable format. "page" and "html" can be either.

As you can see, the primary input format supported is DocBook. DocBook is a format that emphasizes describing one's text rather than formatting it. For example, let's say that you were typing out an assignment and wanted to something like

If you were working directly in HTML, you would probably think to yourself, "How do I want to format the variable name and the file name in that sentence?" You might opt for something like

The problem here is that you might have wind up using italics (<i>) to mean many different things in this document or across a set of related documents. You might later come to regret having used italics to format variable names and want to change this patter. That will be difficult if sometimes an <i> is a variable name, sometimes it is a term being defined, and sometimes it is used simply for emphasis.

A more savvy HTML author might have written

Although more awkward to type, and requiring a lot more self-discipline, this has the advantage of latter allowing you to choose distinctive formatting (via CSS) for variable names and file names. This is an example of writing descriptively rather than visually.

DocBook provides, in essence, a set of descriptive tags that you can use:

This can be translated into HTML, PDF, ebook formats, etc. In fact, the HTML translation would probably look a lot like the span/class example above, so that a little CSS can then be used to uniformly format different "kinds" of text.

The tools provided here will not only take care of translation and cross-referencing, they also provide for some convenience functions as well.

#include <iostream>


/** An example of some C++ code
*/

using namespace std;

int main() {
  cout << "Hello world!" << endl;
  return 0;
}

#include <iostream>


/** An example of some C++ code
*/

using namespace std;

int main() {
  cout << "Hello world!" << endl;
  return 0;
}

#include <iostream>


/** An example of some C++ code
*/

using namespace std;

int main() {
  cout << "Hello world!" << endl;
  return 0;
}

x = (-b +- sqrt(b^2-4a c))/(2a)

Documents are grouped into directories. In general, a given directory can hold only a single document that will be published in "pages" form and a single document (possibly the same one) that will be published in "slides" form. Any number of "page", "pdf", or source code documents may occur in a directory.

Typically, a directory name will reflect the name of the pages/slides document that it contains. For example, a directory overview might contain a DocBook file overview.dbk together with any graphics files, stylesheets, or other auxiliary content that is used to prepare the final document. Let's suppose that this overview document also links to some C++ source code foo.cpp and to an assignment file asst.html. Let's further suppose that we decide to publish the overview in all available output forms. Then the relation between the input and output files is given by

Actually, the table above over-simplified in one respect. There will actually be two separate directories named "overview". One is the original input directory and the other is a copy of that directory created in an output area. In general, document conversion leaves the input directories untouched.

The thing that determines which documents are included in the set and what output forms should be used is the site map, an XML file that lists the directories in which documents are stored, the documents stored there, and the output forms desired for each document.

The site map is normally called "course.sitemap" and looks something like like this

<?xml version="1.0" encoding="utf-8"?>
<targetset> 
  <targetsetinfo>
    CS 250 
  </targetsetinfo>

  <sitemap home="index.html" email="cs250@cs.odu.edu">
    <dir name="cs250Documents">
      <dir name="Directory">
         <document targetdoc="topics">
            <form>page</form>
         </document>
         <document targetdoc="info">
            <form>page</form>
         </document>
         <document targetdoc="buttons">
            <form>html</form>
         </document>
      </dir>

      
      <dir name="syllabus">
         <document targetdoc="syllabus">
            <form>page</form>
         </document>
      </dir>


<!--- ============ Lectures ===============  -->


      <dir name="cppProgramStructure">
         <document targetdoc="cppProgramStructure">
            <form>slides</form>
            <form>page</form>
         </document>
      </dir>

      <dir name="arrays">
         <document targetdoc="arrays">
            <form>slides</form>
            <form>page</form>
	        </document>
      </dir>

 ...

It's worth pointing out nothing in the above sitemap makes any explicit mention of source code documents. That's because source code documents tend to be numerous and are likely to have identical names. Source code documents are handled (almost) implicitly. For every directory named in the site map (whether that directory contains any explicit document entries or not), that directory will be scanned for files endinging in ".h", ".cpp", or ".java". Each such file located will be converted into a web page.

Note that, if you should have a directory that contains only source code but no input DocBook or HTML documents, you would list that directory in the sitemap in order to collect and convert the source code.

It is also possible to have html pages that are not converted in any way. If the input directories contain a *.html file that is not listed in the sitemap, that file simply gets copied to the corresponding output directory. I use this, for example, to provide an index.html for the entire document set that consists of a frameset showing a navigation table (buttons.html) on one side and the topics page on the other.

This is actually not a special case, by the way. All files in a named input directory get copied to the corresponding output directory and to the output form directories. That's how graphics, stylesheets, and other related content stays with your web pages.

The outline file organizes documents into a hierarchical structure of topics. Normally stored in a file named course.outline, it serves as the input from which the course topics page is generated.

If you have no interest in preparing a topics page (e.g., because you are going to link to each document directly from Blackboard or some other Learning Management System) then you can simply provide a skeleton outline file and ignore the generated page.

The outline file looks like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<outline>
  <preamble> 
    <info>
      <title>CS333 Topics</title>
    </info>
  </preamble>


<topic title="Part I. Coding in C++"> 
  <topic title="Overview"> 
    <item kind="slides" targetdoc="policiesAndThemes">Course Policies and Themes</item>
  </topic>

    <topic title="Primitive Data Types and Assignments"> 
      <item kind="lab" 
          date="2010-01-11" enddate="2010-01-15" 
          targetdoc="accountSetup"/>
      <item kind="reading">Chapters 1,2</item> 
      <item kind="lecturenotes" targetdoc="assignment"/>
      <item kind="quiz" 
            href="http://www.course.com/downloads/computerscience/malikcpp3e/selftests2.cfm">
        Self-test (ungraded)</item> 
    </topic>

    <topic title="I/O">
      <item kind="reading">Chapter 3</item>
      <item kind="lecturenotes" targetdoc="io"/>
      <item kind="lab" 
          targetdoc="usingCodeBlocks1"/>
      <item kind="quiz" 
            href="http://www.course.com/downloads/computerscience/malikcpp3e/selftests3.cfm">
        Self-test (ungraded)</item>
    </topic>

       ...

    
    <topic title="End of Part I">
        <item kind="asst" date="2010-02-19">All assignments from Part I are due by the end of the day</item>
        <item kind="exam"  id="exam1_s10" href="../assts/exam1.html" date="2010-02-14">Exam 1</item>
        
        
    </topic>
</topic>

<topic title="part II. Programming in C++">
    ...
</topic>


<postscript>  
  <informaltable>
    <tr>
      <th colspan="2">
        Symbol Key
      </th>
    </tr>
    <tr>
      <td>
        <img alt="conference" src="lecture.gif"/>
      </td>
      <td>Conference</td>
    </tr>
    <tr>
      <td>
        <img alt="lecture notes" src="lecturenotes.gif"/>
      </td>
      <td>Lecture Notes</td>
    </tr>
    <tr>
      <td>
        <img alt="slides" src="slides.gif"/>
      </td>
      <td>Slides</td>
    </tr>
    <tr>
      <td>
      <img alt="text" src="text.gif"/></td>
      <td>Text</td>
    </tr>
     ...
  </informaltable>
  <blockquote>
    <para>All times in this schedule are given in Eastern Time.</para>
  </blockquote>
</postscript>

  <presentation>  
    <column title="Topics" kinds="topics"/>
    <column title="Lecture Notes" kinds="lecture lecturenotes slides event exam"/>
    <column title="Readings" kinds="reading text"/>
    <column title="Assignments &amp; Quizzes" kinds="exam quiz asst lab unix"/>
  </presentation>
</outline>