MetaToo System Administration Guide

Franck Falcoz

Christian Tønsberg

Copyright © 2005 Technical Knowledge Center of Denmark (DTV), Technical University of Denmark (DTU)

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the appendix entitled "GNU Free Documentation License".

Table of Contents
I. Initial Preparations
1. Installation
1.1. From Source
2. Configuration
3. Defining XML MetaData
II. Administrative Maintenance
4. Format Design
5. Form Setup
5.1. Design
5.2. Customisation
III. Getting Data Into and Out of MetaToo
6. Delivering Data Downstream: The Data Access Service (DAS)
6.1. REST based DAS API for Retrieving Records
6.2. Example Response
6.3. REST based DAS API for Retrieving Digital Objects
6.4. REST based DAS API for Registering Back Information
6.5. REST based DAS API for Retrieving Authorities
7. Authorisation data: The Auth Service
A. GNU Free Documentation License

I. Initial Preparations

Disposition: Describing what needs to be done in order to make MetaToo operational as a webapplication for online cataloguing of metadata: Install, Configure (formats, forms, screens, etc), Load (of existing records).

Table of Contents
1. Installation
1.1. From Source
1.1.1. Installing an Additional Version of The Application
2. Configuration
3. Defining XML MetaData

Chapter 1. Installation

A MetaToo application consist of the MetaToo core as well as an application specific supplement and customisation of the core.

Throughout this document, the core may be refered to as "fit" (for historic reasons) or as "the metatoo core".

The target system for the installation must be UNIX. The software packages are particularly well suited for Debian Linux, but should work with other UNIX variants.

1.1. From Source

