Generated: September 11, 2001, 10:23:30Copyright © 2000, Kurt NørmarkThe local LAML software home page

Reference Manual of the fundamental LAML setup library

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

Source file: laml.scm

The file laml.scm is the very first laml file to load. It contains a number of variable and functions which must be defined whenever LAML is used. It also contains a number of top level commands that activate the LAML tools. Some of the variables - the configuration variables - are defined via the configuration file in the laml-config directory. This file loads the scheme-system specific compatibility file and the general.scm file from the library. It is assumed that the value of the variable laml-dir is the full path of the LAML directory. laml-dir must be defined when this file is loaded, and it must be ending in a "/".

Table of Contents:
1. The configuration section.5. LAML contextual information.9. LAML home URL.
2. Other variables.6. Programmatic loading of laml files.10. Cosmetic welcome, ending and copyright functions.
3. Optional parameters in LAML software.7. Interactive tool activation.
4. Library, style and local dir loading.8. Language settings.

Alphabetic index:
bibtex(bibtex file-name)Parse the bibtex file, file-name, which is a bibtex file name without the bibtex extension.
computer-systemcomputer-systemThe machine on which I use LAML-based software.
copyright-clause(copyright-clause)Return an HTML comment with a copyright notice.
credits(credits system-dk system-eng)Return a credit message to Kurt Nørmark about system-dk (the Danish name) and system-eng (the English name).
end-laml(end-laml)This function is inteded to end an LAML file.
fake-startup-parameters(fake-startup-parameters source-file startup-dir)Fake the contextual startup parameters to a specific source file name and a specific startup directory.
full-source-path-with-extension(full-source-path-with-extension ext)Return the full path to the current source file name using the extension ext.
html-parse(html-parse in-file-name [out-file-name])Parse the HTML file file-name (a file name with or without extension) using the XML-based HTML parser for LAML.
html-pp(html-pp in-file-name [out-file-name single-lining indentation max-width])Pretty prints the HTML file or HTML parse tree in in-file-name and place the pretty printed result in out-file-name.
html-to-laml(html-to-laml in-file-name out-file-name)Convert the HTML file on in-file-name to an LAML file on out-file-name.
laml(laml file-name)Load and execute the LAML file on the file file-name (a string).
laml-absolute-url-prefixlaml-absolute-url-prefixThe URL prefix of the LAML software home page at Aalborg University's WWW server.
laml-canonical-command-line(laml-canonical-command-line)Return the contextual command line information passed to LAML upon activation.
laml-cd(laml-cd dir)Set the LAML startup directory to dir.
laml-home-url-prefix(laml-home-url-prefix extra-level . start-dir)Return a relative or absolute url prefix to the LAML home directory.
laml-librarylaml-libraryThe scheme library relative to laml-dir.
laml-load(laml-load full-file-path)Load the laml file in full-file-path after faking the start up parameters.
laml-load-variationlaml-load-variationA global variable which signals some kind of variations in the loading of an LAML style or library.
laml-ls(laml-ls)Returns a list of files and directories of the LAML startup directory (the current directory).
laml-platformlaml-platformThe platform on which LAML is in use.
laml-pwd(laml-pwd)Returns the working LAML directory.
laml-style(laml-style style-spec style-spec load-variation)An alias to the function style which loads a LAML style.
laml-versionlaml-versionA variable that refers to the version of LAML, bound at LAML installation time.
laml-welcome(laml-welcome)Initiating welcome and info text for interactive LAM tools.
language-preferencelanguage-preferenceA variable which determines which language to use in selected parts of the LAML software complex.
lib-load(lib-load file-name)Load file from the library determined by the variables laml-dir and laml-library.
local-load(local-load file-name)Load file from the startup directory.
operating-systemoperating-systemThe operating system on which LAML is in use.
optional-parameter(optional-parameter n optional-parameter-list [default-value])Return element n of optional-parameter-list.
scheme-libraryscheme-libraryAn alias of laml-library.
scheme-pp(scheme-pp in-file-name [out-file-name single-lining indentation max-width])Pretty prints the Scheme or Lisp file - including comments - in in-file-name and write the result to out-file-name.
scheme-pp-simple(scheme-pp-simple in-file-name [out-file-name single-lining indentation max-width])Pretty prints the Scheme or Lisp file - without comment preservation - in in-file-name and write the result to out-file-name.
scheme-systemscheme-systemWhich Scheme system to use.
schemedoc(schemedoc scheme-source-file [relative-destination-dir manual-title manual-author-info manual-abstract])Make documentation from scheme-source-file.
set-laml-source-file(set-laml-source-file file)Set the LAML source file name (without extension) to file.
set-laml-startup-directory(set-laml-startup-directory dir)Set the LAML startup directory to dir.
software-directorysoftware-directoryAn alias of laml-dir.
source-filename-without-extension(source-filename-without-extension . unused-parameter)If possible return the name of the LAML source file (without extension).
startup-directory(startup-directory . unused-parameter)Return the directory in which the Scheme system is started up.
style(style style-spec style-spec load-variation)Load an LAML style.
text-choice(text-choice danish english)Return either danish or english, depending on the value of the global variable language-preference.
the-librarythe-libraryFull path to the scheme library.
xml-parse(xml-parse in-file-name [out-file-name])Parse the XML file file-name (a file name with or without xml extension) using the XML parser for LAML.
xml-pp(xml-pp in-file-name [out-file-name single-lining indentation max-width])Pretty prints the XML file or XML parse tree in in-file-name and place the pretty printed result in out-file-name.

 

