Reference Manual of the LENO Lecture Note System

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

Source file: styles/lecture-notes/lecture-notes.scm
LAML Version 22.00 (October 29, 2003, alpha-3)

This is the reference manual of the original LENO Lecture Note System. The current version of LENO is XML-in-LAML LENO. Although the LENO software, documented here, is very much alive, this manual is obsolete.
This manual - the manual of the original LENO system - is not maintained any more. However, the underlying Scheme program of LENO, styles/lecture-notes/lecture-notes.scm, is maintained because it still makes up the kernel of LENO - indenpendent of its interface.
Using LENO it is possible to make web-based teaching material. The collection is structured in chapters. Each chapter is used in a separate lecture. LENO supports a comprehensive linking of slides within a chapter, and linking between the chapters. Overview pages are generated for each chapter, and lecture wide for all chapters. LENO also supports an alphabetic index with links to slides given selected index words, concepts, and slide titles.
LENO supports three different views on the slide: Slide view, annotated slide view, and a more book-like view. In slide view, the main text of the slides are shown in using a relatively large font. In the annotated slide view, the slide is shown to the left, and the annotations are shown to the right. In the book-like view, the slide contents and the annotations are mixed into a single, long text with marginal comments. All three views can be seen from any Internet browser, because it is translated to simple and plain HTML.
LENO is implemented by means of LAML, which means 'Lisp Abstracted Markup Language'. In LAML a number of Scheme expressions are executed with the purpose to generate HTML counterparts.
This document is the reference manual of LENO. It documents the primary user level 'markup' functions, which act as special purpose slide markup functions. Furthermore, it documents a number of preamble clauses, through which it is possible to set set of lecture notes, Finally a number of utility functions are described.
There exists a separate overview of the CSS support for LENO.
If you want to see examples of material constructed via LENO you can consult the slides to the talk Using Lisp as a Markup Language - the LAML approach, the Lecture Notes on Object-oriented programming (in Danish - the most substantial example until now), and a meta material Using LAML for WWW Authoring (where each of the major markup elements in LENO is demonstrated in a very concrete fashion). You should also pay attention to the very simple (and somewhat artificial) introductory LENO examples provided with this software.

Table of Contents:
1. Overall organization 4. Clauses of the note-page form 7. Cross Reference Support
2. Preamble stuff 5. LENO Emacs Support 8. Show and speak functionality
3. Top level functions 6. Useful templates 9. Some relevant functions from the LENO implementation

