Reference Manual of the XML-in-LAML Lecture Note System

A single lecture material consist on a single lecture only, and as such it is simpler than multi-section materials, which is described in the next section.

The following shows a template of single lecture LENO source file:

(load (string-append laml-dir "laml.scm"))       
(laml-style "lecture-notes/leno")

(leno-front-matters
  (front-title "TITLE")           
  (front-subtitle "SUBTITLE")   
  (front-author "AUTHOR NAME")           
  (front-affiliation "INSTITUTION")  
  (front-abstract "")  

  'scheme-suffix "post-notes.scm"
  'course-home-url "http://www.cs.auc.dk/~normark/"   
  'author-home-url "http://www.cs.auc.dk/~normark/"   
  'note-download-url ""   
  'logo-url "http://www.auc.dk/"  
  'note-contents-description ""    
  'slide-header "minimal"  ; minimal/normal/none 
  'trail-of-lecture "false"  
  'language "danish"      
  'show-and-speak "false" 
    'default-showing-time "2"    
    'additional-showing-time "0" 
    'sound-source "real-audio" 
    'speak-url-prefix "../../speak/"
  'exercise-model "none"   
  'mouse-advancement "double-press" 
  'word-index "true"  
  'apply-css-styling "false"
  'news-flash-string  ""  
  'news-flash-level   "2"
  'quiz-support "false"   
  'verbosity-level "1"
)

(begin-notes)


  (note-page 'id "sec-id"
    (section-title "TITLE")
  )
  
  (note-page 'id "page-id"
    (title (main-text "TITLE")
           (annotation "ANNOTATION")
    )

    (point
     (main-text "TEXT OF POINT")
     (annotation "ANNOTATION OF POINT")
    )
  )


(end-notes)

It is easy to initiate a single lecture material in LENO when you work with LENO and LAML in Emacs. Just initiate the command M-x make-lecture-notes ,and you are started. Use the templates in the Emacs LENO menu to construct your document.

The scheme-suffix attribute of the leno-front-matters clause allows you to read a Scheme file with ordinary Scheme definitions. (This file is loaded after the loading of all LENO software). Use this file to organize ad hoc convenience functions, which help you manage a complex material. There is also a similar scheme-prefix attribute, which you do not need to care about for single chapter materials. The Scheme definitions in the scheme prefix file are read before the LENO software is loaded.

A multi lecture material consist of a number of LAML source files which each represents a chapter (lecture) in the material. Usually, we organize the common aspects in Scheme prefix and Scheme suffix files, which are shared among all the chapters.

The Scheme prefix file, addressed by the scheme-prefix attribute of leno-front-matters clauses, must be present for multi-lecture materials. Here is an example of this file:

(define notes-title "LECTURE NOTE TITLE")
(define notes-subtitle "LECTURE NOTE SUBTITLE")

(define note-abstract
  "ABSTRACT")


(define lecture-sections
  (list
     "lect1"
     "lect2"
     "lect3"
  ))

(define current-lecture (length lecture-sections))

As it appears, the Scheme prefix file defines the note titles, the abstract, and most important a list of lecture names (proper file names of the each lecture/chapter). The variable current-lecture can be set to a value smaller than the length of the lecture-sections, in case you do not want to link to details in the latter chapters yet.

The Scheme suffix file, addressed by the scheme-suffix attribute of the leno-front-matters clauses, can contain additional Scheme definitions.

The following shows a template of a lecture in a multi lecture LENO material:

(load (string-append laml-dir "laml.scm"))       
(laml-style "lecture-notes/leno")

(load "common-front-matters-stuff.scm")

(leno-front-matters
  (front-title "TITLE")           
  (front-subtitle "SUBTITLE")   
  (front-author authors)           
  (front-affiliation institutions)  
  (front-abstract "ABSTRACT")  

  common-attributes
  'process-all-lectures "true"
)