1.   THE CONFIGURATION SECTION.
The configuration section is meant to be addapted in each new LAML installation. This section contains a few fundamental variables. The variables are defined via the configuration file in the laml-config directory.


scheme-system



Form
scheme-system

Description
Which Scheme system to use. A symbol. Currently we support 'scm and 'mzscheme (and to some degree 'drscheme).


laml-platform



Form
laml-platform

Description
The platform on which LAML is in use.


operating-system



Form
operating-system

Description
The operating system on which LAML is in use.


laml-library



Form
laml-library

Description
The scheme library relative to laml-dir. A string. A single directory name (without ending slash). You can change this if you use an alternative or experimental LAML library.


laml-version



Form
laml-version

Description
A variable that refers to the version of LAML, bound at LAML installation time.

Returns
A string that contains the version number and a short description.


 

2.   OTHER VARIABLES.
This part of the laml.scm file contains some other fundamental functions and variables.


computer-system



Form
computer-system

Description
The machine on which I use LAML-based software. This variable is not used any place in the LAML software, so *you* can forget about. I use it in the setup files of the LENO and course-plan systems. The variable allows me to find out on which machine I am running. Files, on which I rely, may be placed different places on different machines. Possible values: cs-unix, home-pc, thinkpad


software-directory



Form
software-directory

Description
An alias of laml-dir. For backward compatibility. Some LAML applications change this variable to a more local directory.


scheme-library



Form
scheme-library

Description
An alias of laml-library. For backward compatibility


the-library



Form
the-library

Description
Full path to the scheme library. Normally the value of this variable is derived from laml-dir and laml-library. Ends in a slash.


laml-load-variation



Form
laml-load-variation

Description
A global variable which signals some kind of variations in the loading of an LAML style or library. If no load variation is present, the value of the variable will be #f. The interpretation of a non-false value is entirely up to a style or a library. The value of this variable is assigned by the style and laml-style form based on the last optional parameter of style or laml-style


 

3.   OPTIONAL PARAMETERS IN LAML SOFTWARE.
In LAML version 14 and earlier we have been rather sloppy with respect to the handling of optional parameters of Scheme functions. From version 15 we have introduced the following simple support of optional parameters. Given the funciton (lambda (r1 r2 . optional-parameters) ...) the function optional-parameter (see below) is able to extract optional parameter number n. Non-used optional parameter can either be passed as the #f value (false in Scheme) or not passed at all.


optional-parameter



Form
(optional-parameter n optional-parameter-list [default-value])

Description
Return element n of optional-parameter-list. The first element is number 1. In Scheme the optional parameters are captured as a list after the required parameters: (define f (x y . optional-parameter-list) ...). Please notice that if you pass optional parameter number i, the optional parameter 1, 2, i-1 must be passed explicitly. (This is a non-symmetric property of optional parameters - and a motivation to a better alternative, which is keyword parameters). If no optional third parameter - default-value - is given to the function optional-parameter the value #f counts as a non-passed optional parameter. It is assumed as a precondition that optional-parameter-list is a proper list.


 

4.   LIBRARY, STYLE AND LOCAL DIR LOADING.
The functions in this section loads LAML libraries and LAML styles.


lib-load



Form
(lib-load file-name)

Description
Load file from the library determined by the variables laml-dir and laml-library.


local-load



Form
(local-load file-name)

Description
Load file from the startup directory.


style



Form
(style style-spec style-spec load-variation)

Description
Load an LAML style.

Parameters
style-specThe name of the style to load. A style-spec is without extension. However, the style file must have the scm extension.
style-baseOptional: The directory which contains the style. If style-base is given it must be a directory (a slash terminated string) from which to load your style. If style-base is omitted, the style is loaded from styles subdirectory of the LAML directory.
load-variationOptional: A load-variation assigned to the global LAML variable laml-load-variation.

Example
 (style "simple" #f 'xyz-variation)

See also
also relevantlaml-load-variation    laml-style    


laml-style



Form
(laml-style style-spec style-spec load-variation)

Description
An alias to the function style which loads a LAML style. The function style is an HTML mirror function, and as such there is a name clash. Please use laml-style instead of style.

Parameters
style-specThe name of the style to load. A style-spec is without extension. However, the style file must have the scm extension.
style-baseOptional: The directory which contains the style. If style-base is given it must be a directory (a slash terminated string) from which to load your style. If style-base is omitted, the style is loaded from styles subdirectory of the LAML directory.
load-variationOptional: A load-variation assigned to the global LAML variable laml-load-variation.

Example
 (laml-style "simple" #f 'xyz-variation)

See also
also relevantstyle    laml-load-variation    


 

5.   LAML CONTEXTUAL INFORMATION.
The functions in this section deal with the necessary context information, which must be passed to Scheme when we use LAML.


source-filename-without-extension



Form
(source-filename-without-extension . unused-parameter)

Description
If possible return the name of the LAML source file (without extension). This is only possible if the information somehow is passed to the Scheme execuctable. In cases where it is not possible to know the source file name, return #f. Notice: The parameter is not used, and should be avoided. In order to be backward compatible, however, we allow a dummy parameter.


startup-directory



Form
(startup-directory . unused-parameter)

Description
Return the directory in which the Scheme system is started up. If this information is not present, return #f. Notice: The parameter is not used, and should be avoided. In order to be backward compatible, however, we allow a dummy parameter.


laml-canonical-command-line



Form
(laml-canonical-command-line)

Description
Return the contextual command line information passed to LAML upon activation. Returns a list of lenght three, or #f if no command line activation exists. The first element must be the symbol laml. Element number two must be the laml source file name (without extension and initial path). Element number three must be a slash terminated directory in which the source file resides. This function must be redefined in the scheme-system dependent compatibility file.


fake-startup-parameters



Form
(fake-startup-parameters source-file startup-dir)

Description
Fake the contextual startup parameters to a specific source file name and a specific startup directory. Both of the parameters must be strings, or the boolean value #f (in case the informations are unknown). This function is useful for programmatic startup of LAML. This function must be redefined in the scheme-system dependent compatibility file


set-laml-startup-directory



Form
(set-laml-startup-directory dir)

Description
Set the LAML startup directory to dir. Dir can be a full path, "..", or a directory relative to the current laml startup directory. This is specialized call to fake-startup-parameters with only directory information.


laml-cd



Form
(laml-cd dir)

Description
Set the LAML startup directory to dir. Dir can be a full path, "..", or a directory relative to the current laml startup directory. A convenient and easy to remember alias to set-laml-startup-directory.


laml-pwd



Form
(laml-pwd)

Description
Returns the working LAML directory. Similar to the UNIX command pwd. An alias of the function startup-directory.


laml-ls



Form
(laml-ls)

Description
Returns a list of files and directories of the LAML startup directory (the current directory). Similar to the UNIX command ls


set-laml-source-file



Form
(set-laml-source-file file)

Description
Set the LAML source file name (without extension) to file. This is specialized call to fake-startup-parameters with only source file information.


full-source-path-with-extension



Form
(full-source-path-with-extension ext)

Description
Return the full path to the current source file name using the extension ext. This function can be used conveniently to name the typical file for LAML to HTML transformations.


 

6.   PROGRAMMATIC LOADING OF LAML FILES.
Loading an laml file involes the setting of two pieces of context: The name of of the source file and the startup directory. The function laml-load sets these information and loads a file.


laml-load



Form
(laml-load full-file-path)

Description
Load the laml file in full-file-path after faking the start up parameters. full-file-path must be the full path of a laml file, including the laml extension.


laml



Form
(laml file-name)

Description
Load and execute the LAML file on the file file-name (a string). The parameter file-name can be a full path with or without the file extension '.laml'. Alternatively, file-name can be a file name with or without the '.laml' extension, in which case we load the file from the laml starup directory. This function is a flexible and versatile alternative to laml-load.


 

7.   INTERACTIVE TOOL ACTIVATION.
The procedures in this section activate laml tools. It is recommended that you activate the commands from an interactive LAML (Scheme) prompt. From emacs issue the editor command run-laml-interactively .

All the commands below work relative to the LAML working directory, which is changed by the procedure laml-cd . Use the command laml-pwd to check the LAML working directory.


schemedoc



Form
(schemedoc scheme-source-file [relative-destination-dir manual-title manual-author-info manual-abstract])

Description
Make documentation from scheme-source-file. This function is meant to be called from a Scheme interpreter. You must first set lam-dir appropriately, load laml.scm from your laml directory, and finally set the start directory via the procedure laml-cd.

Parameters
scheme-source-fileThe source file in the current directory to be processed.
relative-destination-dirThe relative directory in which to place the resulting html file. The directory must exist on beforehand. The default is the current directory.
manual-titleThe title of the manual. The default is 'Manual of scheme-source-file'.
manual-author-infoA list of name and affiliation of the author. The default value is no author.
manual-abstractThe abstract of the manual. The default value is the 'four semicolon' extract abstract from the initial portion of the source file.


xml-parse



Form
(xml-parse in-file-name [out-file-name])

Description
Parse the XML file file-name (a file name with or without xml extension) using the XML parser for LAML. Writes the parse tree on the optional out-file-name.

Parameters
in-file-nameThe name of an XML file, with or without the xml file extension.
out-file-nameThe name of the file on which the parse tree is written. Defaults to the proper name of the xml file with and added lsp extension.


html-parse



Form
(html-parse in-file-name [out-file-name])

Description
Parse the HTML file file-name (a file name with or without extension) using the XML-based HTML parser for LAML. Writes the parse tree on the optional out-file-name.

Parameters
in-file-nameThe name of an HTML file, with or without the html file extension.
out-file-nameThe name of the file on which the parse tree is written. Defaults to the proper name of the html file with and added lsp extension.


xml-pp



Form
(xml-pp in-file-name [out-file-name single-lining indentation max-width])

Description
Pretty prints the XML file or XML parse tree in in-file-name and place the pretty printed result in out-file-name. The input is assumed to be a parse tree if and only if the extension is lsp. A XML file is parsed before pretty printing via use of the simple and non-complete, non-validating XML parser from the LAML software package. The optional file out-file-name defaults to in-file-name. In this case the original input file is overwritten. If you care for your input file, it is strongly recommended that your output file does not overwrite your input file!

Parameters
in-file-nameThe file to pretty print
out-file-nameThe file on which to write the pretty printed result. Default value in-file-name.
single-liningA boolean variable that controls the line breaking; False means break consistently all forms. Default #t.
indentationThe increment of indentation. Default value 3.
max-widthThe preferred maximum line width in the pretty printed file. Default value 80.


html-pp



Form
(html-pp in-file-name [out-file-name single-lining indentation max-width])

Description
Pretty prints the HTML file or HTML parse tree in in-file-name and place the pretty printed result in out-file-name. The input is assumed to be a parse tree if and only if the extension is lsp. A HTML file is parsed before pretty printing via use of the non-validating HTML parser from the LAML software package. The optional file out-file-name defaults to in-file-name. In this case the original input file is overwritten. If you care for your input file, it is strongly recommended that your output file does not overwrite your input file!

Parameters
in-file-nameThe file to pretty print
out-file-nameThe file on which to write the pretty printed result. Default value in-file-name.
single-liningA boolean variable that controls the line breaking; False means break consistently all forms. Default #t.
indentationThe increment of indentation. Default value 3.
max-widthThe preferred maximum line width in the pretty printed file. Default value 80.


bibtex



Form
(bibtex file-name)

Description
Parse the bibtex file, file-name, which is a bibtex file name without the bibtex extension. Put the parsed result in file-name.lsp. In addition, deliver the result in the variable parse-result. Finally, present the parsed file as HTML in file-name.html.


scheme-pp



Form
(scheme-pp in-file-name [out-file-name single-lining indentation max-width])

Description
Pretty prints the Scheme or Lisp file - including comments - in in-file-name and write the result to out-file-name. Conventional comments (prefixed with semicolon) are converted with the Schemedoc procedure lexical-to-syntactical-comments! before the pretty printing. In case you don't care about comments, you should probably use lisp-pp instead. The optional file out-file-name defaults to in-file-name. In this case the original input file is overwritten. It is strongly recommended that your output file does not overwrite your input file! This function assumes that the general LAML library is loaded in advance.

Parameters
in-file-nameThe file to pretty print
out-file-nameThe file on which to write the pretty printed result. Default value in-file-name.
single-liningA boolean variable that controls the line breaking; False means break consistently all forms. Default #t.
indentationThe increment of indentation. Default value 3.
max-widthThe preferred maximum line width in the pretty printed file. Default value 80.

See also
similar functionscheme-pp-simple    


scheme-pp-simple



Form
(scheme-pp-simple in-file-name [out-file-name single-lining indentation max-width])

Description
Pretty prints the Scheme or Lisp file - without comment preservation - in in-file-name and write the result to out-file-name. The pretty printing is simple because the conventional semicolon comments are lost. The similar function scheme-pp preserves the comments during pretty printing. The optional file out-file-name defaults to in-file-name. In this case the original input file is overwritten. It is strongly recommended that your output file does not overwrite your input file! This function assumes that the general LAML library is loaded in advance.

Parameters
in-file-nameThe file to pretty print
out-file-nameThe file on which to write the pretty printed result. Default value in-file-name.
single-liningA boolean variable that controls the line breaking; False means break consistently all forms. Default #t.
indentationThe increment of indentation. Default value 3.
max-widthThe preferred maximum line width in the pretty printed file. Default value 80.

See also
similar functionscheme-pp    


html-to-laml



Form
(html-to-laml in-file-name out-file-name)

Description
Convert the HTML file on in-file-name to an LAML file on out-file-name. The conversion is done by parsing in-file-name, transforming the parse tree to LAML, and by pretty printing the resulting LAML program.


 

8.   LANGUAGE SETTINGS.



language-preference



Form
language-preference

Description
A variable which determines which language to use in selected parts of the LAML software complex. The value of the variale must be a symbol. Currently we only support 'danish and 'english. 'Danish is the default value.


text-choice



Form
(text-choice danish english)

Description
Return either danish or english, depending on the value of the global variable language-preference.


 

9.   LAML HOME URL.



laml-absolute-url-prefix



Form
laml-absolute-url-prefix

Description
The URL prefix of the LAML software home page at Aalborg University's WWW server.


laml-home-url-prefix



Form
(laml-home-url-prefix extra-level . start-dir)

Description
Return a relative or absolute url prefix to the LAML home directory. If possible a relative URL prefix is returned. The parameter extra-level is an extra level to add; As an example, extra-level should be 1 in case HTML files are organized in a sub-directory. Normally, extra-level is 0 (zero). The parameter start-dir is optional. It defaults to the value of (startup-directory).


 

10.   COSMETIC WELCOME, ENDING AND COPYRIGHT FUNCTIONS.



laml-welcome



Form
(laml-welcome)

Description
Initiating welcome and info text for interactive LAM tools. As of now this is entirely cosmetic.


end-laml



Form
(end-laml)

Description
This function is inteded to end an LAML file. As of now this is entirely cosmetic.


copyright-clause



Form
(copyright-clause)

Description
Return an HTML comment with a copyright notice. It is also possible to return an empty string. The value of this function is used in the generic page function called page-1. Redefine this function for personal customization.


credits



Form
(credits system-dk system-eng)

Description
Return a credit message to Kurt Nørmark about system-dk (the Danish name) and system-eng (the English name).


Generated: September 11, 2001, 10:23:31
This documentation has been extracted automatically from the Scheme source file by means of the Schemedoc tool