LAML

This is the homepage of LAML Version 26.0 (April 17, 2005, 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 is OK if you have a good and permanent connection to the Internet, via which you can reach the LAML documentation.

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.

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.

Although Scheme is basically case insensitive, the LAML software does not rely on this property, and we recommend case sensitive reading. From LAML version 26 we assume that the Scheme reader is case sensitive. 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. Guile uses case sensitive reader per default. In MzScheme (read-case-sensitive #t) is used to obtain it. read-case-sensitive is called in the MzScheme compatibility file.

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...

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).

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 of 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 XHTML 1.0 transitional 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.

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.

The following gives an overview of the most important Emacs commands of general LAML relevance. All the mentioned keybindings belong to the so-called hygienic keybinding mode, which does not conflict with other Emacs keybindings. The orginal keybindings are shorter, but with a number of conflics. The choice between hygienic and original keybindings is done at LAML configuration time, in the file laml-config/configuration. Roughly speaking, the original keybindings omit the initial C-c.

• laml-process-current-buffer
  Start LAML asynchronously on the current buffer, say f.laml. This creates or overwrites the file f.html.
  In the hygienic setup this command is bound to C-c 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-c C-x C-o.

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

• tidy-laml-form
  Tidy up the LAML form under point. Breaks long strings relative to the value of the variable tidy-fill-column, fixes LAML forms with fix-laml-form, and takes care of indentation. If tidy-laml-form is applied multiple times at the same location, tidy-fill-column will be incremented for each application. When you are satisfied with the value of tidy-fill-column you should use tidy-laml-form-again instead of tidy-laml-form. tidy-laml-form-again does not change tidy-fill-column. Keybinding C-c C-x C-t and C-c C-x C-y respectively.

• 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. Keybinding C-c C-x C-e.

• 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. Keybinding: C-c C-r

• split
  Splits a string in two parts and insert a surrounding concatenate form if desired. Keybinding: C-c C-q.

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

• 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). Keybinding: C-c C-n.

• unnest
  The opposite command to nest. Keybinding: C-c C-m.

• open-laml-form
  Open a new laml form. Keybinding: C-c C-x C-l.

• insert-relative-file-path
  Insert a file path, which is relative to the current directory associated with the current buffer. This command is, for instance, useful whenever you make relative links from one web document to another.

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 one of the main points which in a significant way makes LAML different from other similar work).

There also exists a number of more specific emacs command for the Elucidator and LENO.

In case you want to change the key bindings used by Emacs LAML mode, you find most of them in the file emacs-support/laml-key-menu-bindings.el. The keybindings of LENO and the Scheme Elucidator are not in this file, however.