(begin-notes)


  (note-page 'id "sec-id"
    (section-title "TITLE")
  )
  
  (note-page 'id "page-id"
    (title (main-text "TITLE")
           (annotation "ANNOTATION")
    )

    (point
     (main-text "TEXT OF POINT")
     (annotation "ANNOTATION OF POINT")
    )
  )


(end-notes)

Notice the loading of 'common-front-matters-stuff.scm' which conveniently define a number of properties shared by the leno-front-matters clauses in all lectures. (We cannot define this in the scheme-prefix or scheme-suffix clauses, because these are first brought to the attention of LENO through the leno-front-matters clause itself.) Here is a typical 'common-front-matters-stuff.scm' file:

(define authors "AUTHORS")
(define institutions "AFFILIATIONS")


(define common-attributes
 (list

  'scheme-prefix "pre-notes.scm"
  'scheme-suffix "post-notes.scm"

  'course-home-url "http://www.cs.auc.dk/~normark/"   
  'author-home-url "http://www.cs.auc.dk/~normark/"   
  'note-download-url ""   
  'logo-url ""  
  'note-contents-description ""    
  'slide-header "normal"  ; minimal/normal/none 
  'trail-of-lecture "false"  
  'language "english"      
  'show-and-speak "false" 
    'default-showing-time "2"    
    'additional-showing-time "0" 
    'sound-source "real-audio" 
    'speak-url-prefix "../../speak/"
  'exercise-model "none"   
  'mouse-advancement "double-press" 
  'word-index "true"  
  'apply-css-styling "false"
  'news-flash-string  ""  
  'news-flash-level   "2"
  'quiz-support "false"   
  'verbosity-level "1"
 )
)

As of now, there is no easy way to make all the pieces of a multi lecture material. It is probably easiest first to initiate a single lecture material, and to create the missing pieces (as described above) manually.

We start with a description of the overall organization of a set of lecture notes. 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
  stylesheets

All of the names above are directory names.

The notes directory contains the laml files (one laml file per chapter in the notes), the Scheme prefix and Scheme suffix files, and other source related files. Your are in control of the real name of this directory. When LENO is executed, an HTML file per lecture is placed in the notes directory.

The html directory contains all the generated html files, and as can be seen, it contains a number of sub-directories. This organization is handy, because you can zip the html directory in order to obtain a 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 Leno. When you process a LENO file the javascript 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 define the source-destination-delta attribute of the leno-front-matters clause. This attributes defines the path 'difference' between the note source directory and the HTML destination directory. In the default case, the value of this attribute is "html/" .

The notes/graphics directory contains gif, jpg, or png 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, for instance, f.gif is a file in html/graphics, f.fig must in addition be found in the directory html/graphics/small. The idea is to reduce the figure in f.gif, and to place the reduced figure in the small directory. This turns out to be necessary, because most browsers makes very rough and poor reductions of pictures.

The images directory contains note-specific icons that are used throughout the LENO systems. In most situations, this directory is empty (or it contains only the logo.gif image). Location hint icons, as described in the documentation of the function cross-reference-location-hints, serve as examples. The note-specific icons do not include the graphical illustrations nor the LENO icons. When you run LENO (thus generating the HTML version of the slides etc) the relevant image icons are copied from the notes/images directory 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, spk, lsp, and idx. Most users of LENO do not need to care about these files. They are generated when a lecture on a 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. lsp files contains a complete representation of the slides in a list representation. spk files contains information about show-and-speak details (if applied). 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 stylesheets directory contains note-specific CSS stylesheets. If you want to affect the appearance of your LENO slides you can organize your CSS files in this directory.

The element mirror functions described in this section are really subelements of the leno element. However, as already explained, we recommend that the LENO top level structuring is ignored. With this, the forms in this section becomes top level elements side by side with leno-front-matters .

A number of attributes are widely available in many note page subclauses. These are

