Generated: Monday, November 14, 2011, 09:19:25Copyright ©2011, Kurt NørmarkThe local LAML software home page

Reference Manual of the Course Plan Document Style

Kurt Nørmark ©    normark@cs.auc.dk    Department of Computer Science    Aalborg University    Denmark    

Source file: styles/course-plan/course-plan.scm
LAML Version 38.0 (November 14, 2011, full)

The course plan document style supports the generation of a course home page with references to course plans for a number of lectures, course introduction, lecture overviews, calendars, and exercises. All the generated WWW pages are organized in a single directory, the course html directory - for convenient bundling of all the generated pages. The variable language-preference determines the language of the fixed texts in the system. Possible values are the symbols danish and english. This system is now obsolete. We have put an XML-in-LAML interface on the course plan system. The new software is found in styles/xml-in-laml/course-plan/. As of now, there is no manual of of this style, but it will come soon.

Table of Contents:
1. Overview and organization.5. Course overviews.9. Utility functions.
2. The course description.6. Course plan exercise functions.10. An example of a course home page
3. Top level course plan functions.7. URL functions.11. Template stuff
4. Colors.8. Internal functions of interest.

Alphabetic index:
actual-exercise-interval(actual-exercise-interval this-lecture-rec next-lecture-rec)Given the records of this lecture and the next-lecture, return an interval of the exercise time.
apply-course-plan-color-scheme(apply-course-plan-color-scheme color-scheme)Apply a given color scheme
brief-course-semesterbrief-course-semesterBrief course semester (a string).
brief-course-titlebrief-course-titleA brief, abbreviated course title (a string).
course-calendar-colorcourse-calendar-colorThe color used to mark course entries in the calendar.
course-dircourse-dirThe absolute path of the course directory.
course-exercise(course-exercise id number body . lecture-id)Define an exercise with a certain id (symbol), a number, and a body.
course-exercise-ref(course-exercise-ref id number lecture-id)Return an URL to an exercise.
course-page(course-page title body)Return a course page (with standard graphical elements, header, body and some footer stuff (standard-links)).
course-plan-color-scheme-1course-plan-color-scheme-1A sample color scheme: Purple and yellow
course-plan-color-scheme-2course-plan-color-scheme-2Another sample color scheme: Read and yellow.
course-plan-color-scheme-3course-plan-color-scheme-3Another sample color scheme: Black and white.
course-plan-color-scheme-4course-plan-color-scheme-4Another sample color scheme: Blue and grey.
course-plan-color-scheme-5course-plan-color-scheme-5Another sample color scheme: Blue and grey.
course-semestercourse-semesterCourse semester (a string).
course-startcourse-startThe time (second-count) of the first lecture in the course.
course-titlecourse-titleThe title of the course (a string).
course-url-prefixcourse-url-prefixThe prefix of the course URL, pointing at the course directory.
exercise-url(exercise-url lecture-id exercise-id)Return an absolute URL to a particular exercise.
export-course-calendar-entries(export-course-calendar-entries to-file)Export this course's calendar entries to to-file.
general-overview-links(general-overview-links)A function which returns a list of links which go into the overview frame (the leftmost frame of the frameset) of the course home page.
generating-system(generating-system)Return a string which tells about the generating computer system.
init-course-plan(init-course-plan)The init-course-plan function must be called after all loading is completed, and before any pages are generated.
last-lecture-numberlast-lecture-numberThe last lecture-number which we want presented now.
lecture-description-listlecture-description-listA list of lecture records.
lecture-number-url(lecture-number-url n)Return an absolute URL to lecture number n in this course.
lecture-plan(lecture-plan id . keyword-parameters)Write the plan of a given lecture to a html file.
make-color-scheme(make-color-scheme dark dark-text light triangle-image)Return a color scheme in terms of a dark color (background of left frame), dark text color, light color (background of large right frame) and a gif triangle file name (usually in the dark color).
make-course-overview-pages(make-course-overview-pages home-page-name cal-year cal-month cal-number-of-months cal-title external-calendar-entries)Make course overview pages, including the course home page, and the course calendar.
meta-course-contribution(meta-course-contribution)Return a list with course meta information to be put on any course page.
meta-tag-clauses(meta-tag-clauses)A function which returns meta information, inserted by html:page.
overview-pixel-widthoverview-pixel-widthThe pixel width of the overview frame (leftmost frame of course home page).
periodic(periodic start n period)Return a list of times, length n, starting with start, and with the period period.
preferred-calendar-pixel-widthpreferred-calendar-pixel-widthThe total pixel width of a calendar.
standard-links(standard-links)A HTML string returning function with standard links from course-plan pages.
subject-listsubject-listA list of subject records.
teacher-nameteacher-nameThe name of the teacher(s).
time-listtime-listA list of times for the individual lectures in the course.
tracing-comment(tracing-comment)A function which returns trace information.
us-relative-url(us-relative-url id)Return a relative URL to a particular lecture page (as generated by the lecture-plan function).
write-course-html-file(write-course-html-file contents file)Write the contents in the course's html file.

 

