This document presents an overview of the directory and file structure of a CoWeM website.

The directory structure, both of the input documents and of the generated website, is kept purposely simple. This allows easy development of the content and easy interlinking between documents in the generated website. On the other hand, the logical structure of the website, and revealed via the navigation links, can be as complicated as you need it to be.

course root/
|- settings.gradle
|- build.gradle
|- gradlew
|- gradlew.bat
|- gradlew-gui.bat
|- gradle/
|- Directory/
|--|- outline/
|--|--navigation/
|--|--policies/
|--|--library/
|- Public/
|--|- syllabus/
|--|--orientation/
|--|--lecture1/
|--|--lecture2/
|- Protected/
|--|- assignment1/
|--|--assignment2/
|--|--project/
|- graphics/
|- styles/
|- build/
|--|- website/
|--|- packages/

The first several files and directories, the ones that contain “gradle” in their name, provide the software and configuration that actually builds the website. Some of these are discussed in the sections that follow, and a more detailed discussion is in Building the Website.

The Directory, Public,and Protected directories are examples of document set groups, or groups for short. Each group contains an arbitrary number of document sets. Document sets are described in the next section, and groups in Document Set Groups.

The next two directories, graphics and styles, are optional in the input but will be present in the generated website. The graphics directory contains icons that are used in multiple places in the website, and the styles directory contains CSS and Javascript files that control the appearance and behavior of pages on the site. If you provide either of these in your input directories, the content you place there will appear in the corresponding direcotires in the generated website. This can be used to extend the standard offerings {e.g., adding new icons) or to override the defaults (e.g., to alter the CSS used for some pages)., This is discussed in the later documents on customizing the website.

The build directory contains work areas and output areas and is created when you generate the website. The generated website istelf will appear in build/website/ and you can preview the website before deploying it by opening any of the HTML files in build/website/... with your web browser. If you request construction of a package, such as a zip archive of the generated website, you will find that in build/packages.

Everything in the build directory can be reconstructed quickly and easily. It is safe to delete any subdirectory in there, or the entire build directory. In fact, that is the easiest way to “reset” the build process back to a clean state.

course root/
|--⋮
|--|--lecture1/           ➀
|--|--|- lecture1.md      ➁
|--|--|- extraNotes.mmd   ➂
|--|--|- listing1.cpp     ➃
|--|--|- listing2.md      ➃
|--|--|- diagram.png      ➄
|--|--|- build.gradle     ➅
|--|--lecture2/
|- ⋮

• one primary document,➁ written in Markdown, which is rendered in one or more HTML-based formats on the website.
  • By default, the primary document in a document set directory named “foo” would be in a file named foo.md.
• any number of secondary documents,➂ written in Markdown, which are rendered as web pages using the scroll format.
  • By default, any files ending in .md or .mmd, other than the primary document, will be treated as secondary documents.

• any number of listings,➃ which are rendered as basic web pages preserving all line breaks, indentation, and spacing.

  • By default, files ending in.h, .cpp, .java, or .listing are treated as listings.
  • Syntax highlighting (coloring) is applied to these listings.

• any number of support files,➄ which are copied to the website without modification. Examples of support files would be graphics, document-specific CSS, or data files that you want to link to.

  • By default, common graphics formats and files ending in .css, .js, and .html are treated as support files.
• a configuration file named build.gradle ➅
  • Among other things, this configuration can augment or override any of the defaults listed above.

slides

The document is split as in the pages format, but the formatting (CSS) uses larger fonts and colored background suitable for slides in a lecture. These “slides” can be longer vertically than the screen, and so may require some scrolling. This is contrary to the practice of more conventional slide formats, but I actually regard that as a major advantage, as it allows the presentation of programming code, mathematics, or diagrams that don’t require shrinking or being artificially chopped into short segments.

You can view the slides format of this document by clicking the symbol at the top or bottom of this page.

• Navigation through both the pages and slides formats can be accomplished by clicking on the and symbols at the top and bottom of each page or, on most system, using the left and right arrow keys. It is possible to change the bindings to use other keys and events (e.g., click/Enter to advance) by a fairly simple modification of the Javascript in the styles/ directory.

You may notice that the text above changes slightly as you move from one format to another. You can use conditional text to select paragraphs of text based upon, among other things, the format into which the document is being rendered. My most common use for conditional text is to omit paragraphs of explanatory text from slides that represent things I will actually say in class when discussing a slide, but allow that text to appear in the lecture notes that I provide for students to review or for publication in a web version of the same course.

