Generated: July 2, 2004, 09:28:18Copyright ©2004, Kurt NÝrmarkThe local LAML software home page

Reference manual of the Scheme Elucidator

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

Source file: styles/elucidator/elucidator.scm
LAML Version 24.00 (December, 2003, development)

This is the documentation of the original Scheme Elucidator, which now is obsolete. Please consult the Reference Manual of the Scheme Elucidator 2.

The Scheme Elucidator is a program development tool which produces internal documentation of a Scheme program. The Scheme Elucidator is part of the LAML software package, and it is available from the LAML home page.

Internal documentation is seen as a contrast to interface documentation, which can be made by means of SchemeDoc. The produced documentation consist of a number of HTML files, to be shown in an Internet browser. The sources of the produced documentation is a number of scheme program files, a documentation file in a simple text format, and an LAML setup file. The the root of the resulting HTML files is located in the same directory as the documentation and the setup file. The documentation is produced when the LAML file is processed. Taken together these files form a so-called documentation bundle.

An elucidator is a kind of a literate programming tool, which connects the documentation and the program by means of links instead of physically embedding the program fragments in the documentation. To emphasize this difference, we talk about elucidative programming instead of literate programming.

The Scheme elucidator produces web documentation. There is also editor support of producing the documentation. Currently we support elucidative Scheme programming via the Emacs text editor. Below we will also summarize the editor commands which we use in Emacs for elucidative programming.

There exists (incomplete) internal documentation of the Scheme Elucidator (on the www.cs.aau.dk site) in terms of an elucidative program. There is also a brief user guide, which describes how to navigate the Elucidator in a WWW browser. Please also take a look of the examples, in particular the example called 'Small Meta Demo', which in simple way illustrates all the different facilities in the Scheme elucidator. The LAML tutorial is written as a set of elucidative programs, and as such it also makes up a good example.

If you are a new user of the Elucidator start reading the section 'Practical Introduction' below the table.

Table of Contents:
1. Practical Introduction4. Lisp level documentation functions7. The program files
2. Forms in the setup file5. The textual documentation file8. An example of a complete documentation file
3. Secondary setup6. The setup file9. Elucidator editor support using Emacs

