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 | The Scheme system on which LAML depends (a symbol).
Possible values are: mzscheme, scm, guile, drscheme.
The value is frozen by the LAML configuration program.
|
|
laml-platform |
Form | laml-platform |
Description | The platform on which LAML is in use (a symbol).
Possible values are: windows, unix, mac. mac is not yet in use.
The value is frozen by the LAML configuration program.
|
|
operating-system |
Form | operating-system |
Description | The operating system on which LAML is in use (a symbol).
Possible values on the windows platform: win98, win95, nt40, win2000.
Possible values on the unix platform: solaris-6, solaris-7, or linux.
The value is frozen by the LAML configuration program.
|
|
laml-library |
Form | laml-library |
Description | The scheme library relative to laml-dir. A string.
A single directory name (without ending slash).
The value is frozen by the LAML configuration program.
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 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 function (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. |
|
3 Library, style, tool, and local dir loading. |
The functions in this section loads LAML libraries and LAML styles. |
|
lib-load |
Form | (lib-load suffix-path) |
Description | Load file from the LAML library directory. |
Parameters | suffix-path | The part of the library file name relative to the LAML library directory, including file extension. |
|
laml-tool-load |
Form | (laml-tool-load suffix-path) |
Description | Load a file from the LAML tool directory. |
Parameters | suffix-path | The part of the tool file name relative to the LAML tool directory, including file extension. |
|
local-load |
Form | (local-load suffix-path) |
Description | Load file from the startup directory. |
Parameters | suffix-path | The part of the file name relative to the LAML startup directory, including file extension. |
See also | related function | startup-directory |
|
laml-style |
Form | (laml-style style-spec [style-base load-variation]) |
Description | Load an LAML style. |
Parameters | style-spec | The name of the style to load. A style-spec is without extension. However, the style file must have the scm extension. |
style-base: | The directory which contains the style. If style-base is given it must be a full path 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-variation: | A load-variation assigned to the global LAML variable laml-load-variation. |
Example | (laml-style "manual" "manual/") |
Example | (laml-style "simple" #f 'xyz-variation) |
|
4 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. |
See also | similar function | full-source-path-with-extension |
|
startup-directory |
Form | (startup-directory . unused-parameter) |
Description | Return the directory in which LAML is started up.
If this information is not available 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-program-parameters |
Form | (laml-program-parameters) |
Description | Return the list of program parameters passed to an activation of LAML.
If no program parameters are passed, the empty list is returnd.
|
|
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 [program-parameter-list]) |
Description | Fake the contextual startup parameters to a specific source file name and a specific startup directory.
As an optional parameter, a list of program parameters can be passed.
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.
|
|
in-startup-directory |
Form | (in-startup-directory suffix) |
Description | Return a (full) path relative to the current startup-directory. |
See also | relevant function | startup-directory |
|
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.
|
|
set-laml-program-parameters |
Form | (set-laml-program-parameters program-parameters) |
Description | Set the LAML program parameters.
This is specialized call to fake-startup-parameters with only program parameters
|
|
full-source-path-with-extension |
Form | (full-source-path-with-extension ext) |
Description | Return the full path to the current source file name in the startup directory, using the extension ext.
This function can be used conveniently to name the typical file for LAML to HTML transformations. |
See also | similar function | source-filename-without-extension |
|
5 Programmatic loading of laml files. |
Loading a LAML file invovles 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 |
Form | (laml file-name . program-parameters) |
Description | Load and execute the LAML file on the file file-name (a string).
This procedure is a flexible and versatile alternative to laml-load. |
Parameters | file-name | A file-name, with or without extension. The extension 'laml' will be added if not supplied. Takes file-name from the startup-directory. Can also be a full path. |
program-parameters | A list of program parameters |
See also | useful function | laml-program-parameters |
Note | Please notice that this procedure will not work in case you use directory or file names with dots ('.'). |
|
laml-load |
Form | (laml-load full-file-path . optional-parameter-list) |
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.
This function is used by the function laml, which is recommended for most users. |
See also | similar function | laml |
|
6 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 carry out 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 find out about 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-file | The source file in the current directory to be processed. |
relative-destination-dir | The relative directory in which to place the resulting html file. The directory must exist on beforehand. The default is the current directory. Another way to get the default is to pass a the empty string. |
manual-title | The title of the manual. The default is 'Manual of scheme-source-file'. |
manual-author-info | A list of name and affiliation of the author. The default value is no author. |
manual-abstract | The abstract of the manual. The default value is the 'four semicolon' extract abstract from the initial portion of the source file. |
See also | Further info | LAML Tutorial section |
|
xml-dtd-manual |
Form | (xml-dtd-manual dtd-path [target-path]) |
Description | Generate a LAML manual (in SchemeDoc style) of an XML DTD.
This procedure reads the parsed dtd file (from a file with extension lsp) and generates an HTML file that represents the manual. |
Precondition | It is assumed that the DTD file already is parsed, and that the parsed DTD file is located side by side the DTD source file. It is also assumed that lib/xml-in-laml/xml-in-laml.scm is already loaded. |
Parameters | dtd-path | the path to the dtd file, without any file extension. |
target-path | the path in which to write the manual target file. Defaults to the startup directory. |
Example | (dtd-manual "xhtml10-transitional") |
See also | preparatory function | xml-dtd-parse |
Note | It is recommended that the XHTML1.0 transitional mirror is loaded before use of this procedure. The precondition and the recommendation is fulfilled when used via M-x run-laml-interactively in Emacs. |
|
xml-dtd-parse |
Form | (xml-dtd-parse dtd-file-name) |
Description | Parse the XML DTD on dtd-file-name. If the input file is f, the parsed file will be
located in f.lsp. The parsed DTD is represented as a Scheme list structure. |
Parameters | dtd-file-name | The name of the XML DTD file name in the startup directory. Without any extension. |
Note | As a side-effect, this procedure defines the variables element-list, attribute-list, and entity-list. |
|
generate-xml-mirror |
Form | (generate-xml-mirror parsed-dtd-file-name language-name) |
Description | Generate a mirror of an XML language in LAML and Scheme. This includes the generation of finite state automata for
XML validation purposes. If the parsed XML DTD file is named f.lsp, the generated mirror will be located in f.scm. |
Parameters | parsed-dtd-file-name | The name of the parsed XML DTD file in the startup directory. Without extension. |
language-name | The name allocated to the new XML language in LAML. A symbol of your choice. |
See also | preparatory procedure | xml-dtd-parse |
Note | After the generation of the mirror you can move the Scheme mirror file (with extension scm) to a directory of your choice. |
|
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-name | The name of an XML file, with or without the xml file extension. |
out-file-name | The 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-name | The name of an HTML file, with or without the html file extension. |
out-file-name | The 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-name | The file to pretty print |
out-file-name | The file on which to write the pretty printed result. Default value in-file-name. |
single-lining | A boolean variable that controls the line breaking; False means break consistently all forms. Default #t. |
indentation | The increment of indentation. Default value 3. |
max-width | The preferred maximum line width in the pretty printed file. Default value 80. |
See also | Similar function | pretty-render-to-output-port |
Similar function | pretty-xml-render |
Note | The pretty printing done by this function is superseded by the LAML AST pretty printing, as implemented by pretty-render-to-output-port and pretty-xml-render. |
|
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-name | The file to pretty print |
out-file-name | The file on which to write the pretty printed result. Default value in-file-name. |
single-lining | A boolean variable that controls the line breaking; False means break consistently all forms. Default #t. |
indentation | The increment of indentation. Default value 3. |
max-width | The preferred maximum line width in the pretty printed file. Default value 80. |
See also | Similar function | pretty-render-to-output-port |
Similar function | pretty-xml-render |
Note | The pretty printing done by this function is superseded by the LAML AST pretty printing, as implemented by pretty-render-to-output-port and pretty-xml-render. |
|
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-name | The file to pretty print |
out-file-name | The file on which to write the pretty printed result. Default value in-file-name. |
single-lining | A boolean variable that controls the line breaking; False means break consistently all forms. Default #t. |
indentation | The increment of indentation. Default value 3. |
max-width | The preferred maximum line width in the pretty printed file. Default value 80. |
See also | similar function | scheme-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-name | The file to pretty print |
out-file-name | The file on which to write the pretty printed result. Default value in-file-name. |
single-lining | A boolean variable that controls the line breaking; False means break consistently all forms. Default #t. |
indentation | The increment of indentation. Default value 3. |
max-width | The preferred maximum line width in the pretty printed file. Default value 80. |
See also | similar function | scheme-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. |
Note | Exprimental |
|
leno-xml |
Form | (leno-xml leno-xml-file) |
Description | Process a LENO xml file. |
Note | Experimental |
|
7 Language settings. |
|
|
language-preference |
Form | language-preference |
Description | A variable which determines which language to use in selected parts of the LAML software.
The value of the variable must be a symbol.
Currently we only support danish and english. english 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.
|
|
8 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.
Latest distributed version.
|
|
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 (an integer).
As an example, extra-level should be 1 in case HTML files are organized in a sub-directory.
Normally, extra-level is 0 (zero).
If a boolean extra-level is passed we explicitly ask for an absolute URL result.
If a string extra-level is passed, we use this string as a relative path to the home.
The parameter start-dir is optional. It defaults to the value of (startup-directory).
|
|
9 Document prolog and epilog functions. |
This section contains definitions of document prolog and epilog functions.
In addition, there are a number of more basic functions which return information about
the document. Several of these return empty strings, and they intended to be redefined in other contexts. |
|
standard-prolog |
Form | (standard-prolog [language]) |
Description | Return a standard document prolog - front matters - inserted before any document elements.
If requested, the rendering function can insert the standard prolog.
In some contexts, the standard prolog may depend on the optional language parameter. |
Returns | The document type declaration and the copyright-clause. |
|
standard-epilog |
Form | (standard-epilog [language]) |
Description | Returns a standard document epilog - end matters - inserted after the document elements.
If requested, the rendering function can insert the standard epilog.
In some contexts, the standard epilog may depend on the optional language parameter. |
Returns | the laml standard comment and the tracing comment. |
|
document-type-declaration |
Form | (document-type-declaration [language]) |
Description | Return a document type declaration. This function is redefined in the individual mirrors.
Called by standard-prolog.
In some contexts, the document type declaration may depend on the optional language parameter. |
Returns | the empty string (if not redefined) |
|
copyright-clause |
Form | (copyright-clause) |
Description | Return an HTML comment with a copyright notice, or an empty string.
You can redefine this function if you need a copyright message as part of your document.
If you redefine this function, it must return an HTML/XML comment.
Called by standard-prolog. |
Returns | the empty string (if not redefined) |
|
laml-standard-comment |
Form | (laml-standard-comment) |
Description | Return a standard comment about LAML. Depends on the function html-comment.
Called by standard-epilog. |
Returns | an HTML comment about LAML. |
|
tracing-comment |
Form | (tracing-comment) |
Description | Return a HTML comment which somehow traces this document.
Typical information includes source file, time of generation, operating system, Scheme systemt, etc.
Redefine this function if you need tracing information in your document. |
Returns | the empty string (if not redefined) |
|
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 intended to end an LAML file.
Reports on elapsed processing time (currently only in MzScheme and Guile).
|
|
credits |
Form | (credits system-dk system-eng [system-url]) |
Description | Return a credit message to Kurt Nørmark about system-dk (the Danish name) and system-eng (the English name).
As an optional parameter, an URL can be supplied with a link to the credited system. |
Parameters | system-dk | The system name in Danish |
system-eng | The system name in English |
system-url | A URL referring to a WWW description of the system |
|
laml-power-icon |
Form | (laml-power-icon [extra-level icon-size]) |
Description | Return the LAML POWER icon with link to the LAML home page.
Intended for the footer of LAML generated pages, from which the author wish to acknowledge the use of LAML.
The LAML icon is located in (string-append (laml-home-url-prefix extra-level) "images/laml-power-icon-1.gif"),
where extra-level is the optional parameter of the current function.
The optional parameter extra-level can be given if the generated HTML files are placed in a different directory than the startup directory.
The default value is 0.
The optional parameter icon-size can either be small or large. large is the default value.
The role of extra-level is the same as in the procedure laml-home-url-prefix. |
See also | related procedure | laml-home-url-prefix |
|
11 HTML file writing procedures. |
In this section we have a convenient and versatile function which can be used as the outer context of an HTML Scheme expression,
in order to write it to a text file. |
|
write-html |
Form | (write-html mode html-clause [file-path-with-extension]) |
Description | Write html-clause (a string or an ast) to a text file.
The full path to the text file can be given by the third, optional parameter,
the default value of which is (full-source-path-with-extension "html").
Mode may be a symbol (raw or pp), or a list of symbols including one of raw/pp and the symbols prolog and epilog.
The latter determines the rendering of the standard prolog and the standard epilog,
as defined by the functions standard-prolog and standard-epilog (in this file).
If mode is the symbol pp, do pretty print the HTML fragment before writing.
If mode is raw, just write the html clause without any kind of pretty printing.
This procedure loads the LAML xml-html-support pretty printing stuff if needed.
This procedure works on both the ast based and the text based mirrors.
In case html-clause is an ast, the tree is processed by an AST rendering function before the file writing takes place.
There are still a few minor problems with the HTML pretty printer. |
Parameters | mode | a list with one or more of the symbols raw, pp, prolog, and epilog. Alternatively just one of the symbols pp or raw. |
html-clause | the string or ast to be written |
file-path-with-extension | the path of the file on which to write. Must include the file extension, typically html. Defaults to the name of the current source file with extension '.html'. |
See also | default target file | full-source-path-with-extension |
prolog and epilog | standard-prolog standard-epilog |
|
12 The HTML character transformation table. |
This table is used by the HTML rendering function to transliterate char data to
textual contents, as to be shown in a browser. You can use this table to perform
transformation of national characters to HTML character entities, and to perform
other character transliterations. |
|
html-char-transformation-table |
Form | html-char-transformation-table |
Description | A vector of length 256 which transforms character number i to a string.
Position number i determines how the extended ASCII character i is transformed.
Boolean entry #t means 'do not transform'.
Boolean entry #f means 'ignore char'.
A string entry describes a proper transformation.
A char entry describes a proper transformation.
An integer entry describes a transformation to the corresponding character number.
All other entries are illegal.
|
|
set-html-char-transformation-entry! |
Form | (set-html-char-transformation-entry! transformation-table index new-entry) |
Description | Mutate a html character transformation table at position index.
More specifically, put new-entry at position index in the table.
The first entry in the table has index 0. |
Parameters | transformation-table | Typically the vector html-char-transformation-table |
index | a number between 0 and 255 |
new-entry | The new entry, which can be boolean, a string, a character, or an integer. |
See also | info about table | html-char-transformation-table |
|
html-char-transform |
Form | (html-char-transform char [transformation-table]) |
Description | Return the transformation of char or string, as transformed by a character transformation table.
Input: a character. Output: a string
chararcters outside the range [0..255] are just passed through, in case an extended character set is used. |
Parameters | transformation-table | A character transformation table, which defaults to html-char-transformation-table defined in laml.scm |
|