Using Lisp as a Markup Language
The LAML approach

Kurt NÝrmark ©
Department of Computer Science
Aalborg University
Denmark


Abstract

Index References Contents
These slides and the associated comments reflect my talk on the LAML approach. The talk is given at the Lisp User Group Meeting in Amsterdam, June 1999.

Background
Slide Note Contents Index
References 
I start with my original need for Lisp in the domain of Internet programming. This was not authoring of static WWW pages, but CGI programming in a better language than Perl

I have used Lisp for many different purposes since the mid-eighties

I wanted to find out if Lisp could be used for server side CGI programming

  • Languages which are often used for CGI programming:

    • Perl - a string manipulation language

    • C - a system programming language

    • Shell Script - hardly a programming language at all

It is quite natural to consider better alternatives

CGI programming is not necessarily imperative programming

CGI Programming
Slide Note Contents Index
References 
In order to explore the nature of CGI programming we here take a closer look at the overall CGI scheme

Figure. The interaction between a browser and a CGI program

The functional programming paradigm fits well with the CGI programming model

The state of the system can be carried from one WWW page to the other by functional means

CGI Programming with Program State
Slide Note Contents Index
References 
In many CGI programs we need to store a 'program state'. Often, data is transferred to and from a database. We modify the previous picture in include this observation.

Figure. The interaction between a browser and a CGI program, which uses a database for storing the program state

Many real world applications need to maintain program state which changes as a function of time

This calls for imperative programming techniques

CGI Programming in Scheme
Slide Note Contents Index
References 
We now return to CGI programming in Scheme.

CGI programming is mainly functional programming

  • Our support of CGI Programming in Scheme

    • A simple library to deal with the Common Gateway Interface

    • An ad hoc library to support the generation of HTML output

    • Other libraries, for instance dealing with time, colors, and reading the textual content of a file.

From a practical point of view Scheme is a realistic language for CGI programming

This conclusion is drawn from a variety of different examples, which we have implemented. Most of the examples have been used to support various aspects of 'Open University' students located off campus.

References

Programming static WWW pages in Scheme
Slide Note Contents Index
References 
We will now return to the main topic of this talk, namely programming of ordinary, static WWW pages.

Given the HTML Scheme library it became attractive to write plain and static WWW pages in Scheme too

  • The main advantages compared to an HTML solution:

    • Abstractions from HTML details

    • Automation of routine tasks

We will return to both abstraction and automation later in the presentation.

The step from HTML to a Scheme basis is similar to the expected transition from HTML to XML (abstraction only)

This observation is in relation to abstraction. XML supports 'your own' domain-specific tags. However, in relation to automation of routine tasks, XML has nothing to offer.

LAML: Lisp Abstracted Markup Language
Slide Note Contents Index
References 
We now introduce LAML, which basically is Scheme with access to libraries which mirror HTML. In addition, we support a number of functions which in our experience are very helpful during a typical WWW authoring process. Some of these functions are organized in document styles.

  • LAML fundamentals:

    • The Scheme programming language itself

    • A mirror of HTML in Scheme

    • A number of useful libraries

    • A number of LAML document styles

LAML = Scheme + The HTML mirror + The LAML document styles

An LAML Document Example
Slide Note Contents Index
References 
It is now time to study a concrete example of an LAML document

Program: We see a simple WWW pages written in LAML. The first interesting thing is the function generic-page-1, which generates all the html, body and title stuff, which is found on any WWW pages written in HTML. The con-par function is just a string-append variant, which concatenates paragraphs of text. The functions em and b mirror the similar HTML tags. The table-1 function is one of our convenient abstractions of HTML tables. We make a three column table with given widths, and a border of 2 pixels. The table proper is defined by a list of table rows. Each row is itself a list. The make-color function makes a color from red, green, blue components.
(load (string-append laml-dir "laml.scm"))

(laml-style "simple")

