Download LAML       Install LAML       LAML Browser       Scheme Browser       LAML News       Why LAML?       LAML System Overview       Porting LAML       LAML Tutorial       LAML Home      

LAML

This is the homepage of LAML Version 23.00 (December 12, 2003, full). This is the full distribution, including all available documentation. As an alternative, it is possible to download a slim version with only the Scheme files (without the tutorial, without manuals, and without the examples directory). The slim version is much smaller than the full version. The slim version may be OK for a first try of LAML, but we recommend the full version for more serious work.

The LAML home page at the Computer Science WWW server at Aalborg University contains additional and up-to-date information about LAML. The development version of the LAML software home page is also available.

LAML means Lisp Abstracted Markup Language. The main idea behind LAML is to bring XML and HTML into the domain of the Scheme programming language. The LAML tutorial is a good place to start.

You can use the LAML software together with any R4RS or R5RS compliant Scheme system. The Scheme system must, however, support a few compatibility functions that give access to operating system resources. We recommend that you use one of the XHTML mirrors, or one of the existing XML-in-LAML languages we provide. (The HTML4.01 mirror, as well as number of earlier mirrors, are only supported because a number of useful document styles and tools still make use of them).

The LAML distribution also contains the Scheme elucidator (a tool for creation of elucidative programs), SchemeDoc (a system to document Scheme libraries), and the LENO system (a system for creation of web-based teaching materials). You may also be interested to read the LAML background page.

It is also possible to create your own XML-in-LAML language from an XML DTD, using the LAML DTD parser and the LAML mirror generation tool.

LAML can be used for creation of both static WEB pages and for server side CGI programming purposes (via the cgi library).

For installation details, please see the installation section below.

LAML is free software, as defined by the GNU general public licence.

In order to trace the recent developments of the system please consult the page what is new in LAML.

Below follows a structured overview of the LAML software in terms of library interfaces and programmatic descriptions of styles and tools. Notice that all the examples, as referred by the right column, are found in the examples directory of the full version

Category Kind Manual Examples
LAML setup Fundamental LAML setup Manual -
XML-in-LAML Mirrors
and Styles
XHTML1.0 strict Manual Examples
XHTML1.0 transitional Manual Examples
XHTML1.0 frameset Manual Examples
SVG1.0 Manual Examples
LENO Lecture Notes Manual Examples
LAML Course Plan Manual Examples
LAML Manual and SchemeDoc Manual Examples
LAML Photo Show Manual Examples
Older LAML Styles Questionnaire Manual Examples
Article Manual Examples
LAML Libraries Generally useful Scheme functions Manual -
XML-in-LAML common library Manual Examples
XHTML convenience library Manual -
Time Manual -
Color Manual -
Reading and writing of text files Manual -
Buffered Input Streams Manual -
Finite state automaton Manual -
Cgi Manual -
URL encode and decode Manual -
Crypt Manual -
String make-up Manual -
Scheme pretty printing Manual -
MzScheme compatibility Manual -
Tools The Schemedoc tool Manual -
The Scheme Elucidator Manual Examples
The XML-in-LAML mirror generation tool Manual Examples
The Calendar tool - XHTML Manual Examples
The XML DTD parsing tool Manual Examples
Bibtex Manual Examples
XML parsing and pretty printing Manual Examples
HTML parsing and pretty printing Manual Examples
Additional Examples LAML Processing - Examples
LAML examples for a LAML paper - Examples
LAML examples for another LAML paper - Examples

Old stuff

LAML comes with a number of old styles and mirrors, which are used internally in some parts of LAML the software. New development should not be based on the old stuff. The old software can be accessed from above, in case you need to look at the details.

 

Which Scheme Systems?

The following table shows the existing LAML configurations by Scheme systems, Platform and Operating System, which correspond to the symbols scheme-system, laml-platform, and operating-system in the LAML configuration description.

Scheme System Applies to Platform Operating System Status Notes
mzscheme mzscheme 103, 101, ... unix solaris-7 and solaris-8 OK note
mzscheme-200 mzscheme 200, 201, 202, 203, 204 unix solaris-7 and solaris-8 OK note
mzscheme-200 mzscheme 200, 201, 202, 203, 204 unix linux OK note
mzscheme mzscheme 103, 101, ... windows win2000 OK note
mzscheme-200 mzscheme 200, 201, 202, 203, 204 windows win2000 OK note
mzscheme mzscheme 103, 101, ... windows win98 OK note
mzscheme mzscheme 103, 101, ... windows nt40 OK note
mzscheme-200 mzscheme 200, 201, 202, 203, 204 unix osx ? note
guile guile 1.4 unix linux OK note
guile guile 1.3, 1.4, 1.6 unix solaris-7 and solaris-8 OK note
drscheme drscheme windows win2000, nt40 OK note
scm scm unix solaris-7 and solaris-8 ? note
scm scm unix linux OK note
SISC SISC unix linux ? note