1.   OVERVIEW AND ORGANIZATION.
The course plan document style relies on a complete description of a course plan in terms of lecture lists, time lists, subject lists, and a number of other parameters. The course description is represented in a single central Lisp file, the course description file.

Besides the course description file there is one central LAML file which generates the introduction, the overviews, and the HTML frame pages. The is caled the LAML course file. Besides these two files there exists a file pr. lecture, typically (but not necessarily) organized in a directory of their own. Finally, there may be other course files with additional text, which are produced with the course file look using the functions course-page write-course-html-file. The course plan document styles features a very convenient handling of time. If the course runs perodically and regularly the determination of the individual lecture times is almost made automatically, see time-list below. The temporal power of the system is used to generate overviews and calendars (by means of the LAML calandar tool). We use a separate and simple time-list, external from the other lists, to provide for very easy rescheduling of lectures.

We recommend the following directory and file organization when using the course plan document style: 

 course-dir html (*) images  (*) internal (*) lecture-pages course-description.scm course.laml
All but course.laml and course-description.scm are directories. Only those directories marked by (*) need to have the mentioned names. We will now describe the role of each of the directories and files: The html, html/images, and the internal directories are created automatically by the course-plan system. In a later section we will show examples and templates of the directories and files.
 

2.   THE COURSE DESCRIPTION.
The definitions in this section must be redefined in the course-description file which should be located in course-dir, which is defined below. The course description file must be loaded just after the style loading clause. The central description structures (lists) are time-list, lecture-description-list, and subject-list.

subject-list


Form
subject-list

Description
A list of subject records. A subject record is a list of (subject-id title subject). The default is the empty list. Is allowed to be longer or shorter than lecture-description-list. Entries are looked up via the subject-id.

lecture-description-list


Form
lecture-description-list

Description
A list of lecture records. A lecture record is the central description of a single lecture in the course, in terms of a lecture-id, a subject-id (referring to a record in suject-list), exercise time info, plenum time info, and room info. The list must be of the same length as time-list. Lecture record description: Lecture-id: A symbol identifying a lecture. - Subject-id: A symbol identifying a subject in subject list. - Exercise-info: A list of (start-displacement length). Displacement relative to lecture start in time-list. Length in seconds. - Plenum-info: A list of (start-displacement length). Displacement relative to lecture start in time-list. Length in seconds. - Room: A room id string.

time-list


Form
time-list

Description
A list of times for the individual lectures in the course. Each time is an integer (the number of seconds since jan. 1, 1970). Use the function time-encode from the LAML time library to return such a number. Must be of the same length as lecture-list.

course-title


Form
course-title

Description
The title of the course (a string). Must be defined in the course description file.

brief-course-title


Form
brief-course-title

Description
A brief, abbreviated course title (a string). Must be defined in the course description file.

course-semester


Form
course-semester

Description
Course semester (a string). Must be defined in the course description file.

brief-course-semester


Form
brief-course-semester

Description
Brief course semester (a string). Must be defined in the course description file.

teacher-name


Form
teacher-name

Description
The name of the teacher(s). Defaults to "The teacher"

course-dir


Form
course-dir

Description
The absolute path of the course directory. Ends in a slash. Must be defined in the course description file.

course-url-prefix


Form
course-url-prefix

Description
The prefix of the course URL, pointing at the course directory. Ends in a slash. Must be defined in the course description file.

standard-links


Form
(standard-links)

Description
A HTML string returning function with standard links from course-plan pages. As default, no standard links are defined.

general-overview-links


Form
(general-overview-links)