Alphabetic index:
alphabetic-cross-reference-index?alphabetic-cross-reference-index?A boolean variale controlling whether to split the cross reference index in alphabetic files.
alphabetic-defined-name-index?alphabetic-defined-name-index?A boolean variale controlling whether to split the defined name index in alphabetic files.
begin-documentation(begin-documentation)Starts the section of the documentation in which documentation-entry and documentation-section forms may appear.
body(body b)Defines the body of a documentation-entry.
browser-pixel-widthbrowser-pixel-widthA variable defining the width of the browser in pixels
control-frame-pixel-heightcontrol-frame-pixel-heightThe pixel height of the (top level) control frame
copy-image-files?copy-image-files?A variable which controls whether to copy image icons from the software directory to the source (documentation) directory.
d-link-prefix-chard-link-prefix-charA variable defining the documentation link prefix character.
d-link-suffix-chard-link-suffix-charA variable defining the documentation link prefix character.
default-program-font-sizedefault-program-font-sizeSet the default font size of the programs presented in this elucidator.
default-program-linkdefault-program-linkA variable that determines the default kind of linking from documentation to program.
default-table-of-contentdefault-table-of-contentSet the default table of contents of this elucidator.
documentation-entry(documentation-entry . elements)Define the elements of a documentation entry.
documentation-from(documentation-from documentation-file)Parses and extracts documentation from a separate, textual format which we define in a subsequent section of this manual.
documentation-intro(documentation-intro title author email affiliation abstract)Define the documentation introduction in terms of a title, author, email, affiliation, and abstract
documentation-section(documentation-section . elements)Define the elements of a documentation section.
elucidator-color-schemeelucidator-color-schemeAn association list that maps group strings to colors.
elucidator-home-urlelucidator-home-urlDefine the home URL of the elucidator.
elucidator-marker-charelucidator-marker-charA char valued variable which defines the character used as source marker char.
elucidator-verbose-modeelucidator-verbose-modeA variable controling the amount of output written while eludicating a documentation bundle.
end-documentation(end-documentation)Ends the section of the documentation which contains documentation-entry and documentation-section forms
end-file-empty-linesend-file-empty-linesThe number of empty lines in the bottom of an html file, Allow navigation to bottom stuf.
file-location(file-location path)Sets the file location of a program source to be path
group(group group-name)Defines the group to which a source file belongs.
id(id id-symbol)Defines the identification of a documentation-entry or documentation-section
intro(intro i)Defines the introductory text of a documentation-entry.
key(key key-val)Sets the key to key-val.
language(language lang)Defines the programming language used in a program source
link-definitions-to-cross-reference-index?link-definitions-to-cross-reference-index?A boolean variable which controls whether to link from program definitions to the corresponding entry in the cross reference index.
make-all-indexes(make-all-indexes)Ask for generation of both duplicate name index, cross reference index, and defining name index
make-large-source-files?make-large-source-files?A boolean variable which controls the generation of a source file with large fonts.
make-no-indexes(make-no-indexes)Ask for generation of no indexes
manual-frame-from-documentation manual-frame-from-documentationA variable that determines the name of the browser frame used when we address manual entries from the documentation.
manual-frame-from-programmanual-frame-from-programA variable that determines the name of the browser frame used when we address manual entries from the program.
manual-source(manual-source . elements)Declare a LAML manual file to be part of the documentation.
maximum-processing(maximum-processing)Ask for maximum processing of the documentation bundle.
minimum-processing(minimum-processing)Ask for minimum processing of the documentation bundle.
p-link-prefix-charp-link-prefix-charA variable defining the program link prefix character.
p-link-suffix-charp-link-suffix-charA variable defining the program link suffix character.
present-hidden-ids?present-hidden-ids?Controls whether to present the identification of sections and entries, hidden using the background color.
process-only(process-only . source-keys)Controls which of the sources files to process.
program-source(program-source . elements)Define a program source file to be part of this documentation bundle.
rs4r-url-prefixrs4r-url-prefixDefine the URL prefix to the LAML distribution directory that contains the 'Scheme knowledge'.
set-documentation-name(set-documentation-name name)Define the name of the documentation.
set-source-directory(set-source-directory dir)Defines the source directory to be dir.
source-marker-kindsource-marker-kindA variable which deterimens the 'style' of source markers on the documentation page.
title(title t)Defines the title of a documentation-entry or documentation-section
url-location(url-location path)Sets the url address of a manual-source to be path

 

1.   PRACTICAL INTRODUCTION
When you have installed LAML on your computer you also have a full installation of the Scheme elucidator, including Emacs support of elucidative programming.

The emacs command M-x make-elucidator helps you establish a fresh elucidator. Follow the direction given from this command. From Emacs type C-e ? to get brief help on the Elucidator editor commands. For more complete information see the section 'Elucidator editor support using Emacs' in this manual.

The command M-x elucidate (or C-e C-o) on an elucidator buffer activates the Elucidator from Emacs. The Elucidator is the tool which produces the WWW pages which presents the documentation bundle in an Internet browser. The main file is found in html/index.html. In addition, if the setup file is called f.laml, the main file is available as f.html in the source directory.

When you read the Elucidator WWW pages navigate to the Help page via one of the 'Question Mark Icons' to get help on the possibilities offered by the Elucidator tool.


 

2.   FORMS IN THE SETUP FILE
The setup file must be a file with laml file extension. This is the file which connects all the files in a documentation bundle. In this section we will describe the important and primary functions and forms, which may be found in the setup file. In the next section we document a number of less important forms. We start with the most important setup forms


documentation-intro


Form
(documentation-intro title author email affiliation abstract)

Description
Define the documentation introduction in terms of a title, author, email, affiliation, and abstract

Parameters
titleThe title of the documentation (a string)
authorThe author of the documentation (a string)
emailThe email address of the author (a string)
affliationThe affiliation of the author (a string)
abstractThe abstract of the documentation (a string)