Alphabetic index:
additional-showing-time additional-showing-time An additional number of seconds added to the showing times of each show-and-speak page.
answer (answer possible-answer correctness-point clarification) Define a single answering possibility side by side with other possible answers
answers (answers . answer-list) Define a number of possible answers of a quiz clause
applet-program (applet-program class-file codebase explanation width height) Defines and inserts a Java applet
author-home-url author-home-url A variable the value of which must the URL of the author home page.
begin-notes (begin-notes) This form marks the ending of the preamble and the beginning of the note page definition part.
book-url (slide-url lecture-id . slide-id) Return a URL of particular aggregated lecture.
comment (comment comment-text) Present an internal comment.
concept (concept concept-name concept-definition concept-explanation) Defines a concept in terms of its name, a concept definition, and a concept explanation.
concept-list (concept-list . concepts) Defines a number of concepts.
copy-image-files? copy-image-files? A variable which controls whether to copy image icons from the software directory to the note source directory.
copy-note-graphics? copy-note-graphics? A variable which controls whether to copy author defined graphics from the software graphics directory to the HTML destination directory.
course-dir course-dir A variable which defines the course directory, in which the course plan files resides.
course-home-url course-home-url A variable the value of which must be the URL of the course home page (a string).
cross-reference-location-hints (cross-reference-location-hints location-hints) A function which may return a hint of the location of a cross reference.
cross-references (cross-references reference-list) Define a number of cross references to other material.
current-lecture current-lecture An integer variable defining the chapter number of the last lecture to be generated.
default-showing-time default-showing-time The number of seconds to show a slide page with show-and-speak.
elucidate (elucidate description url target) Insert a link to an elucidator (accompanied with an eluciator icon) which explains a program.
end-notes (end-notes) States the ending of this lecture note file.
example (example example-text about-the-example) Defines an example which is shown in all views.
exclude-front-index (exclude-front-index) Arrange that no index of chapters is generated.
exclude-word-index (exclude-word-index) Arrange that no index of keywords will be generated.
exercise (exercise exercise-id exercise-title exercise-formulation . exercise-solution) Defines an exercise in terms of an id, a title, a formulation and an optional solution.
exercise-formulation-url (exercise-formulation-url lecture-id page-id presentation-kind exercise-number) Return a URL to an exercise formulation in a given lecture, and on a given page.
exercise-formulation-url-given-id (exercise-formulation-url-given-id lecture-id exercise-id . presentation-kind) Return a URL to an exercise formulation identified with exercise-id, located in a particular lecture.
exercise-model (exercise-model model) Set the exercise model to model.
exercise-solution-url (exercise-solution-url lecture-id page-id exercise-number) Return a URL to an exercise solution in a particular lecture, on a particular page.
formulation (formulation exercise-formulation-text) Defines the exercise formulation text
generating-system (generating-system) A parameter less function which is supposed to return a string describing the system, which has generated these notes.
image (image filename explanation formatter) Inserts a gif image from an external file.
image-series (image-series series-title image-descriptions how-to-show) Defines a series of images, which may define a number of steps.
image-series-part (image-series-part number time-list) Define an image-series part of the surrounding show and speak clause.
include-front-index (include-front-index) Arrange that an index of all chapters are generated.
include-word-index (include-word-index) Arrange that an index of distinquished keywords will be generated with links to the slides, where the words occur.
index-words (index-words . words) Defines a number of index words of this page.
informal-reference (informal-reference anchor-text reference-text . location-hints) Defines a reference to an off line resource, such that a paper or a book
internet-reference (internet-reference anchor-text url . location-hints) Defines a reference to an Internet resource
item (item primary-text secondary-text sub-items) Describes a single item.
items (items . item-list) Defines one of more items, to be presented as a bullet list
java-scripting java-scripting A boolean valued variable telling whether or not to use Javascript scripts.
javascript-loading javascript-loading A variable which determines how Javascript scripts are loaded.
lecture-intro (lecture-intro title author-list . abstract) Defines the title, authors and the abstract of this lecture note
lecture-note-verbose-mode lecture-note-verbose-mode A booelan Scheme variable that determines whether some feedback on progress etc is written out while the LENO system processes a LAML file.
lecture-sections lecture-sections A variable which keep track of the names and titles of all lecture chapters in these lecture notes.
lecture-title-page? lecture-title-page? A variable that controls the generation of a title page and an abstract page.
lecturer-photos (lecturer-photos start-photo-number number-of-photos) Present a number of lecturer photos on the current note page
lecturer-photos-and-logo (lecturer-photos-and-logo start-photo-number) Show two lecturer photos and a logo.
long-slide (long-slide) Declares that this slide is a long.
meta-tag-clauses (meta-tag-clauses) Returns meta information about these notes in terms of a list of list.
mouse-advancement mouse-advancement It is possible to advance from one slide to the next via either single or double click.
note-abtract note-abtract A variable the value of which is the overall abstract of the lecture notes (top level, covering all chapters).
note-download-url note-download-url A variable the value of which must the URL of page, from which download of the lecture notes is possible.
note-page (note-page page-id . note-page-elements) The outer level description of a page.
note-reference (note-reference anchor-text section-id slide-id . location-hints) Describes a reference to another part (possibly in another section) of the current lecture notes
note-source-directory note-source-directory A mandatory variable the value of which must be a string holding the full path of the directory, in which the LAML note files are located.
note-specific-image-files note-specific-image-files This optional variable is a list of image file names (without path, with extension such a gif) used specifically in these notes.
note-text (note-text text) Defines a text clause to appear in note page view and annotated slide view only.
note-url (note-url lecture-id slide-id) Return a URL of particular note page in a particular lecture
notes-title notes-title A variable which holds the title of the lecture notes (a string).
opposing (opposing . item-list) Presents a number of opposing items.
point (point primary-point secondary-point) A point is a distinguished observation which is presented with special emphasis in all views.
preferred-maximum-filename-length preferred-maximum-filename-length The preferred maximum length of file names.
program-part (program-part number time) Define a program-part of the surrounding show and speak clause.
question (question question-formulation) Defines the question of a quiz clause
quiz (quiz question answer-list) Define a contribution to a quiz about the current lecture.
quotation (quotation quotation-text quotation-comment) Defines a quotation, which is presented within quote characters.
relative-source-html-destination-path-fragment (relative-source-html-destination-path-fragment) A non-argument function which returns the difference between the note-source-directory and the note destination HTML directory.
section-title (section-title title-string) Defines the title of a section of slides.
set-language (set-language language) Defines which language to use in the LENO defined text of the lecture note system.
set-lecture-name (set-lecture-name name) Define the internal name of a chapter of the lecture notes (the chapter on the current file).
set-lecture-number (set-lecture-number n) Defines the chapter number of the current chapter.
show-and-speak (show-and-speak . show-speak-clauses) Define a number of 'show and speak' clause of the surrounding note page.
show-and-speak? show-and-speak? A boolean variable that controls the generation of an automatic progressing slide show with speaker sound, briefly referred to as 'show-and-speak'.
side-track (side-track title track-lecture-id track-explanation) Define a side track.
slide-header? slide-header? Define the style of headers to use in slide style.
slide-image (slide-image filename) Show a gif image in slide view and in the annotated slide view.
slide-part (slide-part number time) Define a slide-part of a surrounding show and speak clause.
slide-text (slide-text text) Defines a text clause to appear in slides views only.
slide-url (slide-url lecture-id slide-id) Return a URL of particular slide page in a particular lecture
solution (formulation exercise-solution-text) Defines the exercise solution text
solution-passwords solution-passwords A variable the of which is to define a number of password for exercise solution files.
source-program (source-program filename region-marks decorations how-to-show comment) Shows a source program (or a similar text of an artificial language) in 'verbatim style'.
speak-file-prefix speak-file-prefix The file prefix to the speaker sound.
speak-url-prefix speak-url-prefix The prefix of the URL to speaker sounds.
splice-page-with (splice-page-with tag-list lecture-id page-id [id]) Splice the elements of another page from a specified lecture-id including certain kinds of elements.
splice-page-without (splice-page-without tag-list lecture-id page-id) Splice the elements of another page from a specified lecture-id excluding certain types of elements.
style (style which-style) States the style of this LAML document.
synopsis (synopsis . synopsis-item-list) Defines a synopsis in terms of a list of synopsis item elements.
synopsis-item (synopsis-item synopsis-text synopsis-comment) Defines a single item in a synopsis clause
syntax (syntax syntax-rule syntax-explanation) Defines a syntax description in terms of a syntax rule and an explanation
tabular (tabular border column-widths table-contents table-explanation) Defines a tabular presentation of table-contents.
text (text primary-text secondary-text) Defines a text clause of a note page.
title (title title-string title-comment) Defines the title of a note-page
trail-of-lecture? trail-of-lecture? A boolean variable which controls whether to make a parallel trail of the lecture.