Description
A function which returns a list of links which go into the overview frame (the leftmost frame of the frameset) of the course home page. Each element of the list must be a list of the format ("url" "anchor-name" "target"). The target may be "main" (for the main, rightmost window of the frameset) or "_top". Thus this function must return a list of lists. The links given here are added to some automatically generated links to overviews, calendar, and introduction. If you want additional general links, redefine the function in the course description file. As the default, this function returns the empty list.

tracing-comment


Form
(tracing-comment)

Description
A function which returns trace information. Must return the emtpy string of an HTML comment. The LAML function html:page uses and expects this function. You can use the LAML function html-comment when implementing the function. The default implementation returns the empty string.

meta-tag-clauses


Form
(meta-tag-clauses)

Description
A function which returns meta information, inserted by html:page. The LAML function html:page uses and expects this function. Must return a list of property lists of meta information. The default implementation returns the empty list (no meta information).

meta-course-contribution


Form
(meta-course-contribution)

Description
Return a list with course meta information to be put on any course page. Similar to the function meta-tag-clauses. The result of this function is passed more directly to the html:page function via the course-plan document style. As default no meta descriptions are provided.

last-lecture-number


Form
last-lecture-number

Description
The last lecture-number which we want presented now. Using this variable we can progressively reveal more and more lectures in the course. Must be defined in the course description file.

overview-pixel-width


Form
overview-pixel-width

Description
The pixel width of the overview frame (leftmost frame of course home page). Default 320.

preferred-calendar-pixel-width


Form
preferred-calendar-pixel-width

Description
The total pixel width of a calendar. OK for one semester, but problematic for other course spans.

course-start


Form
course-start

Description
The time (second-count) of the first lecture in the course. Must be defined in the course description file.

actual-exercise-interval


Form
(actual-exercise-interval this-lecture-rec next-lecture-rec)

Description
Given the records of this lecture and the next-lecture, return an interval of the exercise time. Return #f if there are no exercises. Depends on the model: forskudte øvelser til næste øvelsesgang. This function may return #f in case there is no lectures. next-lecture-rec may be #f in which case this function also returns #f. Must be redefined in the course-description-file.

 

3.   TOP LEVEL COURSE PLAN FUNCTIONS.
The top level functions used in individual lecture pages (pages describing a single lecture plan in the course) are init-course-plan and lecture-plan. Besides these, the exercise functions described later are typically found in a lecture plan file.

init-course-plan


Form
(init-course-plan)

Description
The init-course-plan function must be called after all loading is completed, and before any pages are generated.

lecture-plan


Form
(lecture-plan id . keyword-parameters)

Description
Write the plan of a given lecture to a html file. The id parameter is mandator. The keyword parameters are each of the form (key value), where key is one of literature, guide, exercises, references, and misc. The function writes the plan to an HTML file in the course html directory. The name of the files will be identical to the name of the LAML file, in which the source (with the lecture-plan form) is located. This function the central function for generation of individual lecture plans for lectures in the cource.

 

4.   COLORS.
The graphical idea of the course home page is to show the left frame in a dark color with white text, and the right large main frame in a light color with black text. The course plan document style supports color styles in terms of related colors and (currently) a single gif image file. You can make a new color scheme, and you can apply an existing color scheme.

course-calendar-color


Form
course-calendar-color

Description
The color used to mark course entries in the calendar.

make-color-scheme


Form
(make-color-scheme dark dark-text light triangle-image)

Description
Return a color scheme in terms of a dark color (background of left frame), dark text color, light color (background of large right frame) and a gif triangle file name (usually in the dark color).

apply-course-plan-color-scheme


Form
(apply-course-plan-color-scheme color-scheme)

Description
Apply a given color scheme

course-plan-color-scheme-1


Form
course-plan-color-scheme-1

Description
A sample color scheme: Purple and yellow

course-plan-color-scheme-2


Form
course-plan-color-scheme-2

Description
Another sample color scheme: Read and yellow.

course-plan-color-scheme-3


Form
course-plan-color-scheme-3

Description
Another sample color scheme: Black and white.

course-plan-color-scheme-4


Form
course-plan-color-scheme-4

Description
Another sample color scheme: Blue and grey.

course-plan-color-scheme-5


Form
course-plan-color-scheme-5

Description
Another sample color scheme: Blue and grey.

generating-system


Form
(generating-system)

Description
Return a string which tells about the generating computer system. Default: the empty string.

 