directory

This is used for the major organizational pages in the website. It is a single web page with a navigation panel on the left. The navigation panel provides links, usually to the various directory pages.

• Here is an example of a page in directory format.

navigation

This is the format used to prepare the navigation panel that appears in all directory pages.

• Here is an example of a page in navigation format. This is generally not viewed separately, but as included in directory pages.

modules

This renders the outline as a single page with collapsible sections.

• Here is an example of a page in modules format.

topics

This renders the outline as a table with different columns for different types of activities.

• Here is an example of a page in topics format.

calendar

This format renders as a simple list of those activities in the outline that have been given dates, with formatting assigned based upon whether the event is in the past, is currently running, or is in the future. It is intended to serve as a notice of upcoming events.

This list can appear as a component of the “modules” format listing but can also be used separately, e.g. by inserting an iframe into a Blackboard item.

LMS

This renders individual modules of the outline in a format that can be incorporated into Canvas (and potentially other LMS systems) via an <iframe> element.

For example, compare the outline page for this site to the LMS format renderings of the following URLs:

• ../../Directory/outline/outline__LMS.html?reveal=overview1
• ../../Directory/outline/outline__LMS.html?reveal=activities1
• ../../Directory/outline/outline__LMS.html?reveal=overview2
• ../../Directory/outline/outline__LMS.html?reveal=activities2
• ../../Directory/outline/outline__LMS.html?reveal=overview3
• ../../Directory/outline/outline__LMS.html?reveal=activities3
• ../../Directory/outline/outline__LMS.html?reveal=overview4
• ../../Directory/outline/outline__LMS.html?reveal=activities4

Each document set must have a file named “build.gradle”. Unless you are overriding the default document processing options, this can consist of a single line:

apply plugin: 'edu.odu.cs.cowem.Documents' 

course root/
|- ⋮
|- Directory/
|- build.gradle
|--|- outline/
|--|--navigation/
|--|--policies/
|--|--library/
|- Public/
|--|- syllabus/
|--|--orientation/
|--|--lecture1/
|--|--lecture2/
|- Protected/
|--|- assignment1/
|--|--assignment2/
|--|--project/

You would add such a file to the group directory if you wanted to establish some default processing options for all document sets in that group. The details are discussed later. But as an example, to establish a default that all documents in the Directory group should be processed using the directory format, I would put this into a build.gradle file in my Directory/ folder:

apply plugin: 'edu.odu.cs.cowem.Group'

subprojects {
    documents {
        formats = ['directory']
    }
}

Similarly, in my Public/ directory, I would place this in a build.gradle file during a semester when I am teaching a live course:

apply plugin: 'edu.odu.cs.cowem.Group'

subprojects {
    documents {
        formats = ['scroll', 'slides']
    }
}

to indicate that I wanted document sets in the Public group to be processed into both lecture notes (scroll) and slides for in-class presentations. In a semester when I offer the same couse as a web-based offering, I would change this to

apply plugin: 'edu.odu.cs.cowem.Group'

subprojects {
    documents {
        formats = ['scroll']
    }
}

and eliminate the slides, since the lecture notes (scroll) version usually includes more detailed information.

pluginManagement {
    repositories {
        ivy { // Use my own CS dept repo
            url 'https://secweb.cs.odu.edu/~zeil/ivyrepo'
        }
        gradlePluginPortal()        
        mavenCentral()
    }
}

def includeFrom = {
    dir ->  new File(rootDir,dir).eachFileRecurse { f ->
        if ( f.name == "build.gradle" ) {
            String relativePath = f.parentFile.absolutePath - rootDir.absolutePath
            String projectName = relativePath.replaceAll("[\\\\\\/]", ":")
            include projectName
        }
   }
}

// Don't touch anything abode this line

rootProject.name = 'CS350'   // any short descriptive word or phrase - no blanks  


// The following lines establish the course groups.
includeFrom('Directory')
includeFrom('Public')
includeFrom('Protected')

// Top-level build.gradle for a course.

plugins {
   id 'edu.odu.cs.cowem.course' version '1.16'
}

                   ➀

course {
    courseName        = 'CS 350'     ➁
    courseTitle       = 'Introduction to Software Engineering'
    semester          = 'Fall 2016'
    sem               = 'f16'             ➂
    instructor        = 'Steven J Zeil'   ➃
    email             = 'zeil@cs.odu.edu' ➄  
    copyright         = '2016, Old Dominion Univ.'  ➅
    homeURL           = '../../Directory/outline/index.html' ➆
}