Installation on a UNIX system involves the following:

  1. Acquire the MetaToo core software package (http://toolxite.net/metatoo/) as well as the MetaToo supplement packages relevant for the application.

  2. Make sure that the software upon which MetaToo depends are present on the target system. The setup script (see below) will provide you with a list of missing packages upon startup. Also, make sure that a database user with appropriate privileges exist. This database user should either have privileges to create databases or - in the case an already existing database is to be used - have all privileges on that existing database.

  3. Unpack the core package and the application package in the same directory. The core package will have be named fit.ver where ver will usually be a 3 digit version number (e.g. fit.1.4.5). The name of the application directory can be anything. For the purpose of this document, we will refer to it as app/

    The rest of the installation takes place from within the app/ directory.

  4. Make any necessary adjustments of the configuration file config.in. The various entries are described in Chapter 2. In most cases, no adjustments are needed.

  5. In the app/ directory, run the setup script setup as superuser (root): 

    app/# ./setup

    This script will start an interactive dialog with the installer and subsequently:

    • check the target system for existence of necessary Perl modules,

    • perform the necessary database actions to create the necessary table structure,

    • install the necessary code on the target system, and

    • upload to the database the content of various definitions (formats, forms, etc) located in the source package(s) in various files.

    The setup dialog will ask for the following:

    Service name

    The dialog will start by asking for a service name - vname - for the installation. Default value is the value for configuration parameter PACKAGE.

    Database name, MySQL user name, MySQL password

    Informations regarding the database used for the installation.

    Admin email

    The mail address to which MetaToo system mails are sent. Should be the application manager or the system administrator.

    metatoo user 'admin' password, metatoo user 'root' password

    The passwords for the two special users associated with any MetaToo installation.

    After these informations are fed to the setup script, it will establish the MetaToo database.

    Application specific - as well as core - definitions are then loaded into the database.

    Finally, various codefiles are copied to their location beneath the cgi-bin directory of the target system. During the copy, the files are renamed, introducing the chosen service name as prefix.

1.1.1. Installing an Additional Version of The Application

An application may be installed more than once on the target system, for example, for test purpose.

Making a second installation of an application is done by making a new installation of the MetaToo supplement packages relevant for the application into directory app2/ which should reside as sibling to app/, and then repeat step 4 and 5 of the install procedure described above. Make sure to:

  • choose a service name at the begining of the dialog which is different from the service name chosen for the initial installation, and

  • choose database parameters for a database different from the one used for the first installation.

As with a first-time installation, it is important that the database user is allowed to create databases (or that the database is readily created at setup time).

Chapter 2. Configuration

A walkthrough of MetaToos config.in file

Chapter 3. Defining XML MetaData

describing formats and introducing forms and their relations

II. Administrative Maintenance

Disposition: Describing how to configure metatoo: format design, formi design, screen design (images, stylesheets, etc), lookups (internal, external). Also, user-maintenance, authorisation, workflow, etc. Intended audience: Application Managers

Table of Contents
4. Format Design
5. Form Setup
5.1. Design
5.2. Customisation
5.2.1. XSL: standard_form

Chapter 4. Format Design

Choose Administration -> Formats -> New Use xpaths (without prefix /) with one addition: foo/bar/.body allow content to an element which has nothing else than attributes as its children

Chapter 5. Form Setup

Cataloguing form setup is a process which influence both the input experience when actually using the form to catalogue metadata as well as the structure of the resulting xml metadata.

The form design is the process of determining

  • which elements the resulting xml metadata should contain; their names and their structure

  • for each field, which kind of input widget should be used to input content to fields

  • the associated text elements associated with fields when cataloguing: Labels and help

  • the associated cataloguing actions which should be available for fields.

The form customisation is the process of determining the apperance of the input form in the cataloguers browser.

A form is designed and/or customised by logging in as admin, choose "administration" and choose the "Forms" menu.

If the form in question does not exist, create it either by duplicating an existing or by creatig a new by pressing "New".

Locate the form in question in the list of forms and press "Edit". This will bring up the design and customisation form for the form in question.

The following sections will describe the setup possibilities for the form in question by describing the content and use of this design and customisation form.

5.1. Design

Disposition: Describe includes, groups, properties, labels, help, actions.

5.2. Customisation

The cataloguing form for - as well as the view of - a metadata record are created by merging an xml representation of the record data with eXtensible Stylesheet Language (XSL) stylesheets, and the resulting HTML is then rendered by the cataloguers browser using Cascading Style Sheets (CSS).

For a specific form, the choice of XSL stylesheets is done by selecting from the dropdown "XSL Stylesheet" near the top.

MetaToo ships with a limited selection of XSL stylesheets, each defining a basic visual structure and design for catalouging forms. If a more application specific layout is needed, it is possible to supplement this list with alternative stylesheet(s).

Each XSL stylesheet has an associated CSS stylesheet. Depending on the degree of customisability in the HTML produced by the XSL, this CSS determines a number of styling parameters for the apperance of the cataloguing form in the browser.

A form specific appeaance is obtained by overloading the associated CSS. This is done by redefining (parts of) the CSS in the input field "CSS" near the top.

In the design process of the actual browser experience of a certain form, FireFox eqiped with the WebDeveloper plugin - and perhaps even with the mozdev plugin - is recommended.

Below, the structure of the output of each of the default XSL is briefly described, as well as the most relevant CSS classes to change.

5.2.1. XSL: standard_form

This XSL represents a layout of the input form which is historically inspired: The structure of its output resembles that of the HTML producd by earlier versions of MetaToo.

The descriptive area - the left hand side of the form - is organised in columns with fixed width. Labels for groups and fields on the top level is set in the first column, labels for groups and fields on the second level is set in the secenond column, etc. The number of columns are determinded by the depth of the form.

Labelwise, groups are layed out with its label vertically aligned with the label of the first subfield or subgroup.

Buttons for collapsion/expansion of groups, adding new occerences (repeat), reordering occurences (move up and move down) as well as buttons for longhelp and lookup are located in the vicinity of the label; either immedialtely after it or right justified in its column.

Help texts are placed as it is described in the design and customisation form: Either below or to the right of input boxes, below the label or as the first line of a group.

CSS classes most relevant to modify:

#the_form

The class controlling the whole form. Its width should be defined in accordance with the width for the descriptive area and the width for the input area.

.input-area

The class controlling the input area - the right hand side of the form, containing the input boxes. Its width should be set in accordance width the width of the individual input boxes as well as the total width of any horisontally layed out groups.

.description-area-1, .description-area-2, .description-area-3, .description-area-4

The class styling the columns of the descriptive areas. Their width should be chosen acording to the labeltexts in a form, making the linebreaking visually tolerable.

Example CSS snippet:

III. Getting Data Into and Out of MetaToo

Disposition: 1) Describing how to load data into MetaToo 2) Describing how to access catalogued metadata. Describing the Data Access Service (DAS)

Table of Contents
6. Delivering Data Downstream: The Data Access Service (DAS)
6.1. REST based DAS API for Retrieving Records
6.1.1. Search related
6.1.2. Format related
6.1.3. Others
6.1.4. Changes done to database records
6.2. Example Response
6.3. REST based DAS API for Retrieving Digital Objects
6.4. REST based DAS API for Registering Back Information
6.5. REST based DAS API for Retrieving Authorities
7. Authorisation data: The Auth Service

Chapter 6. Delivering Data Downstream: The Data Access Service (DAS)

Making records and associated digital objects catalogued with MetaToo available outside of MetaToo is done via communication through the Data Access Service, or DAS.

