READ ME

As mentioned above, the images for a lesson are collected in a subdirectory called images. References to these images in the adoc files are of the form @image{path-to-image-file, width}, where the path-to-image-file is the relative pathname of the chosen image file in images, and the optional width is the desired width of the image.

The images also contains a lesson-images.json file that lists all the image files in the same directory with their associated metadata, i.e., caption, description, source, and license. The topmost JSON object in this file maps each image name to an object containing its metadata.

Here is an example:

Captions are optional and will print under the image on the webpage and workbook page. They can be left out if no caption is desired.

Descriptions are for visually impaired folks using screenreaders so need to be detailed enough to allow students to engage with our materials. For example:

If an image is created by us, not derived from other work, and is not a data display, use

If an image is created by us and derived from other work, indicate that. Here’s an example of how we credit the data cycle images:

If an image is a data display created by us using real data, please specify the source. For example:

If an image is a data display created using fictitious data, please indicate that.

The build will issue warnings for underdefined images when description, source, or license are missing. (You will get warnings even if the value is an empty string. However, for the moment, empty-string captions are ignored.)

The build process collects all the image descriptions into a single file images.js in distribution/en-us.

Glossary items are annotated with the directive @vocab. E.g.,

In a lesson plan, such items are searched in the main glossary file, lib/glossary-terms.rkt, and are inserted as lists at the head of the document.

For a pathway narrative, the glossary items from all its constituent lessons are collected into a file pathway-standards.shtml that is linked to in the narrative page.

There can be auxiliary glossary files in lib/ that can be used to shadow the main glossary for particular lessons. For now, the only such shadowing glossary file is glossary-terms-ss.rkt, used for Social-Studies lessons.

In order for a lesson lessonA to use a shadowing glossary, its directory, i.e., lessons/lessonA/langs/en-us, should containing a file shadow-glossary.txt that contains the name of the shadowing glossary file.

Each lesson plan is strongly advised to start out with a

The description is displayed in the lesson plan, but is also part of the autogenerated thumbnails used by the pathway narrative for each of its lessons.

A lesson can optionally include a set of keywords, which are used when searching for lesson content. While the title, description, and standards alignment are already included in the search, occasionally there are search terms a user might employ which are not reflected in any part of the lesson (e.g., “PEMDAS”, “GEMDAS”). These keywords can be added anywhere in the lesson with the keywords directive: @keywords{PEMDAS, GEMDAS}. Multiple keywords are comma-separated.

Exercise files are typically recipes and have calls to one of two directives

The former is used to specify a correct recipe; the latter to introduce a recipe that needs to be debugged. For examples of such recipes, please see the .adoc files in the various fragments subdirectories in the repo.

Some exercise files are more elaborate than recipes and contain sketches of solutions and tables that need to be filled. These use some extra directives like @do, @show, @showsoln, and @code that then use raw Racket code to format the exercise. Examples of these can be found in the Supplemental lesson.

Sometimes, just a contract (part of a recipe) needs to be shown in the text. Use @show to call the Racket procedures contract (for a single contract) or contracts (for multiple).

This states that the function name is /, its domain list is ("Number" "Number") and its range is "Number".

adds an optional fourth argument stating the function’s purpose.

To show multiple contracts,

Note that contracts takes a list of arguments. Also note that quoting each such argument obviates the need for quoting the domain-list argument.

The directive @showsoln is similar to @show but renders only in solution pages.

The directive @do passes its argument to Racket, and renders the standard output thereof. It is a general-purpose trapdoor into Racket for things that are too difficult to do using regular AsciiDoc and the standard directives. (That said, we haven’t had occasion to need it so far.)

There are a clutch of directives to allow easy cross-referencing between pages in the converted document base.

The directive @printable-exercise is used to refer to pages that are part of the workbook, e.g.,

If , link text is not supplied, the title of the page is used. The first and second components of the pathname may be dropped in certain cases: lessonA/ may be dropped if the reference is made within the same lesson. In that case, the second component, if pages/, may also be dropped. (The only other possible second component is solution-pages/, which cannot be dropped.) The third component may have extension .pdf, .html, or .adoc. If .adoc, it is resolved to .html.

The directives @opt-printable-exercise and @handout are called the same way, and are applied to exercise pages not mentioned in the lesson’s page list. (The two are categorized differently in the collections appearing in the pathway narrative.)

The directive @lesson-link{…​} is a general-purpose link to any pages within lessons, and uses pathnames relative to the distribution/<natlang>/lessons/ directory.

The directive @dist-link{…​} uses pathnames relative to the distribution/<natlang>/

Use @link{URL, link-text} to refer to a generic URL not part of the curriculum hierarchy. The second argument for the link text is optional.

Use @image{images/pic.png} to insert the image images/pic.png.

An optional second argument gives the preferred width of the image. Additional information about the image is retrieved from the images/lesson-images.json file.

Comments can be inserted anywhere in the .adoc file as

Note that such comments will be seen in the HTML source, which may be exactly what you want, either for documentation or debugging.

If you don’t want your comments to survive into the HTML, you may use AsciiDoc’s own commenting mechanism with // and //// (see manual). While these work mostly, their text is unfortunately subject to preprocessing for directives, which may have consequences. To have truly inert comments, use

@scrub's argument can contain plausible directives — the only requirement is that any braces within it should be paired. (This is obviously needed to keep the extent of @scrub's argument recognizable.)

Use the @ifproglang directive to conditonally include a fragment text for a specific programming language. E.g.,

Some standard CSS classes to emphasize certain regions of text.

Use

to generate a “strategy box”, a boxed text with a blue border.

Use

to generate a “notice & wonder box”, a boxed text with a purple border.

Add the class .physics-table to a table attribute to generate a single-arg function table, e.g., one that maps miles driven to cost.

You can add your own CSS classes or IDs. Classes are specified with an initial dot and IDs with an initial #. Note that at most one ID is meaningful, although any number of classes may be specified. A combination of classes and ID are simply strung together, e.g.,

The above works for blocks. Use @span{classes and id}{text} to enclose CSS classes and/or an ID around arbitrary (i.e., in-line) text. @spans may be nested. @span’s first argument of classes and ID is specified in the same way as for blocks, without the brackets.