program-source


Form
(program-source . elements)

Description
Define a program source file to be part of this documentation bundle. A program source file is defined in terms of a key name, a file location, the programming language used, and a group name. The key name nick names the file for use in an elucidative program (in order to avoid using the full file name or file path). The file location should be the full path to the program file (including extension). The programming language must be Scheme. Finally, group defines the belonging of this source file to a group of logically related source files. This is used for background coloring purposes. One or more program-source forms may be present the the LAML setup file

Parameters
elementsan element may be a key, file-location and language forms

See also
Constituentskey    file-location    language    group    


manual-source


Form
(manual-source . elements)

Description
Declare a LAML manual file to be part of the documentation. This causes links to be created from the programs to relevant manual entries. File-location clauses must address '-.lsp' files which are generated by the manual document style.

Parameters
elementsan element may be a file-location or a url-location

See also
Constituentsfile-location    url-location    


begin-documentation


Form
(begin-documentation)

Description
Starts the section of the documentation in which documentation-entry and documentation-section forms may appear.


end-documentation


Form
(end-documentation)

Description
Ends the section of the documentation which contains documentation-entry and documentation-section forms

Note
This form initiates far the majority of the processing of the Elucidator. As such, end-documentation is a very important form


documentation-from


Form
(documentation-from documentation-file)

Description
Parses and extracts documentation from a separate, textual format which we define in a subsequent section of this manual. The documentation-file is opened in the source-directory. This form is entirely equivalent to a number of of documentation-entry and documentation-section forms. In fact, the extracted information is passed into the documentation-entry and documentation-section forms, after which these are evaluated by means of the Lisp eval.

Parameters
documentation-fileThe name of the documentation file (a string). No path information must be present. However, a possible file extension must be included.

See also
See alsoset-source-directory    
Equivalent Lisp formsdocumentation-entry    documentation-section    


elucidator-verbose-mode


Form
elucidator-verbose-mode

Description
A variable controling the amount of output written while eludicating a documentation bundle. The type of the variable is boolean. If #t, a bunch of output is written on standard output while processing. The default value is #t.

Note
If necessary, set this variable with a Scheme define form


set-source-directory


Form
(set-source-directory dir)

Description
Defines the source directory to be dir. The source directory is the directory which contains the documentation laml setupfile, and the path typically ends in doc. Ends in a slash. You must setup the source directory by means of this function.

Parameters
dirThe full path of the directory with the laml setup file


set-documentation-name


Form
(set-documentation-name name)

Description
Define the name of the documentation. Per convention, this is the same as the file name of the laml file, without extension.

Parameters
nameThe name of the documentation (a string)


make-all-indexes


Form
(make-all-indexes)

Description
Ask for generation of both duplicate name index, cross reference index, and defining name index

See also
Opposite functionmake-no-indexes    

Note
This variable assigns values to the boolean variables make-duplicated-name-index?, make-cross-reference-index?, and make-defining-name-index?


make-no-indexes


Form
(make-no-indexes)

Description
Ask for generation of no indexes

See also
Opposite functionmake-all-indexes    

Note
This variable assigns values to the boolean variables make-duplicated-name-index?, make-cross-reference-index?, and make-defining-name-index?


process-only


Form
(process-only . source-keys)

Description
Controls which of the sources files to process. Only process the sources whose keys are given in the parameter. If no parameteres are given, process no sources If this form does not appear, process all sources.

Parameters
source-keysa number of source-keys, as specified in the program-source clauses

See also
See alsoprogram-source    


minimum-processing


Form
(minimum-processing)

Description
Ask for minimum processing of the documentation bundle. This means make no indexes, process no of the source files (but read information from last processing, if any), and make no large font source files

See also
Opposite functionmaximum-processing    


maximum-processing


Form
(maximum-processing)

Description
Ask for maximum processing of the documentation bundle. This means make all indexes, process all the source files (but read information from last processing, if any), and make large font source files

See also
Opposite functionminimum-processing    


key


Form
(key key-val)