(generic-page-1
  "A simple page"
  (con-par 
     "This page demonstrates a few of the functions in the HTML library."

     (em (con-space "This paragraph has been emphasized by means of the" 
         (b "em") "function."))

     "Let us also show a simple table, which is one of the real convenient 
      elements in LAML:"

     (table-1
       2 ; border 
       (list 100 200 100)
       (list red green blue)
       (list
         (list "Here" "is" "some")
         (list "tabular" "text" "")))

     (b "This ends this simple page"))

     
  (make-color 255 255 191) black blue blue
)

(end-laml)

References

Syntactic LAML issues
Slide Note Contents Index
References 
The example from above raises a number of relevant syntactic issues, which we will discuss here and on the next page

Which parameter profile is used for the HTML mirror functions?

We may want to mirror the HTML tags as accurate as possible.

Syntax: We show the syntax of a tag application f on some text. The tag application passes the attributes a1 and a2 with given values

<f a1=v1 a2=v2> Some text. More text</f>

Figure. A table shown four possible parameter profiles of HTML mirror functions in Scheme. We use the third possibility in our libraries and in our examples

Reference

Semi constant strings in Scheme
Slide Note Contents Index
References 
When we compare an SGML family language with a Lisp family programming language we find some major syntactical differences. The observation about semi-constant strings is one of the most important

It would be convenient to support a semi constant string concept analogous to quasi quoted lists in Lisp

Program: This is a typical HTML/XML fragment
  <point> 
    A text with a 
    <a href="subsection/sec1.html">link</a> 
    to a <b>subsection</b>
  </point>