1. OVERALL ORGANIZATION
We start with a description of the overall organization of a set of lecture notes.

A set of lecture notes, say n chapters, reside on n laml files in a single directory. An laml file has extension 'laml'.

There is a single file, which provides common description of the set of chapters in a lecture note document. The name of this file is typicaly notes.scm, and it should reside in the same directory as all the laml files. The notes.scm file is loaded before the LENO software. It is often convenient, in addition to notes.scm, to load a file after the LENO software. Such a file, which may be called post-notes.scm, can be used to redefine LENO default values. It is intended that the notes.scm and post-notes.scm files contain information which is common to a number of lecture notes file (information which we will avoid being replicated in a number of lecture note files). Notes.scm contain a list, lecture-sections, which describes the identity and the titles of all chapters in the set of lectures notes. We refer to an annotated example of a notes.scm files later in this manual. Notice that notes.scm must be loaded explicitly by each laml lecture note file, just before the style clause (which loads the LENO software). If a post-notes file is used, it must be loaded explicitly just after the style clause.

Here follows the subdirectory structure of the directory with LENO lecture notes:

notes
  html
    graphics
      small
    images
    javascript
    applets
    external-html
  graphics
    small
  images
  includes
  internal
  latex

All of the names above are directory names.

The notes directory contains the laml files (one laml file per chapter in the notes), notes.scm, and post-notes.scm.