Description
Sets the key to key-val. The key of a program-source is a convenient string which allows us to reference to a particular source file without using file name or file path

Preconditions
Must be part of a program-source form

Parameters
key-vala string

See also
Neighbor formsfile-location    language    group    
Part ofprogram-source    


file-location


Form
(file-location path)

Description
Sets the file location of a program source to be path

Preconditions
Must be part of a program-source or manual-source form

Parameters
pathThe full path of a source file in the documentation bundle

See also
Neighbor formskey    language    group    
Part ofprogram-source    manual-source    


url-location


Form
(url-location path)

Description
Sets the url address of a manual-source to be path

Preconditions
Must be part of a manual-source form

Parameters
pathThe absolute or relative url of a manual HTML file. Relative to the html directory.

See also
Neighbor formsfile-location    
Part ofmanual-source    


language


Form
(language lang)

Description
Defines the programming language used in a program source

Preconditions
Must be part of a program-source form

Parameters
langa string

See also
Neighbor formskey    file-location    group    
Part ofprogram-source    


group


Form
(group group-name)

Description
Defines the group to which a source file belongs. This is used for background coloring purposes.

Preconditions
Must be part of a program-source form

Parameters
group-namea string

See also
Neighbor formskey    file-location    language    
Part ofprogram-source    


 

3.   SECONDARY SETUP
In this section we document a number of less important setup possibilities.


end-file-empty-lines


Form
end-file-empty-lines

Description
The number of empty lines in the bottom of an html file, Allow navigation to bottom stuf.

Note
If necessary, set this variable with a Scheme define form


browser-pixel-width


Form
browser-pixel-width

Description
A variable defining the width of the browser in pixels

Note
If necessary, set this variable with a Scheme define form


control-frame-pixel-height


Form
control-frame-pixel-height

Description
The pixel height of the (top level) control frame

Note
If necessary, set this variable with a Scheme define form


p-link-prefix-char


Form
p-link-prefix-char

Description
A variable defining the program link prefix character. Default is '{'

Note
If necessary, set this variable with a Scheme define form


p-link-suffix-char


Form
p-link-suffix-char

Description
A variable defining the program link suffix character. Default is '}'

Note
If necessary, set this variable with a Scheme define form


d-link-prefix-char


Form
d-link-prefix-char

Description
A variable defining the documentation link prefix character. Default is '['

Note
If necessary, set this variable with a Scheme define form


d-link-suffix-char


Form
d-link-suffix-char

Description
A variable defining the documentation link prefix character. Default is ']'

Note
If necessary, set this variable with a Scheme define form


copy-image-files?


Form
copy-image-files?

Description
A variable which controls whether to copy image icons from the software directory to the source (documentation) directory.

Note
If necessary, set this variable with a Scheme define form


make-large-source-files?


Form
make-large-source-files?

Description
A boolean variable which controls the generation of a source file with large fonts.

See also
Affected byminimum-processing    maximum-processing    

Note
If necessary, set this variable with a Scheme define form


present-hidden-ids?


Form
present-hidden-ids?

Description
Controls whether to present the identification of sections and entries, hidden using the background color. If you knows theses are presented, it may be useful to copy them from the browser to the editor during the programming and documentation process. Thye type of the variable is boolean.

Note
If necessary, set this variable with a Scheme define form


source-marker-kind


Form
source-marker-kind

Description
A variable which deterimens the 'style' of source markers on the documentation page. The value must be one of the symbols as-text, as-colored-text, as-image. as-image is recommended (default).

Note
If necessary, set this variable with a Scheme define form


elucidator-marker-char


Form
elucidator-marker-char

Description
A char valued variable which defines the character used as source marker char. The default value is '@', which in Scheme is denoted by #\@

Note
If necessary, set this variable with a Scheme define form


alphabetic-cross-reference-index?


Form
alphabetic-cross-reference-index?

Description
A boolean variale controlling whether to split the cross reference index in alphabetic files. If false, make one large cross reference index. Default value is true

Note
If necessary, set this variable with a Scheme define form


alphabetic-defined-name-index?