Program: Here we attempt to use a semi-constant string in Scheme. This does actually not make sense.
  (point
    "A text with a 
     (a "link" 'href "subsection/sec.html")
     to a (b "subsection")
    ")

Program: Here we see the solution we use in all our examples. This uses a plain Scheme programming approach.
  (point
    (string-append
      "A text with a " 
       (a "link" 'href "subsection/sec.html")
      " to a " (b "subsection")))

We have dropped the idea of supporting semi-constant strings in Scheme

Instead we go for distinguished editor support of the 'string-append' forms

Abstractions in LAML
Slide Note Contents Index
References 
We now return to one of the main points of the talk, namely how to take advantage of abstraction in an LAML document. Notices that similar things can be done in XML.

A powerful abstraction mechanism is extremely useful for the professional WWW author

In that respect WWW authoring is analogous to program development

Program: A complete LAML WWW page. We have introduced a number of 'ad hoc' abstractions, the implementation of which is shown below.
(load (string-append laml-dir "laml.scm"))
(style "simple")
(load (string-append (startup-directory scheme-system) "functions.scm"))

(generic-page-1
  "Demonstration of abstractions"
  (con
    (standard-intro "My FAQ")
    (ul 
     (map present-faq-entry
       (list
          (faq-entry  'teacher
            "What is Lisp"
            "Lisp is a list processing language...")

          (faq-entry  'student
            "What is LAML"
            "LAML is Scheme in which HTML is mirrored...")

          (faq-entry  'student
            "What is the main differences between Scheme and Lisp"
            "Scheme is a relatively small, but powerful Lisp dialect...")
        )))
    (standard-signature)
  )
  white black blue blue
)

Reference

Program: The implementation of the abstractions.
includes/functions.scm

The developed LAML document styles represent sets of domain specific abstractions

URL abstraction
Slide Note Contents Index
References 
We will here mention a very useful area of abstraction, namely the possibility to abstracts from part of the details in an URL

By abstracting from certain details in an URL it becomes possible to redirect a set of URLs systematically via redefinition of a single Scheme function

  • The URL of this slide page:

    • http://www.cs.auc.dk/~normark/scheme/slides/lugm-99-amsterdam/html/lugm99-slide-url-abstractions.html

  • A possible abstraction of this URL:

    • (laml-root-url lugm-slides  (slide-url 'lugm99 'url-abstractions))

We have used this technique to 'switch' all addresses in a large material from an Internet location to a location on a CD

Overview of LAML styles
Slide Note Contents Index
References 
An LAML style represents a collection of related abstractions, which supports authoring of documents in a particular domain. This page gives an overview of existing document styles in LAML

During the LAML project we have developed a number of useful document styles

  • LAML document styles:

    • A manual style for documentation of programmatic library and tool interfaces

    • A lecture note style for annotated transparencies (slides)

    • A questionnaire document style

    • An elucidative programming style for internal documentation of Scheme programs

Example of the manual document style
Slide Note Contents Index
References 
The manual styles is oriented towards documentation of the external and programmatic aspect of a Scheme program

The manual style has been used to document the LAML software package via a tool, which extracts particular doc comments from a Scheme program

Program: This shows an excerpt of a typical manual style LAML document. Actually, the excerpt is taken from the manual which document the manual facility itself. This is a little circular, but quite realistic. Using the nearby cross reference you can see the resulting WWW page
; Top level functions

(manual-section
  (section-title "Top level functions")
  (section-body  
     "The important top level functions are manual-page and manual-section.
      These are the most important functions from a manual writer's perspective."))

(manual-page   
  'manual-page
  (title "manual-page")
  (form '(manual-page id . elements))
  (description "Defines a manual entry.")
  (parameters
    (parameter  "id" "A symbol identifying the manual page")
    (parameter  "elements" "Zero, one or more title, form, pre-condition,
                           description, parameters, example, or misc elements")
  )
)

(manual-page   
 'manual-section
 (title "manual-section")
 (form '(manual-section . element))
 (description "Defines a new section of a manual.
               The only forms allowed within a manual section are manual-title
               and manual-body")
 (parameters
   (parameter  "elements" "a list of manual-title and manual-body forms")
 )
)

; End top level functions

Reference

Example of the lecture note document style
Slide Note Contents Index
References 
On this page we show an example of the most substantial LAML document style developed to date. It is called LENO: A lecture note style. The slides you are looking at right now are written in LENO. Therefore we show the underlying LENO source of this page to illustrate our approach.

These slides are written in LAML by means of the lecture note style

Program: This is the LAML expression which generates the current slide. You can easily recognize the point clauses above and below. The source-program clause inserts the large middle LAML document excerpt.
(note-page 'leno-ex
  (title "Example of the lecture note document style"
         "On this page we show an example of the most substantial
          LAML document style developed to date. It is called LENO:
          A lecture note style. The slides you are looking at right
          now are written in LENO. Therefore we show the underlying LENO
          source of this page to illustrate our approach."
  )

    (point  
     "These slides are written in LAML by means of the lecture note style"
     ""
    )

    (source-program
     "lugm-99.laml"
     (list "(note-page 'leno-ex" demo-end-mark)
     (list 
       (list "note-page" "" level-1-color 'bold)

       (list "title" "" level-2-color 'bold)
       (list point-form "" level-2-color 'bold 2)
       (list "source-program" "" level-2-color 'bold)
       (list index-word-form "" level-2-color 'bold)
     )
     (list 'slide-inline 'book-inline)
     "This is the LAML expression which generates the current slide. 
      You can easily recognize the point clauses above and below. The
      source-program clause inserts the large middle LAML document excerpt."
    )

    (point  
     "The program excerpt above is taken directly from the LAML source
      of these slides"
     ""
    )

  (index-words  "LENO" "Lecture note style (example of)")

) ; end leno-ex

The program excerpt above is taken directly from the LAML source of these slides

Example of the Elucidator document style
Slide Note Contents Index
References 
As the last LAML document style we take a look at the Scheme Elucidator style.

The elucidator document styles support a variant of literate programming for Scheme
in which we document the internal aspects of a program

References

  • Characteristics of the Scheme Elucidator:

    • The documentation and the program are shown in a two column layout with lots of links in between them

    • The documentation can either be defined using a simple, specialized markup language or via LAML expressions

    • The program source files are not affected by our documentation efforts

    • The Elucidator is language dependent

    • Most of the functionality of the Elucidator is replicated in Emacs, such that it is convenient to document a program during the process of program development

Automation with LAML
Slide Note Contents Index
References 
We now turn to the other main point of the LAML approach. This is the possibility to automate routine tasks in the authoring process via programmed solutions.

Having a programming language available 'anytime and anywhere' makes it possible to automate a variety of tasks, which otherwise should be carried out manually

  • Examples of LAML 'automations':

    • Insertion of quotations from external files

    • Checking the validity of links to some external nodes

In many practical situations 'abstraction' and 'automation' go hand in hand

Non-trivial 'automations' can be considered as LAML-based tools

Insertion of quotations from external files
Slide Note Contents Index
References 
Here we illustrate how to insert excerpts from external files into a note page (a slide). We have used this facility several times in this set of slides already presented

Automatic and programmed insertion of excerpts from external material is extremely useful in non-trivial documents

Superimposition of decorations (fonts and colors) makes it possible to focus the readers attention

Program: The application of the Scheme functions which returns a selected part of an external file
  (read-text-file-between-marks
    file-path
    mark)

Program: A variant of the function shown above which includes the marks in the extracted text string
  (read-text-file-including-marks
    file-name
    start-mark end-mark)

Program: Additional superimposition of colors and fonts, as specified by font-and-color-specification
  (colorize-substrings
    (read-text-file-between-marks
      file-path
      mark)
    font-and-color-specification)

We use these facilities a lot in course materials in the area of programming

An example of an LAML tool: SchemeDoc
Slide Note Contents Index
References 
We illustrate the ideal of an LAML with the SchemeDoc tool. This tool is inspired from JavaDoc and similar tools.

Problem: Extract selected comments from a Scheme program source file in order to produce external documentation of a programmatic interface

Solution: An LAML-based tool which interfaces to the Manual document style

References

Figure. This figure illustrates the process implemented by the SchemeDoc tool. The main idea is to translate the lexical Lisp comments to syntactic elements. Given this, it is easy to parse the translated program and to extract the relevant comments

An Emacs-based LAML environment
Slide Note Contents Index
References 
We here briefly discuss an LAML environment in which the Emacs text editor plays an important role

It may be a problem for many WWW authors to write documents using Lisp syntax

An environment with good editor support can alleviate some of these problems

  • LAML support via Emacs:

    • Scheme processing an LAML file via a single keystroke

    • Editor support which compensates for the lack of semi-constant strings

    • Special support of individual LAML document styles:

      • Advanced template support of all LENO source forms

      • Advanced support of elucidative programming

References

Conclusions: The LAML approach
Slide Note Contents Index
References 
An finally the conclusions based on or LAML work until now

Lisp can be used successfully as a markup language

There is a tradeoff between 'pains' (using Lisp syntax and handling errors) and 'gains' (abstraction and automation)

It would be interesting to produce HTML counterparts in Scheme directly from SGML Document Type Definitions

Homogeneous syntactic conventions for all future LAML document styles should be considered

 

I write all my WWW pages in LAML

Via definitions of appropriate document styles my own productivity is increasing


Collected references
Contents Index
Library overview
The HTML library
The CGI library
The raw HTML version of the page
The interpreted HTML version of the page
A more fundamental HTML library
The resulting HTML page
The resulting manual page
Example of the Elucidator's textual documentation format
The Elucidator documentation (large example)
An Elucidator demo (small example)
The Scheme source file
The LAML file which binds the processing together
An example of SchemeDoc generated documentation
Overview of the Elucidator editor support
Semi-constant strings (earlier slide)


Source files in this lecture
Contents Index References
../../examples/simple-pages/simple-page-1.laml
includes/abstraction-demo.laml
includes/functions.scm
../../styles/manual/man/manual.laml
lugm-99.laml
includes/quote-1
includes/quote-3
includes/quote-2

 

Using Lisp as a Markup Language
The LAML approach

Course home     Author home     About producing this web     Previous lecture (top)     Next lecture (top)     Previous lecture (bund)     Next lecture (bund)     
Generated: March 26, 2002, 12:32:16