A bold 'OK' means that I use the combination myself, and that it works for me. An 'OK' means that am confident that the configuration works, and that it is supported in the distribution. (Perhaps I used it earlier, I have tested it to some degree, or others have reported positively on that combination.) When a combination is OK or OK you should be able to install LAML with no or very reasonable efforts (GNU Emacs support included). If you use a combination marked '?' I will not promise anything. In case you use a combination not mentioned above, you should make some porting efforts, and this is more difficult.

We have measured the speed of several Scheme systems on several machines on a long-running LAML script. In general, MzScheme 101 and 103 are the fastest. More details.

Case sensitiveness

Although Scheme is basically case insensitive, the LAML software does not rely on this property, and we recommend case sensitive reading. The LAML software is written in a case sensitive style, in the sense that a given name, such as xyz is consistently referred to as xyz, not XYZ nor xYz. The SVG mirror requires case sensitive reading of symbols, and in general XML is case sensitive. Guile uses case sensitive reader per default, and in MzScheme (read-case-sensitive #t) can be used to obtain it. (If you prefer, you can add this procedure call to the appropriate MzScheme compatibility file in lib/compatibility, but as of now it is not necessary to do so).

Which Emacs?

I recommend that you use LAML from GNU Emacs. The Emacs interface makes it possible to activate LAML directly on a buffer, and to produce an HTML file in a very flexible way. The Emacs interface abstracts away the starting of the Scheme system, and the loading of all the necessary files. The Emacs interface works well on both the UNIX and PC (NT4.0/Win98/Win95) platforms. You can download a PC version of Emacs (win95/98/NT) from the GNU FTP site. If you prefer, we offer a zipped version of GNU Emacs 21.2 for Windows from our web site. As of May 2003 I use version 21.7 but earlier versions (such as 20.7) will also work without problems.

Which non-standard functions are used in LAML?

The LAML software uses the following non-standard R4RS functions:

(current-time) Returns the number of seconds elapsed since January 1, 1970
(sort-list list leq-fn) Returns a sorted version of list. The sorting is based on the function leq-fn, which returns if two elements in the list are considered less than or equal. See note below.
(file-exists? file-path) Returns whether a file named file-path (full path) exists.
(delete-file file-name) Deletes a file.
(directory-exists? dir-path) Returns whether the full directory dir-path exists.
(copy-file source destination) Copy the source file to destination file. Both source and destination are supposed to be full paths.
(make-directory-in-directory in-directory-path new-dir) Make a new directory new-dir in an existing directory path. Used in LENO and Course-plan.
(directory-list path) Return a list of files and directories in path. The resulting list does not include the directories named '.' and '..'.
(eval-cur-env e) Evaluates the expression e in the current interaction environment.
Rationale: Bridges the differences between R4RS systems (in which eval is not standardized) and R5RS systems, in which eval takes two parameters.

In addition, the following functions are desirable although not used in the central pieces of the LAML software. If you cannot implement them, just relax...

(getenv name) Read and return the value of an environment variable in the operating system. Used for LAML CGI programming purposes.
(mail receiver title contents) Send email to receiver with title and contents.
(bound? name) Return if the name is bound in the current interaction environment.

The Scheme system compatibility files in lib/compatibility/ provide implementations of the functions mentioned above. (In case no implementation is possible, we call the error procedure.) In the distribution, there are compatibility files for a number of Scheme systems and operating systems. When you have installed LAML, the appropriate compatibility file will be loaded automatically.

A note about sort-list: If you cannot easily provide an implementation of sort-list, we provide the file lib/compatibility/sorting/sort.scm with Aubrey Jaffer's sorting functions. You can include this file in the compatibility file and add (define sort-list sort:sort).

Installation

You are supposed to unzip the LAML distribution into a directory of your choice. Next you have to make a few modifications to a configuration file in order to describe properties of your installation. Finally you run a particular Scheme program which effectuates the configuration process. See the LAML installation guide for details on that. We assume that you are a competent Scheme programmer, and as such that you are able to fix simple installation problems that may occur.

Processing LAML files

By processing an LAML file (a file with extension laml) the LAML Scheme expressions are translated to HTML. Thus, by processing the file f.laml you typically get g.html in the same directory. Usually f equals g (depending on the method of processing).

When we start a LAML process, we transfer a bit of context to the processing which gives us knowledge about the name of the file, on which the laml source resides, and the directory in which the source file is placed. In addition, the underlying Scheme process needs to know where the LAML software is located (and a few other options to allow correct processing using a particular Scheme engine).

We support the following LAML processing methods:

  • Via an Emacs text editor
    The Emacs commands M-x laml-process-current-buffer or M-x laml-sync-process-current-buffer starts a Scheme processor on the buffer containing an LAML file. The command laml-process-current-buffer is bound to C-o in the original setup, and to C-c C-o in the hygienic setup. This is undoubtedly the most flexible method of LAML activation. It requires Emacs to be configured appropriately. The Emacs configuration is described as part of the LAML installation guide referred to above.

  • Via an operating system command file called laml
    From a command prompt activate the laml command on an laml file in the current directory:
    c:\users\kurt\laml>  laml file
    The file is written without the laml extension. First, however, insert the laml/bin directory into your PATH. Also, on UNIX, make sure that the command file is executable ( chmod 775 laml, for instance).

    On some platforms we also support the variant

    c:\users\kurt\laml>  absolute-laml absolute-path file
    where absolute-path is the file path leading to file (again given without extension). This variant is useful from cron jobs, which starts LAML processing at some given point in time.

    The laml command depends on bin/SETENV.EXE which does not work on NT4.0 and Windows 2000, but it works on Win95/98. Thus, it is currently not possible to use the this mode of activation on Window NT or Windows 2000. The laml command works on Unix.

  • Directly from a running Scheme interpreter in Emacs
    Activation the Emacs command M-x run-laml-interactively. This gives you a Scheme system in which LAML has been loaded. This means of LAML execution is useful for interactive experiments and for debugging purposes.

    You can control which HTML/XML mirror to use via the Emacs command M-x set-interactive-laml-mirror-library . This commands will present the possibilities, via Emacs completion. As the default, the fully validating HTML4.01 mirror is used.

    You can use the laml procedure to process a LAML file. You can also use one of the LAML tools. Use the single-parameter procedure laml-cd to change the working directory, laml-pwd to find out about the working directory, and laml-ls to list the working directory ( laml-ls depends on directory-list ).

  • Directly from a running Scheme interpreter (outside Emacs)
    First start your Scheme system.

    1. Define the variable laml-dir as the file path of your LAML directory. For instance
         (define laml-dir "c:/users/kurt/laml/")

    2. Load laml-init.scm file from the laml directory by
         (load (string-append laml-dir "laml-init.scm"))

      This loads the fundamental setup file laml.scm, and as such lib/general.scm, the necessary Scheme compatility file, and - if requested in the your installation file configuration - your laml init file. The XHTML1.0 strict mirror is also loaded by laml-init.scm, and the LAML startup directory will be set to the LAML root directory.

    3. If necessary, relocate your position in the file system by with:
         (laml-cd  new-dir )
      where new-dir can be absolute, relative, or "..". This sets the LAML startup directory, from which all input files are read. The function laml-pwd is also helpful because returns the current LAML startup directory.

    4. Now process LAML files with the laml procedure, for instance:
         (laml "index")
      The laml procedure takes its input file from the startup directory, as set by the previous step.

    A separate guide for use of LAML from DrScheme exists.

    If possible, you can arrange that the first two steps are carried out in the init file of your Scheme system.

    Please also notice all the other LAML tools that can be activated from this level.

If specified in the configuration file, a laml init file - such as .laml from you home directory - can be used for your personal LAML customization purposes. The LAML init file is loaded as the last action in laml.scm. You can redefine stuff from laml.scm and general.scm, but not LAML style or tool stuff (which is loaded after laml.scm ).

Time Correction

LAML uses the time library in lib/time.scm to access time and date information, in part based on the LAML compatibility function current-time. It may be necessary to change the value of the constant time-zone-info in lib/time.scm. We also use (or misuse) this variable for the necessary Daylight Saving Time adjustment during the summer months.

The Scheme Elucidator

Elucidative Programming in Scheme is supported by a tool which we call the Scheme Elucidator. Elucidative programming is a variant of literate programming in which programs and internal documentation is presented in an Internet Browser. The Scheme Elucidator is one of the most substantial LAML-based pieces of software I have written.

The Scheme Elucidator is an integrated part the LAML distribution. With respect to installation and setup of the Scheme Elucidator see the Elucidator Installation page. In addition, elucidative documentation of the Elucidator tool is available from the www.cs.auc.dk web site. See also the Home Page of Elucidative Programming on the Aalborg University WWW site.

The LAML tutorial is represented as a set of elucidative programs.

Emacs support

As an integral part of this software package you will find special LAML support from the Emacs editor, including a LAML mode with both key bindings. If you followed the installation steps you should be able to use LAML from emacs. Many LAML command are available via the LAML menu, which will apear when you work on a Emacs buffer in LAML mode.

The following gives an overview of the most important, general LAML Emacs commands.

  • laml-process-current-buffer
    Start LAML asynchronously on the current buffer, say f.laml. This creates or overwrites the file f.html.
    In the original setup this command is bound to C-o.

  • laml-sync-process-current-buffer
    Start LAML synchronously on the current buffer, say f.laml. This creates or overwrites the file f.html.
    In the original setup this command is bound to C-x C-o.

  • laml-process-buffer
    Start LAML on particular buffer of your choice, say b. This typically creates the file b.html

  • embed
    Embed the currently selected substring or word into a LAML form. A word is selected implicitly by pointing at its first character. This command handles the necessary string splitting and string concatenation.

  • unembed
    Unembeds the currently selected form. This is the reverse command to embed. The form is selected by pointing at the start parenthesis or a character in the form name. This command unnests the form, joins neighboring strings, and gets rid of a possibly unnecessary string concatenation form.

  • split
    Splits a string in two parts and insert a surrounding concatenate form if desired

  • unsplit
    Joins neigboring strings to a single string and remove a possible surrounding concatenate form if it is redundant.

  • laml-mode
    Set the major mode of the current buffer to LAML mode.

  • laml-insert-template
    Insert a stored template. You are prompted for a particular one.

  • insert-laml-template
    An alias for laml-insert-template

  • nest
    Nest the current Lisp form into an extra form (a general lisp editing command)

  • unnest
    The opposite command to nest

The embed, unembed, split, and unsplit commands are important, because they help the LAML user to embed portions of a string into a Lisp form. Stated in a slightly different way, these commands alleviate the inconvenience caused by the string passing problem (the problem that occurs because all strings must be passed explicitly to LAML functions - this is the main point which in a significant way makes LAML different from the SGML family of mark up languages). The commands are controlled by the two Emacs Lisp variables laml-single-string-approach and smart-word-determination. Please see the LAML customization facility in Emacs (available through the LAML menu) if you want to change these.

Besides these, a variety of specialized template insertion commands are available. They all start with insert-. Use the Emacs completion facility to find out about these.

There also exists a number of more specific emacs command for the Elucidator, the Manual style, and for LENO (XML-in-LAML version). See the relevant manual pages for description of these.

In case you want to change the key bindings used by Emacs LAML mode, you will have to change these in the file emacs-support/laml-key-menu-bindings.el

Porting LAML to other Scheme Systems

In order to port the LAML software package to another Scheme system you will need to carry our some programming work. I have written a guide for people who want to port LAML to another Scheme system.

Known bugs and problems

  1. The Emacs stuff may cause conflicts with other Emacs packages. As pointed out by several people, all Emacs Lisp functions should have a 'laml-' prefix. This is a major work, which I postpone. Is there a program that makes such conversions? If not, it would be worthwhile to make one, perhaps...

  2. LAML program parameters are not supported when using the Scheme system SCM. (There is no inherent problems in doing so, however).

  3. The LAML XML/HTML parsers do not handle white space properly. This issue needs to be reconsidered from scratch in order to reach a good solution.

  4. The laml bat files on Windows NT4.0 do not work. On NT4.0 it does not find in which directory it is started, and it therefore fails to transfer this information to the Scheme process. As a consequence, all files are written into the laml directory instead of being written into the same directory as the LAML source file.

 

Kurt Nørmark
Aalborg University
normark@cs.auc.dk

Program Oriented Web Engineering - using LAML Generated: December 12, 2003, 15:59:13