Form
alphabetic-defined-name-index?

Description
A boolean variale controlling whether to split the defined name index in alphabetic files. If false, make one large cross reference index. Default value is true

Note
If necessary, set this variable with a Scheme define form


link-definitions-to-cross-reference-index?


Form
link-definitions-to-cross-reference-index?

Description
A boolean variable which controls whether to link from program definitions to the corresponding entry in the cross reference index.

Note
If necessary, set this variable with a Scheme define form


elucidator-color-scheme


Form
elucidator-color-scheme

Description
An association list that maps group strings to colors. The group string can be defined side by side with key, file-location, and language in a program-source form. The color can be a LAML color. Typically we use one of the symbolic name documentation-background-color or program-background-color-i, i in [1..7].

See also
Related formprogram-source    

Note
Use a define form to set this variable.


rs4r-url-prefix


Form
rs4r-url-prefix

Description
Define the URL prefix to the LAML distribution directory that contains the 'Scheme knowledge'. This is the 'r4rs/ directory in the LAML distribution. The value of this varibale should be an absolute or relative file path from the elucidator html directory to the 'Scheme knowledge directory'.

Note
Use a define form to set this variable. Unfortunately, I have used a slightly inconsistent abbreviations for this URL prefix property.


elucidator-home-url


Form
elucidator-home-url