5.   COURSE OVERVIEWS.
This sections contains a single function which generates convenient overviews of a course, including the 'home page' of the course. A call of this function is typically made by the LAML file which produces the course introduction, which must have the name "course-introduction".

export-course-calendar-entries


Form
(export-course-calendar-entries to-file)

Description
Export this course's calendar entries to to-file. Only this course's entries are exported. The export format is the 'native' calendar format, as defined by the interactive, server-based LAML calendar tool. URL's to lectures are made absolute via the exporting. If to-file exists, overwrite it.

make-course-overview-pages


Form
(make-course-overview-pages home-page-name cal-year cal-month cal-number-of-months cal-title external-calendar-entries)

Description
Make course overview pages, including the course home page, and the course calendar. home-page-name is the name of the home page file, without extension and without path information. cal-year, cal-month, and cal-number-of-months determine the calendar range. cal-title is used to define the title of the calendar. external-calendar-entries is used to pass additional calendar entries to the course calendar (a list of entries). The entries must be in the 'calendar-events' format, as documented in the LAML calendar tool.

 

6.   COURSE PLAN EXERCISE FUNCTIONS.
The course-exercise function may, for instance, be called after the lecture-plan function in order to define an excercise for the lecture. Each exercise is written on a separate HTML file. The URL function course-exercise-ref can be used to refer to the exercises from the lecture-plan.

course-exercise


Form
(course-exercise id number body . lecture-id)

Description
Define an exercise with a certain id (symbol), a number, and a body. The exercise belongs to lecture-id, which is optional in cases the course-exercise follows a lecture-plan clause. id is a symbol identifying the execise. number is the execise number or letter.

course-exercise-ref


Form
(course-exercise-ref id number lecture-id)

Description
Return an URL to an exercise. The URL is relative, and only works from HTML files in the course html directory. id is a symbol identifying the execise. number is the execise number, a letter or an integer. lecture-id identifies the lecture, to which the exercise belongs. The function return a link to the exercise, and it is only applicable from a lecture plan page. See the function exercise-url for an absolute url.

 

7.   URL FUNCTIONS.
These functions define a few useful URL functions. The user is encouraged to write more such functions in the course description file.

us-relative-url


Form
(us-relative-url id)

Description
Return a relative URL to a particular lecture page (as generated by the lecture-plan function).

exercise-url


Form
(exercise-url lecture-id exercise-id)

Description
Return an absolute URL to a particular exercise.

lecture-number-url


Form
(lecture-number-url n)

Description
Return an absolute URL to lecture number n in this course.

 

8.   INTERNAL FUNCTIONS OF INTEREST.
Here we wil document a few internal functions which may turn out to be useful in some contexts.

course-page


Form
(course-page title body)

Description
Return a course page (with standard graphical elements, header, body and some footer stuff (standard-links)). This functions returns an HTML string. Use this function together with write-course-html-file if you want to make additional course plan files.

write-course-html-file


Form
(write-course-html-file contents file)

Description
Write the contents in the course's html file. The contents is typcically an activation of course-page. File is without extension and without any path information. This function adds an html extension. Use this function together course-page if you want to make additional course plan files.

 

9.   UTILITY FUNCTIONS.
Here are some functions which are useful when producing course home pages.

periodic


Form
(periodic start n period)

Description
Return a list of times, length n, starting with start, and with the period period. This function can be used to produce the time-list in case of a regular course rythm.

 

10.   AN EXAMPLE OF A COURSE HOME PAGE
One of the best ways to learn about the course plan document style is to study an example. As part of the LAML example collection we also provide a course plan example, where you can see the Scheme and LAML sources together with the generated HTML pages.

 

11.   TEMPLATE STUFF
If you are going to create a course home page via use of the LAML course plan document style the template described in this section is a possible starting point. We have made a directory structure with templates of all the central elements. The capitalized names should be filled in by you. It is possible generate the 'template course' once the course-dir in course-description.scm has been defined. The resulting course home page does not look nice, but it may be instructive to take a look at it anyway. The resulting HTML files can be navigated to above, but they are not part of the zip file. We have also made a zipped version of the template directory for your convenience. You can unzip it into the parent directory, in which you want your course home page to reside. It creates a course directory called 'template'. Afterwards, rename 'template' to something which makes sense.

Generated: Monday, November 14, 2011, 09:19:25
This documentation has been extracted automatically from the Scheme source file by means of the Schemedoc tool