The graphics directory in notes contains the sources of the user defined graphics used in the notes. The small subdirectory contains manually reduced copies. If the variable copy-note-graphics? is #t, the graphics file from notes/graphics are copied to the html/graphics. If this variable is #f (false) you are supposed to put the graphics file into the html/graphics directory yourselves. Similarly, the notes/graphics/small files are copied to html/graphics/small.

The html directory contais all the generated html files, and as can be seen, it contains a number of sub-directories. This organization is handy, because you can pack the html directory in order to obtain a total, complete and self contained set of information at HTML level. In other words, the contents of the html directory is enough to use the material in an Internet browser. The javascript directory contains a tiny amount of javascript stuff used by Lene. When LAML processing a note file, this directory is populated automatically.

It is possible to organize that the html directory is placed outside the notes directory. In order to do that you should redefine the function relative-source-html-destination-path-fragment, which defines the path 'difference' between the note source directory and the HTML destination directory. In the default case, this function just returns "html/".

The notes/graphics directory contains gif files for all the figures of the notes. The author of the notes is responsible for the population of this directory, as well as the subdirectory called small. If f.gif is a file in html/graphics, f.fig must in addition be found in html/graphics/small. The idea is to reduce the figure in f, and to place the reduced figure in the small directory. This turns out to be necessary, because a browser makes very rough and poor reductions of pictures. The variable copy-note-graphics? controls the copying of files from notes/graphics to html/graphics.

The images directory contains note-specific icons that are used throughout the LENO systems. (The LENO software support its own images, which are organized in the LAML directories). When we run LENO (thus generating the HTML version of the slides etc) the relevant image icons are copied from the notes/images directoy to the html/images directory. Therefore we do not need to copy the images into this directory on beforehand.

In the applets directory you should place java class files with applets.

The directory external-html is intended to contain html files, which are considered an integrated part of a set of lecture notes, but being outside the LAML domain. In other words, here you can put html files, which somehow are relevant for the lecture notes.

The internal directory contains helping files in Lisp format with extensions aux, crs, exc, and idx. Most users of LENO do not need to care about these files. They are generated when a lecture on an LAML file is processsed. The aux file contains the name of the lecture together with an 'record' for each page in the lecture. The crs file contains information about all cross references found in a lecture. The exc file contains information about all the exercises of a lecture. And finally, an idx file contains all contributions to the index file from a given section.

The includes directory can be used to material which is included (copied into) the notes. In other words, the material in the include directory is source material, which is addressed from the LAML note files. Such included material can also come from other places in your file system.

The latex directory is intended to contain a latex version of the lecture notes, generated by means of the style "lecture-notes/lecture-notes-latex".

2. PREAMBLE STUFF
Here we describe the various declarations which are possible to include before the (begin-notes) clause. Many of the declarations are carried out as (re)definition of Scheme variables.

The notes.scm files, introduced above, is an integral part of the preamble stuff. Notice that the contents of the notes.scm can be included inline in the preamble. This is, however, only recommended for single chapter lecture notes. For all the clauses of the preamble we will state whether to place the clause in the notes.scm, or in the laml chapter file. Most useful, perhaps, we have an example template of a lecture note laml file, where you can see a typical preamble.