Description
Define the home URL of the elucidator. This 'home page' may serve as a common page for a number of elucidators. If false (#f) no home icon is included.

Note
Use a define form to set this variable.


default-program-font-size


Form
default-program-font-size

Description
Set the default font size of the programs presented in this elucidator. The value is either the symbol small or large. Defaults to small

Note
Use a define form to set this variable.


default-table-of-content


Form
default-table-of-content

Description
Set the default table of contents of this elucidator. Possible values are either the symbol overall or detailed. Defaults to overall.

Note
Use a define form to set this variable.


default-program-link


Form
default-program-link

Description
A variable that determines the default kind of linking from documentation to program. The default is used if no +, *, or - is used as the first character in {...}. The value is one of the symbols 'weak, 'strong, or 'none.

Note
Use a define form to set this variable.


manual-frame-from-program


Form
manual-frame-from-program

Description
A variable that determines the name of the browser frame used when we address manual entries from the program. Possible values are "documentation-frame", "program-frame", or another frame name (causing a new window to be created).

See also
Related formmanual-frame-from-documentation    

Note
Use a define form to set this variable.


manual-frame-from-documentation


Form
manual-frame-from-documentation

Description
A variable that determines the name of the browser frame used when we address manual entries from the documentation. This frame is also used to display Scheme manual - R4RS - information. Possible values are "documentation-frame", "program-frame", or another frame name (causing a new window to be created).

See also
Related formmanual-frame-from-program    

Note
Use a define form to set this variable.


 

4.   LISP LEVEL DOCUMENTATION FUNCTIONS
The functions in this section document the Lisp level documentation-entry and documentation-section functions. Normally, these functions are not used. Instead we rely on the simple, textual (and non-Lisp) format of documentation found in a separate file. However, it is perfectly possible to avoid the separate documentation file, and to use the two functions below (and their constituent forms). In fact, the format of the separate, textual documentation file is parsed and transformed to calls of documentation-entry and documentation-section


documentation-section


Form
(documentation-section . elements)

Description
Define the elements of a documentation section. The possible elements are id, title, and intro, all of which are defined in the last part of this section

Parameters
elementsconstituents of the documentation section

See also
Constituents formsid    title    intro    
Similar formdocumentation-entry    


documentation-entry


Form
(documentation-entry . elements)

Description
Define the elements of a documentation entry. An entry is a subsection of a section. The possible elments of an entry are id, title, and body

Parameters
elementsconstituents of the documentation section

See also
Constituents formsid    title    body    
Similar formdocumentation-section    


id


Form
(id id-symbol)

Description
Defines the identification of a documentation-entry or documentation-section

Parameters
id-symbolA unique symbol which identifies a documentation-entry or documentation-section

See also
Part ofdocumentation-section    documentation-entry    


title


Form
(title t)

Description
Defines the title of a documentation-entry or documentation-section

Parameters
tThe title (a string)

See also
Part ofdocumentation-section    documentation-entry    


body


Form
(body b)

Description
Defines the body of a documentation-entry. The body may contain program references in curly brackets {...} and documentation references in brackets [...]

Parameters
bThe body (a string)

See also
Part ofdocumentation-entry    


intro


Form
(intro i)

Description
Defines the introductory text of a documentation-entry. Also this text may contain program references in curly brackets {...} and documentation references in brackets [...]

Parameters
iThe introductory text (a string)

See also
Part ofdocumentation-section    


 

5.   THE TEXTUAL DOCUMENTATION FILE
Here we describe the format of the textual and separate documentation format. The textual format is inserted into the documentation by means of the function
documentation-from . If the textual documentation form is used, the functions defined in the previous sections are typically not used. However, it is perfectly possible to use the textual format (and documentation-from) side by side with documentation-entry and documentation-section forms . Such a mixed style may be attractive for people who want to take advantage of LAML expressions instead of HTML expressions, which can be used in the textual documentation format.

First we describe the documentation intro (corresponding to the function documentation-intro ):

.TITLE       title
.AUTHOR      author
.EMAIL       email
.AFFILIATION affiliation
.ABSTRACT
abstract
.END

After the documentation intro comes a number of documentation sections: (corresponding to the function documentation-section ):

.SECTION id
.TITLE title
.BODY
body-text
.END

Finally, in between sections we have documentation entries (corresponding to the function documentation-entry )

.ENTRY id
.TITLE title
.BODY
body-text
.END

The templates shown above corresponds exactly to the insertions done by the Emacs lisp template functions, which are described in the last part of this manual.

Inside the body text of sections and entries you can make links to program fragments, or more precisely, to the definitions in a Scheme program.

If {f} is used without a leading +, *, or -, the value of the variable default-program-link determines the default kind of linking from documentation to program. Possible values of default-program-link is one of the symbols weak, strong, or none.

If {f}, {+f}, {*f}, or {file:f} does not refer to a program name in the documentation bundle, as defined by the program-source clauses, we attempt to link to a manual entry, as defined by the manual-source clauses.

It is possible to mark a particular place in program by means of a source marker. A source marker in a program must be at a comment place, and it is denoted by @x, where x is a letter in the interval [a..o]. A source marker in a program, such as @a, must be followed by blank space (a space, CR, etc). Source markers can also be used in the documentation, in which they link to the detailed program place via the closest, preceding strong documentation/program link. Make sure that you do not use the same source marker to refer to places in different definitions within a single section or entry in the documentation.


 

6.   THE SETUP FILE
Here follows an example of a complete setup file. The example is taken from the from the LAML example directory:

; The elucidator laml setup file
; Change the capital names

; Load the styles file, hereby defining style function

(load (string-append laml-dir "laml.scm"))

(laml-style "xml-in-laml/elucidator/elucidator")

; Set the directory in which this file resides.
; The directory ends in a '/'

(set-source-directory (startup-directory))

; Set the name of this file, without extension
(set-documentation-name "meta-demo")

; Set the level of processing. With commenting, process all source files.
; (process-only)

; (make-no-indexes)
(make-all-indexes)

(define make-large-source-files? #t)
; (define toc-columns-detail 1) 
; (define present-hidden-ids? #t)
; (define underline-program-links #f)
; (define underline-documentation-links #f)
; (define show-sectional-comment-name #f)

; The RELATIVE (back) path to the r4rs directory, which is located in the root of the LAML distribution.
(define rs4r-url-prefix "../../../../r4rs/")

; Do you want an menu like selection of programs?
(define separate-program-menu? #t)

(define elucidator-color-scheme 
  (make-color-scheme 
    "meta" program-background-color-1
    "other"   program-background-color-2
  ))

(define (laml-source-file f)
  (string-append software-base-directory f))


; Define the sourcefiles in this documentation bundle
(program-source
 (key "meta-demo")
 (file-location (laml-source-file "examples/elucidator/meta-demo/meta-demo.scm"))
 (language "scheme")
 (group "meta")
)

(program-source
 (key "other-source")
 (file-location (laml-source-file "examples/elucidator/meta-demo/other-source.scm"))
 (language "scheme")
 (group "other")
)


; Define the documentation body, here in terms of a documentation-from clause
(begin-documentation)

  (documentation-from "meta-demo.txt")  ; the name of the file can be changed 

(end-documentation)


 

7.   THE PROGRAM FILES
The program files are normal Scheme files. There are only a few things to observe:

In addition the rules about the use of source marker in the scheme program should be observed:



 

8.   AN EXAMPLE OF A COMPLETE DOCUMENTATION FILE
In this section we show an example of complete documentation file. The example is taken from the
meta demo example in the elucidator example directory.

.TITLE       A simple meta demonstration of the Scheme Elucidator
.AUTHOR      Kurt NÝrmark
.EMAIL       normark@cs.aau.dk
.AFFILIATION Department of Computer Science, Aalborg University, Denmark
.ABSTRACT
This elucidative program demonstrates the facilities of the Scheme Elucidator.
The program fragments are just simple and well known functions without any coherence
or real value.
.END

-----------------------------------------------------------------------------

.SECTION first-section
.TITLE A section
.BODY
This is section one. Here we can give overview of the subsequent subsections, which we
happen to call entries.
.END

-----------------------------------------------------------------------------

.ENTRY first-entry
.TITLE An introductory entry
.BODY
Here in the first subsection we can introduce the matters. Typically we do not make
very many references to program pieces from the first section.

A documentation bundle is the set of Scheme files, the textual documentation file, and
the LAML setup file.  <p>

We have made the documentation bundle by means of the emacs command M-x make-elucidator. 
This command creates the documentation file, the first program file, and the setup file.
It also creates the necessary and underlying file and directory structures. When we execute
this editor command we are asked to process the LAML file, and to activate another emacs command
setup-elucidator. We just do that.

.END

--------------------------------------------------------------------------------

.ENTRY second-entry
.TITLE The next entry
.BODY
I made this entry via the Emacs command M-x insert-documentation-entry. <p>

In this entry we can start discussing the Scheme program. Just to have something
on the program side, we have made the well-known {-fak} function in meta-demo. So we make
a reference to it. If we have lost the editor context we can always say C-e C-r (or M-x elucidator-reset-elucidator)
to establish the characteristic split view editor panes with documentation in the top window and
program in the bottom window.<p>

Now let us discuss {*meta-demo$fak}. The reference just inserted is conveniently made by selecting
the fak header in the Scheme file and entering C-e C-p (elucidator-program-ref). It turns out that 
this makes a full qualified reference (file and name). The reason is that the editor - at this point in 
time - does not known any thing about {-fak}. If the documentation bundle had been processed (abstracted)
we would have this knowledge. We may change this policy in the future.<p>

We now process the documentation bundle by C-e C-o (or M-x elucidator-elucidate).

.END

--------------------------------------------------------------------------------

.ENTRY third-entry
.TITLE The next steps
.BODY
We now program additional functions in both {meta-demo$} and in {other-source$}. This - by the way -
illustrates links to whole program files.<p>

The functions in meta-demo are {*list-prefix} and its helping function {+list-prefix-1}. Notice first the
strong reference (red) and the weak reference (blue). We may also just make typographic emphasis, like
{-list-prefix-1} (C-e C-w). 
<p>

The functions in {+other-source$} are {*other-source$pair-up} and its helping function {+other-source$pair-up-1}.<p>

At the bottom of {*other-source$} we see a definitions of {+other-source$key-list} and {+other-source$val-list}.
Following these definitions we see {+other-source$aref-assignment}, which in a rather informal way denotes a section
of the program via use of a so-called  <em>sectional comment</em> in {+other-source$}.

.END

--------------------------------------------------------------------------------

.ENTRY details
.TITLE Discussing details
.BODY
Let us demonstrate the use of source markers in {*fak}.
At @a we test if the parameter is zero. If it is we return the base value 1 (@b).
If not we return n times (fak (- n 1)) (@c); This illustrates the recursion in {+fak}.

.END


--------------------------------------------------------------------------------

.ENTRY the-end
.TITLE The End
.BODY
This ends our simple demonstration of the Scheme elucidator.
.END




 

9.   ELUCIDATOR EDITOR SUPPORT USING EMACS
Using Emacs (GNU Emacs on either windows or unix) there exists a substantial support of elucidative programming. The main idea is to keep track of all the files in a bundle, and to help author a documentation bundle in a a safe and convenient way. We support a splitted frame, with documentation in the top-most window, and a program in the bottom window in an Emacs frame.

We will now describe the Emacs editor commands which support elucidative programming. These are defined in the Emacs lisp file 'elucidator.el' which resides in the same directory as the 'elucidator.scm' program (which defines the Elucidator tool).

CommandKey bindingEffect
make-elucidatornoneMake the directory structure of a new elucidator and establish a setup file based on information retrieved via prompting. Also make a template of the documentation file. As the first thing you should call elucidate on the setup buffer. This will cause the rest of the files to be created, including the necessary gif icons. Finally you should use setup-elucidator to make all the elucidator editor buffers, and to prepare for the programming and documentation process
setup-elucidatornoneSet up the elucidator on an existing laml setup file, which must be an laml file. If f.laml is selected, the textual documentation is assumed to in file f.txt. Both files are brought up in editor buffers.
refresh-elucidatorC-e rRefresh the program knowledge established by the laml processing part of the elucidator. This affect the cross referencing capabilities of the editor part, and it (re)defines the source files on which the elucidator works. The information is taken from the internal directory.
reset-elucidatorC-e C-rReestablish a situation where the documentation and program is shown in a two window configuration, the documentation above the program
gotoC-e g
C-e C-h
A generic navigation command which can be used inside the textual documentation format. If used inside curly bracket navigate to a program unit. If used in brackets navigate to another documentation unit. If used on a defined name in the head of a Scheme define form go to the place this definition is documented. If used on an applied name go to the definition of the name.
backC-e C-bReverse the effect of the previous goto
prog-refC-e C-pInsert a program reference (in curly brackets) in the documentation. Uses completion for entering of a program identification
doc-refC-e C-dInsert a documentation reference (in brackets) in the documentation. Uses completion for entering of a documentation identification
surround-prog-refC-e C-qSurround an identifier with curly brackets in order to make a relation from a place in the documentation to a program unit. This function is an alternative to prog-ref, in situations where there is an existing program unit name in the documentation
show-setupC-e C-uShow the setup LAML file
show-programC-e pShow a program. You are prompted for one of the programs in the documentation bundle
elucidateC-e C-oRun the elucidator on the setup file of the current documentation bundle. This command can be activated from an arbitrary buffer in the documentation bundle
save-elucidator-buffersnoneSaves all the buffers in the documentation bundle
quit-elucidatornoneSave elucidator buffers and kill them all. Reset the state of elucidator.
elucidator-helpC-e ?Shows brief elucidator help information in Emacs

In addition, we support a number of insert functions which allows template insertion. These functions are all defined as part of LAML emacs lisp template facility. The template insertions commands are:

CommandKey bindingEffect
insert-documentation-intrononeInsert a documentation intro using the textual format
insert-documentation-sectionC-e C-xInsert a documentation section using the textual format
insert-documentation-entryC-e C-cInsert a documentation entry using the textual format
insert-lispstyle-documentation-sectionnoneInsert a documentation section using the LAML format
insert-lispstyle-documentation-entrynoneInsert a documentation entry using the LAML format

Any command described above is activated by M-x command (i.e., Esc X command) or via the keyboard bindings. Notice that the prefix of the elucidator keyboard bindings is C-e. Usually C-e runs the command end-of-line. This commands has been moved to C-e C-e when the elucidator is loaded into Emacs.


Generated: July 2, 2004, 09:28:19