Creating Lesson Files
- To use the Webucator CourseWare Creation (WCWC) system
- How Webucator manuals are created.
- To properly structure lesson files.
- To add headings, paragraphs, lists, and tables.
- To add inline markup.
- To insert images.
- To create cross references and external links.
- To create footnotes.
- To validate lesson files.
Webucator manuals are broken into lessons. Each lesson is made up of one XHTML file with 0 or more references to external files which are maintained in a simple XML format.
This document, which itself was created using this system, provides instructions for creating lesson files.
Structuring Lesson Files
Each lesson file is a valid XHTML Strict file, but only a subset of HTML tags is used and the structure is very specific.
Naming Lesson Files
Lesson files should be named so that the file name relates to the lesson content. Words in the file name should be separated with dashes.
The <head /> Tag
The <head /> tag contains several tags that should not be changed. Tags that you should modify are listed below.
- The <title /> tag should contain the lesson title, which should not be repeated in the body as a heading.
- The Author <meta /> tag should be changed to reflect the actual author of the lesson.
- The Category <meta /> tag should be changed to reflect the actual category of the lesson. There can only be one category. If you are unsure of the value for this, please email Nat at courseware@webucator.com. In most cases, you will use the same category for every lesson in a particular manual.
Code Sample: LessonFiles/Demos/Template-Head.html
---- Code Omitted ----<head> <title>Lesson Title</title><!--Insert the title of the lesson in title case (e.g, Conditionals and Loops)--> <meta name="Author" content="Nat Dunn" /><!--Insert your name as the value of the content attribute--> <meta name="Category" content="WCWC" /><!--Insert the lesson category (e.g, CSS, JavaScript, Silverlight, XML, etc.) as the value of the content attribute. If you don't know what category to insert, email Nat at ndunn@webucator.com.--> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="http://www.webucatormanuals.com/WCWC/Authoring/lesson.css"/> <script src="http://www.webucatormanuals.com/WCWC/Authoring/lesson.js" type="text/javascript"></script> </head>---- Code Omitted ----
The section which you need to modify is highlighted.
The <body /> Tag
id Attribute
The <body /> tag should have an id attribute that uniquely identifies the lesson. This will often be the file name, but be aware of file names that aren't unique. For example, an HTML course might be combined with a CSS course in a single manual. If both courses have a lesson with the filename Basics.html there could be a conflict. A solution is to name the files HTML-Basics.html and CSS-Basics.html with <body /> id attributes set to "HTML-Basics" and "CSS-Basics", respectively.
Subsections
The body is divided into a <div /> and an optional <ol /> as shown below:
- <div id="Content" /> - contains the lesson content.
- <ol id="Footnotes" /> - footnotes.
<div id="Content" />
The Content section is structured as follows:
- <ol id="LearnItems" /> (required)
- <div id="Introduction" /> (optional)
- Block Elements: Headings, Paragraphs, Lists, Tables, Code Blocks, Syntax Blocks, Demos, and Exercises
- <div id="Conclusion" />
Each section is described in detail below.
<ol id="LearnItems" />
The LearnItems section is a ordered list showing what is to be covered in the lesson. In the manual, this section will be prefixed with "In this lesson you will learn...", so each list item should begin with a word that flow from that (e.g, "to, how, about, etc.").
Note that each learn item should end with a period.
Code Sample: LessonFiles/Demos/Template-LearnItems.html
---- Code Omitted ----<ol id="LearnItems"> <li>To use...</li> <li>To create...</li> <li>About...</li> </ol>---- Code Omitted ----
<div id="Introduction" />
The optional Introduction section can contain paragraphs, lists and tables.
Block Elements
This section describes the block-level elements allowed in the body. The elements can appear in any order and can all be repeated. Except where indicated, you should assume that you can nest these elements according to the rules of XHTML.
Headings
You can use <h1 />, <h2 />, <h3 />, and <h4 /> headers only. They should be structured in a logical order, so that <h4> elements are alway preceded by <h3> elements, <h3> elements are alway preceded by <h2> elements,and <h2> elements are alway preceded by <h1> elements. Think of legal documents.
<h1 /> and <h2 /> elements appear in the table of contents.
Paragraphs
<p /> tags denote paragraphs.
Blockquotes
<blockquote /> tags denote blocks of quoted text. Do not use them for formatting purposes alone.
Lists
- <ol /> - for ordered lists - it's okay to nest lists. Sublists have no class.
- <ul /> - for unordered lists - it's okay to nest lists. Sublists have no class.
Tables
Tables are denoted with <table /> and are structured as follows:
- <caption />
-
<thead />
- <tr />
- <th /> - colspan and rowspan attributes are allowed.
-
<tbody />
- <tr />
- <td /> - colspan and rowspan attributes are allowed.
The <table /> tag takes an optional "Wide" class which indicates that the table can stretch into the margin in the printed manual.
Code Blocks
Code Blocks are denoted with <div class="CodeBlock" />:
- used for short code blocks. Longer code samples should be stored in external files and referenced as Demos.
- All whitespace is relevant. The start of the code should be flush up against the open <div class="CodeBlock"> tag and the end of the code should be flush up against the corresponding close </div> tag. Tabs should be used for indenting.
- output will be preformatted.
- only subtag allowed is <em />
- optional title attribute is used to provide a caption in the output
- we recommend that you write these in code view so that you can control spacing and linefeeds.
- Note that when you preview them in the browser, they will not appear preformatted.
var foo = "Hello World"; //set variable alert(foo); //alert message
Syntax Blocks
Syntax Blocks are denoted with <div class="SyntaxBlock" /> and are structured as follows:
- Just like CodeBlocks except that they are prefixed with "Syntax: " and the optional title in the output.
Special Inline Tags
Syntax Blocks can have special inline <span /> tags for optional code and substitution code (placeholder text that the developer would subsitute, like a class name).
Here is an example:
<div class="SyntaxBlock" title="Java Compile Command">javac <span class="Optional">[-classpath <span class="Subst">classpathElements</span>]</span> <span class="Optional">[-d outputDirectory]</span> <span class="Subst">className</span>.java</div>
And here is the approximate output:
javac [-classpath classpathElements] [-d outputDirectory] className.java
Demos
Demos are denoted with <div class="Demo" /> and are structured as follows:
- <a href="LessonName/DemosExercisesOrSolutions/FileName.ext">Sample</a>
-
<div class="CodeExplanation" />
- Paragraphs and Lists
Exercises
Exercises are denoted with <div class="Exercise" /> and are structured as follows:
- <h1 /> - Exercise title
- <div class="Duration" />
- <span class="Min" />Num Minutes</span>
- <span class="Max" />Num Minutes</span>
- <ol class="Instructions" /> - it's okay to nest lists
- <div class="CodeSample" /> - zero or more, structured like Demo blocks
- <div class="Challenge" /> - zero or more
- <ol class="Instructions" /> - it's okay to nest lists. Sublists have no class.
- <div class="Solution" /> - zero or more, structured like <div class="Demo"/>
- <div class="SolutionToChallenge" /> - one for each challenge
Inline Elements
Emphasis
Emphasized text is marked up with <em /> tags.
Links
Links to web resources and email addresses should use standard HTML syntax (see footnote): <a href="url">Link text</a>. In the online manual, this will show up as a normal link. In the print manual, the link text will be footnoted and the link will show up in the footnote.
File Paths
File paths should be marked up as <a class="FilePath" href="Path/To/File.ext">File Name</a> if you want them clickable and <span class="FilePath">File Path</span> if you don't want them clickable. In the print manual, the two will appear exactly the same. In the online version, links (but not spans) will be clickable and bring up the code sample.
Code Snippets
Code snippets are marked up with <code /> tags.
Images
Images are marked up as <img src="" alt="" /> tags.
The <img /> tag takes an optional "Wide" class which indicates that the image can stretch into the margin in the printed manual.
Images can be tough. Don't make them any wider than 660 pixels and use the Wide class when they are more than 500 pixels, like so:
Do not use height and width attributes.
<img src="Images/MyImage.gif" class="Wide" alt="" />
By default images will appear as blocks. To have them appear inline, assign the <img /> tag the "Inline" class.
Book Titles
Book titles should be marked up as follows: <span id="" class="BookTitle" />. The id is required so that it can be footnoted.
Footnotes
Footnotes are stored in an ordered list at the end of the lesson: <ol id="Footnotes" />
Each footnote is a list item. It should begin with an empty <a href="#TagIdentifier"> </a> tag and followed by a div tag containing any block-level elements as shown below:
Code Sample: LessonFiles/Demos/Template-Footnotes.html
---- Code Omitted ----<ol id="Footnotes"> <li> <a href="#TagIdentifier"></a><!--This <a /> tag should be empty, but don't use the XML shortcut close syntax.--> <div> <p>This is where the footnote content goes.</p> </div> </li> </ol> </body> </html>
Important: Elements that contain block-level elements cannot be footnoted. For example, a <table /> cannot be footnoted as it's unclear where the footnote marker should show up. You could footnote the <caption />or the first <th /> instead.
Creating Cross References
You can id elements that do not have reserved ids. Each id should be unique throughout the document.
- You can reference any element with an id like this: <a href="lessonID#id" class="CrossReference">text</a>.
- If you are referencing the beginning of the file, you just need the file name: <a href="lessonID" class="CrossReference">text</a>.
- If you are referencing a tag in the same file, you just need the anchor name: <a href="#id" class="CrossReference">text</a>.
Validating the Lesson
There are two steps to validating the file:
- Open the file in Firefox to have it validated with JavaScript.
- Upload the file to the W3C Markup Validation Service. It should be valid valid XHTML 1.0 Strict.
Creating Lesson Files Conclusion
In this lesson of the WCWC tutorial, you have learned how to create lesson files.
Footnotes
-
Standard link syntax for a tags is explained in Webucator's online HTML tutorial.