A client program can use DAS as a web service for retrieving records as well as for registering back informations for records and their associated digital objects.

Note: by default, this service is only accessible from localhost, if you wish to grant external access, add auth.ip to the configuration file with a space separated list of IP addresses: e.g. das.ip 127.0.0.1 192.168.1.2

This chapter describes the communication.

6.1. REST based DAS API for Retrieving Records

The DAS is called for record retrieval as http://yourserver/cgi-bin/yourapp_das?key=val&...&key=val, where the possible keys (and their values) are described below.

6.1.1. Search related

id

a single record ID or a comma separated list of record IDs.

status

a comma separated list record status

timestamp

either a unix timestamp (seconds since EPOCH) or a timestamp in the format YYYYMMDDHHMMSS or 1957-03-20T20:30:00.

type

a comma separated list of record type

where

an abitrary where clause which can be used to select records based, at this time, on the id, udate, cdate, status, grp, uid and type.

6.1.2. Format related

format

if set to 'short', the record XML is not returned

gzip

if equal to 1, the result will be compressed with gzip

pad

if equal to 1, the XML returned will be indented

raw

if equal to 1, the records returned will be extractly like in the database and will not include, among other things, authority text mapping

6.1.3. Others

firstRecord

the number of the first record to be returned, starting from 1 (default: 1).

key

the authentication key, which must match configuration option das.key, if it is defined

maxRecords

the maximum number of records returned (default: 100000).

6.1.4. Changes done to database records

The following changes are done to the database record when not using the raw argument:

Adding of fit namespace to admin fields

All fields and attributes under /<root>/admin are modified to use the fit namespace.

Change update timestamps

All Unix timestamps under //admin/cataloguer/timestamp are changed to ISO8601 dates in local time without timezone.

Adding release dates

The first date of cataloguer publication under a new status is added as admin/released, with the attribute status giving the status code and the body being an ISO8601 date as described above.

Change of authority attribute to fit namespace

All attributes with the name authority or authority_* are moved to the fit namespace.

Modifications done through the export configuration in Metatoo

Metatoo can be configured to modified records upon export. If you have a file 'export.cat_doc.xml' in your application xml directory, changes defined in the file will be applied to your record in DAS.

6.2. Example Response


          
<das:records xmlns:das="http://toolxite.net/ns/metatoo/das/" hits="37">(1)
    <das:record id="34" status="O3">
        <das:object id="e674fb0fce2b68381cc47dca7ed5782a" type="image/gif"
            uri="/doc/e674fb0fce2b68381cc47dca7ed5782a">
            yeti5.gif
        </das:object>
        <das:data>
            ...your XML record...                         (2)
        </das:data>
    </das:record>
    <das:record id="46" status="O4">
    ...
    </das:record>
    <das:record id="15" status="D"/>
    <das:diagnostic>
        <das:result>
            <das:returned>3</das:returned>
            <das:total>37</das:total>
        </das:result>
        <das:error type="warning">
            partial reply
        </das:error>
        <das:args>
            <das:where></das:where>
            <das:timestamp></das:timestamp>
            <das:type></das:type>
            <das:status></das:status>
            <das:pad>1</das:pad>
            <das:raw></das:raw>
            <das:gzip>0</das:gzip>
            <das:firstRecord></das:firstRecord>
            <das:maxRecords>3</das:maxRecords>
        </das:args>
        <das:select>select id from cat_doc</das:select>
    </das:diagnostic>
</das:records>
(1)
Description of construct 1
(2)
Description of construct 2

In this example the we get back three records from the puller. The maxRecords parameter was set to 3 and we can see my comparing //diagnostic/result/total and returned that the reply in incomplete. An error of type warning also indicates that this is a partial reply. To view the next two records, you would need to use the same request but this time setting firstRecord to 4.

The attribute /records/record/@id is the metatoo internal identifier for that record. The attribute /records/record/@status is the status of the record, in the example above, you can see that the record as status D which stands for deleted. Deteted records are returned as a closed tag with just the id and status attributes. The object field is a pointer to a file uploaded with the record. Using the object/@id attribute it is possible to link the actual file section in you record to the object/@uri.

6.3. REST based DAS API for Retrieving Digital Objects

The DAS is called for Digital Object retrieval as http://yourserver/cgi-bin/yourapp_das/doc/CKSUM, where CKSUM is the MetaToo internl identifier (checksum) for the digital object.

This URL can be constructed from a DAS record retrieval response by combining the url for the DAS with the "uri" attribute of the <das:object> element.

6.4. REST based DAS API for Registering Back Information