• id : An optional identification of note page subclause. Must be unique within a note page. If you use the theme facility it is important to use the id attributes of the elements described below.
• margin : Margin around the subclause, using CSS semantics. Remember a unit, such as em or ex
• margin-left : Margin around the subclause, using CSS semantics.
• margin-right : Right margin of the subclause, using CSS semantics.
• margin-bottom : Bottom margin of the subclause, using CSS semantics.
• margin-top : Top margin the subclause, using CSS semantics.
• drop : A boolean attribute which makes it possible to disregard a note page subclause, in the same way as note-page can be dropped.
• annotations : An attribute of relevance only to the LENO theme facility. Tells how annotations are treated in a thematic presentation of the material.

There is a number of useful Emacs commands that make it easy and convenient to author LENO material. Most important, perhaps, is the function which help initiate a new set of slides (a single lecture only). This command is called make-lecture-notes .

In Emacs there is a LENO menu in which many LENO relevant editor commands are available. This is very useful for newcomers. You can use this menu to see the keyboard shortcuts to a number of commands.

The table below lists the other LENO specific Emacs Lisp commands. These will all be available if you have installed the LAML system appropriately. The list is not necessarily complete, but the LENO menu of Emacs is! The keyboard shortcuts are based on the assumption that you use the hygienic emacs keybindings in the LAML configuration file. If you use the original keybindings you can ignore the leading C-c.

The Emacs Lisp variable laml-pp-helpful (of type boolean) controls the detailed working of most of the leno-insert-... functions from above. If the value of laml-pp-helpful is t (for true) it shows the roles of the individual constituents. If nil (for false) just empty string placeholders are presented.

Please also notice the following generally useful LAML Emacs commands (shown with hygienic key bindings):

It is often useful and necessary to refer from one piece of LENO information to another. In this section we will document the various cross reference facilities supported by LENO. The functions in this section return URLs to other pages generated by LENO.

Recall the cross-references clause of LENO, the purpose of which is to define cross references to other note pages, or to external material. The cross-references clause is a constituent of a note-page.

In this section we describe the show and speak functionality of LENO. This facility provides for an automatically progressing lecture with the lecturer's speaker sound. It is rather difficult to arrange for show and speak functionality in LENO. The information below will give you a help in the right direction, but it is probably not complete, nor totally up-to-date.

The LENO clauses related to the facility is described elsewhere. Here we will focus on the practical procedure for recording and arranging the sound clips in relation to a LENO material.

At the overall level, we can observe that the show and speak facility is based on the following:

1. To each note page there is one or more corresponding sound clips

2. On each note page we specify the sequencing and timing of the sound clips using a show-and-speak clause

3. The sound clips are brought to the appropriate sound files by means of a LENO utility tool, found in the xml-in-laml LENO source program directory's util branch.

4. A number of leno-front-matters attributes control the show and speak facility, most important the one called show-and-speak. These are all attributes in the leno-front-matters element.

The practical procedure for making and arranging a set of sound files is the following:

1. Specify the sounds in the leno source, using (show-and-speak ...) clauses

2. Be sure that the attributes show-and-speak is set to true.

3. Process the lecture with the variable show-and-speak-recording? set to #t. Set in post-notes.scm. This will cause the numbers of the source sound files to appear in the annotated slide view. Using this information it is easy to find out where to locate a given sound clip.

4. Record the sounds, on files 1.wav, 2.wav, etc. in a subdirectory of the sound dir. We recommend to organize the sounds outside the note source directory, because they are too voluminous.

5. Move the sound files from its subdirectory up one level to the sound directory. During the moving, the files should be renamed appropriately. The mentioned utility program does this, based on the information in the internal -.spk file.

6. Process the leno LAML source file again. In this processing, be sure to set show-and-speak-recording? to false - #f.

As another practical information, the processing of a LENO laml file with show-and-speak clauses (and with show-and-speak? set to #t) generates a -.spk file in the internal directory. This file holds all the bookkeeping information about the show-and-speak clauses in a LENO laml file.