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

Table 2. Input and Output Files

Input File	Output File
overview/overview.dbk	overview/page/overview.html	The "page" output format
overview/overview.dbk	overview/pages/index.html	The opening page of the multi-page output for the "pages" output form.
overview/overview.dbk	overview/slides/index.html	The opening page of the multi-page output for the "slides" output form.
overview/overview.dbk	overview/page/overview.pdf	The "pdf" output format
overview/foo.cpp	overview/foo.cpp.html	Highlighted version of the source code
overview/asst.html	overview/html/asst.html	The "html" output format

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.