A client using the DAS interface to extract records may register back information for records (e.g. id's from various staorage or handler services) as well as for objects associated with records.

The REST based interface for that resides on http://yourserver/cgi-bin/yourapp_das/extid?key=val&...&key=val, where the keys are described below.

type

The type of the external id. Typically an identifier of the recieving system.

extid

The external ID to register.

recid

The record ID to register for.

objid

The identifier (cksum) of a MetaToo object related to the record. Use this if the registration is for the digital object rather than for the record itself.

6.5. REST based DAS API for Retrieving Authorities

In order to retrieve an xml representation of authority 'foobar', the DAS is called for authorities as http://yourserver/cgi-bin/yourapp_das?tab=fit_authority&where=name='foobar'

If an element in a DAS record retrieval response was catalogued by a form in which authority (dropdown) 'quez' were used for this element, the element will carry an attribute 'fit:auth_quez'.

Chapter 7. Authorisation data: The Auth Service

This service is designed to be used by external service to discover some of the Metatoo authorisation data for a specified user. For example, a search interface could have a direct link to edit a record but unless authorisation information is available, that system has no way of knowing if the user is actually allowed to edit the record.

Note: by default, this service is only accessible from localhost, if you wish to grant external access, add auth.ip to the configuration file with a space separated list of IP addresses: e.g. auth.ip 127.0.0.1 192.168.1.2

This authorisation service is REST based and takes a single user ID as parameter: e.g. http://localhost/cgi-bin/urbit_auth?id=root

The result is an XML record with the following main elements: diagnostic: internal diagnostic, fields: fields from the authentication record, flags: authorisation flags, groups: main and extra groups this user belongs to. Example record: 


          
<authentication>
    <diagnostic>
        <id>darcimm</id>
        <grp>dtu_imm</grp>
    </diagnostic>
    <fields>
        <email>pf@dtv.dk</email>
        <grp>dtu_imm</grp>
        <id>darcimm</id>
        <switch_id/>
    </fields>
    <flags>
        <flag>default_document</flag>
        <flag>default_document_create</flag>
        <flag>default_document_pe</flag>
        <flag>default_document_view</flag>
        <flag>document_group_list</flag>
        <flag>document_proof_o21</flag>
        <flag>document_search</flag>
        <flag>document_su_in</flag>
        <flag>document_su_in_create</flag>
        <flag>document_su_l</flag>
        <flag>document_su_pr</flag>
        <flag>fit_authorisation_view</flag>
        <flag>fit_authority_view</flag>
        <flag>fit_javascript_view</flag>
        <flag>fit_view_view</flag>
    </flags>
    <groups>
        <group>dtu_imm</group>
    </groups>
</authentication>

This service does not return table level authorisation information because the resulting XML would be too complicated and hard to use by an external service anyway.

You can however deduce some things based on your authentication rules. For example, by default a user is always able to edit is own records, this will mean that darcimm user will be able to edit all his own records.

Further more, there are super-user flags defined which allows a user to edit records of a certain time if they are part of a group to which he belongs. For example, the user above has the flag document_su_l and has access to group dtu_imm, which means he will be able to edit all dtu_imm literature records.

Appendix A. GNU Free Documentation License




        GNU Free Documentation License
          Version 1.2, November 2002


 Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.


0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.

This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.


1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The "Document", below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as "you".  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification.  Examples of
transparent image formats include PNG, XCF and JPG.  Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".)  To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.


2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.


3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.


4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct
   from that of the Document, and from those of previous versions
   (which should, if there were any, be listed in the History section
   of the Document).  You may use the same title as a previous version
   if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
   responsible for authorship of the modifications in the Modified
   Version, together with at least five of the principal authors of the
   Document (all of its principal authors, if it has fewer than five),
   unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
   Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
   adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
   giving the public permission to use the Modified Version under the
   terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
   and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add
   to it an item stating at least the title, year, new authors, and
   publisher of the Modified Version as given on the Title Page.  If
   there is no section Entitled "History" in the Document, create one
   stating the title, year, authors, and publisher of the Document as
   given on its Title Page, then add an item describing the Modified
   Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
   public access to a Transparent copy of the Document, and likewise
   the network locations given in the Document for previous versions
   it was based on.  These may be placed in the "History" section.
   You may omit a network location for a work that was published at
   least four years before the Document itself, or if the original
   publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
   Preserve the Title of the section, and preserve in the section all
   the substance and tone of each of the contributor acknowledgements
   and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
   unaltered in their text and in their titles.  Section numbers
   or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements".  Such a section
   may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
   or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.


5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications".  You must delete all sections
Entitled "Endorsements".


6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.


7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.


8. TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.


9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License.  Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.


10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.