.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH pgml 5 "August 29, 2002"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
pgml \- a (PostGresql) Markup Langage conforming (almost) to Extended Entity
Relationship
.SH DESCRIPTION
Pgml is a xml compliant langage for describing databases structure.
Tools are provided (see
.IR pgml2sql (1), pgml2dot (1))
which read those files and generate SQL schema or graphical representation.

Althougth not postgreSql specific, some features work only with
postgreSql v7 or above.

.PP
You can (have to) read the DTD ans sample files at
.BR /usr/share/doc/pimentech-dbutils/pgml/pgml_2.0.dtd .

Basically, a pgml file looks like :

.RS 1
<?xml version='1.0' encoding='ISO-8859-1' standalone="no"?>

<!DOCTYPE template SYSTEM "path/pgml_2.0.dtd">

<schema>
.RS 1

(...)

.RE
</schema>
.RE

Inside the only schema section, you describe tables (without
keys nor references) like this :

.RS 2
<table name='employees'>

<attribute name='firstname' type='text' default='foobar'/>

<attribute name='birth' type='date' default='now'/>

(...)

</table>

<table name='useless_datas'>

<attribute name='foo' type='text' default='foobar'/>

<attribute name='bar' type='int4' default='0'/>

(...)

</table>
.RE

You then enter relations between tables, specifying
names and cardinality :

.RS 2
<relation name='employees_foobar'>

<participation table='employees' type='0,1,1'/>

<participation table='useless_datas' type='0,n,0'/>

<attribute name='hours' type='int4'/>

</relation>
.RE

As we are not Extended Entity Relationships conventions fanatics,
you can put attributes in relations, in which case that relation will
be
.I de facto
converted to a table. Also, in the
.I type 
of the relation, where you specify the cardinality, you also can
provide a hint as where to put the key (if the third value of the
type of a participation is 1, the key will be in this table).
So that what we have in the previous example is a table named
employees_foobar, referenced by employees (this implies that employees_foobar has a
key by itself), referencing useless_datas, and whith a field named hours of type int4.

The fields added for holding keys are named id_tablename by default (but see 
.BR pgml2dot (1)),
and the fields added for holding references are named after the referenced
table name prepended by 'ref_'.

Note that when the relation leads to a SQL table, its name is the name of the relation.
Note also that in some conflictual cases the name of the relation is used to build the name
of the field which hold a reference.

.SH SEE ALSO
.BR pgml2sql (1),
.BR pgml2dot (1).
.br
.SH AUTHOR
This manual page was written by PimenTech staff <info@pimentech.net>.