Garpagal

Introduction

Web pages of the project Garnoo  are to be created from the database Garnoose.

Direct generation of Web pages

.------------------.                    .------------------.
| database         |  page generator    | Web pages        |
| Garnoose         |------------------->| (e.g., in XHTML) |
|                  |                    |                  |
'------------------'                    '------------------'

However, it was decided not  to create the Web pages by the page-generator directly.

Instead, the page generator "build.pl" writes files in a special intermediate language Garpagal. The name Garpagal  was named to abbreviate something like “Garnoo page generator language ”.

Indirect generation of Web pages

.--------------.             .--------------.             .--------------.
| database     | build.pl    | pages        | garpagal.pl | Web pages    |
| Garnoose     |------------>| in Garpagal  |------------>|              |
|              |             | (Unotal)     |             |              |
'--------------'             '--------------'             '--------------'

Thus, the page generator was separated from the “XHTML  renderer” (i.e., the program rendering the information to an XHTML  representation).

Advantages of this approach are:

• Instead of one large program one has two smaller programs with separated concerns, each focused on one task: The page generator "build.pl" splits the information from the database into separate pages. It decides which piece of information goes to which page. But it is not concerned with XHTML  or another target language. The XHTML  renderer only has the job to translate each page from Garpagal  to XHTML.
• If a rendition to another target notation (e.g., an NROFF  source file) is wanted, it can be created by using another renderer than the script "garpagal.pl". The developer can easily see from the structure of the page generating process, that the script "build.pl" does not have to be modified at all, because it does not contain any reference to XHTML. He only has to be bother with the separated small tasks to translated from Garpagal  to another notation.
• Unotal  as a base language is independent from any specific programming language. Therefore, each program used for the process can be written in any programming or script language: It does not have to be Perl  as in the examples.

A base language for such an intermediate language could be XML. But because of problems with XML  being described elsewhere the data language Unotal  (developed by Stefan Ram ) was used instead. The XHTML  renderer uses support modules for Unotal, which can read a Unotal  file into a data structure. The modules and scripts are unpublished software in pre-alpha state and will be published later.

Examples

The Garpagal  file for the entry "n:base:~description~" as created from the database. (This file might be a historic version, i.e., not the one used for the following XHTML  file.)

http://www.purl.org/stefan_ram/utf-8/n!base!~description~

The XHTML  file for the entry "n:base:~description~" as created from the above file.

http://www.purl.org/stefan_ram/garnoo/n!base!~description~

An example arrow, saying “the earth is a planet.”

           isa
            |
            |
earth --------------> planet
         arrow22

Here an arrow is shown. The arrow has the name "arrow22". It has the relation "isa". It has the source "earth". It has the target "planet".

A constructed example of a Garpagal  page representing the relation "isa"

< &entry name=[isa] relset=< &relset
    < &relarrow arrow=[arrow22]
      source=[earth] target=[planet]>>>

A constructed example of a Garpagal  page representing an isa-arrow

< &entry name=[arrow22]
  relation=[isa] source=[earth] target=[planet]>

A constructed example of a Garpagal  page representing the physical entity earth

< &entry name=[earth]
  outset =< &outset
    < &outarrow arrow=[arrow22]
      relation=[isa] target=[planet]>>>

A constructed example of a Garpagal  page representing the concept planet

< &entry name=[planet]
  incset =< &inset
    < &incarrow arrow=[arrow22]
      relation=[isa] source=[earth]>>>

A constructed example of a Garpagal  page representing the namespace island

< &entry name=[island]
  entries=< &entryset [island:java]>>

Detailed Description of Garpagal 

As Garpagal  is an application of Unotal, its Syntax is that of Unotal  and does not have to be described here. Only the meaning of space type names and their attributes needs to be given:

Type "entry"

A space of type "entry" describes an entry, usually the entry this page describes.

Attributes of the Type "entry"

name

The name of the entry.

data

The data (text) of this entry. The data specifies information specific to this entry.

outset

The outset (outgoing set) of the entry. This is the set of all outgoing arrows starting at this entry.

relset

The relset (relation set) of the entry. This is the set of all arrows with this entry as their relation.

incset

The incset (incoming set) of the entry. This is the set of all incoming arrows ending at this entry.

entries

The entry set of the entry. This is the set of all entries with this entry as their namespace.

Type "outset"

An outset (outgoing set) is a set of arrows starting at an entry. It contains a sequence of outarrows (spaces of the type "outarrow").

Type "relset"

A relset (relation set) is a set of arrows having this entry as their relation. It contains a sequence of relarrows (spaces of the type "relarrow").

Type "inset"

An inset (incoming set) is a set of arrows having this entry as their end point. Actually, this should be renamed to "incset" to be consistent with the name of the attribute "incset". It contains a sequence of incarrows (spaces of the type "incarrow").

Type "entryset"

An space of type "entryset" (entry set) is a set of entries having this entry as their namespace. (internal note: a bug in the script "build.pl" marks the value of the attribute "entries" as the type "inset" [false] and not as the type "entryset" [correct].)

An entry set contains the names (string literals) of its entries directly as its body sequence. E.g., the entryset "< &entryset [e:a] [e:b]>".

Type "outarrow"

An outarrow (outgoing arrow) is an arrow starting at a specific entry.

Attributes of the Type "outarrow"

The arrow starts at the entry specified by the context of this outarrow space (at the super space of the outset it is contained in, i.e., the super space of its super space).

It may have the attributes listed under “Common Attributes of the Type "outarrow", the Type "relarrow" and the Type "inarrow" ” and the following attributes.

target

The target entry of this arrow. This is the entry the arrow is directed to.

relation

The relation of this outarrow. The relation specifies the meaning of this outarrow.

Type "relarrow"

A relarrow (relation arrow) is an arrow having a specific entry as its relation.

Attributes of the Type "relarrow"

The arrow has as its relation the entry specified by the context of this relarrow space (the super space of the relset it is contained in, i.e., the super space of its super space).

It may have the attributes listed under “Common Attributes of the Type "outarrow", the Type "relarrow" and the Type "inarrow" ” and the following attributes.

source

The source entry of this arrow. This is the entry the arrow is starting at.

target

The target entry of this arrow. This is the entry the arrow is directed to. The arrow starts at the entry specified by the context of this outarrow space (at the super space of its outset, i.e., the super space of its super space).

Type "incarrow"

An incarrow (incoming arrow) is an arrow ending at a specific entry.

Attributes of the Type "incarrow"

The arrow has its ending at the entry specified by the context of this incarrow space (the super space of the incset it is contained in, i.e., the super space of its super space).

It may have the attributes listed under “Common Attributes of the Type "outarrow", the Type "relarrow" and the Type "inarrow" ” and the following attributes.

relation

The relation of this outarrow. The relation specifies the meaning of this outarrow.

target

The target entry of this arrow. This is the entry the arrow is directed to. The arrow starts at the entry specified by the context of this outarrow space (at the super space of its outset, i.e., the super space of its super space).

Common Attributes of the Type "outarrow", the Type "relarrow" and the Type "inarrow"

arrow

The name of this outarrow.

data

The data (text) of this outarrow. The data specifies information specific to this arrow.