Copyright ©2006 Jáchym Äepický 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 section entitled "GNU Free Documentation License".
In this file, you can found the description of installation and configuration of PyWPS script. At the and, you can learn, how to add your own process to the list of processes.
PyPWS project has been started on April 2006 with support of DBU - Deutsche Bundesstiftung Umwelt (http://dbu.de) and with help of GDF-Hannover (http://gdf-hannover.de) and Help Service Remote Sensing (http:/bnhelp.cz) companies.
Source code can be found at http://Les-e(2,11)[t]35j315k?cat=pywps
Please report all problems or unexpected handeling.
Required packages:
Recommended packages:
$ tar -xzf pywps-VERSION.tar.gzand run
$ python setup.py install
\$ ./wps.py Content-type: text/xml <?xml version="1.0" ?> <ExceptionReport version="1.0.0" xmlns="http://www.opengis.net/ows" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Exception exceptionCode="MissingParameterValue" locator="request"/> </ExceptionReport>
If you got some other message, like e.g.:
Traceback (most recent call last): File "trunk/index.py", line 53, in ? from Wps import wpsexceptions File "/home/jachym/prog/pywps/trunk/Wps/wpsexceptions.py", line 8, in ? from xml.dom.minidom import Document ImportError: No module named xml.dom.minidom
Than something is wrong with your Python installation or with the program. This message means, that the xml.dom.minidom package is not installed in your system.
Before you start to tune your pywps program, you should get your copy of OpenGIS(R) Web Processing Service document (OGC 05-007r4) version 0.4.0 from http://www.opengeospatial.org/specs/?page=specs
NOTE: Note, that the configuration option are CASE SENSITIVE
Pywps configuration takes places in two files. The files are actually python scripts, so it does not harm, if you have some experience in python programming language. But you should be able to setup the program without any python knowledge.
The first file is in etcsettings.py and (optional) the second file is etcgrass.py. Some special "tuning" can be done in processes/__init__.py file
This file has got two sections: WPS and serverSettings
In the WPS section, the main configuration is set, which appears mostly in GetCapabilities request. The mandatory parameters, which should be set up are (with default/recommend values):
'version': "0.4.0", 'ServiceIdentification': { 'Title':"Jachym's WPS server", 'ServiceType':"WPS", 'ServiceTypeVersion':"0.1.0", 'Abstract':'Abstract to this WPS', }, 'ServiceProvider': { 'ProviderName' : "Your Company", 'IndividualName':"Your Name", 'PositionName':"Your Position", 'Role':"your role", 'DeliveryPoint': "Street", 'City': "City", 'PostalCode':"00000", 'Country': "Your country", 'ElectronicMailAddress':"your.email@address", }, 'OperationsMetadata': { 'ServerAddress' : "http://localhost/cgi-bin/wps/wps.py", }, 'Keywords' : ['GRASS','GIS','WPS'],
In the ServerSettings section, the variables are set, which have impact on the whole server.
# NOTE: You have to create this directory manually and set rights, so # the program is able to store data in there 'outputPath': '/var/www/wpsoutputs', # # 'outputUrl' - URL of the directory, where the outputs will be stored 'outputUrl': 'http://192.168.1.31/wpsoutputs', # # tempPath - path to directory, where temporary data will be stored. # NOTE: the pywps has to have rights, to create directories and files # in this directory 'tempPath': '/tmp', # # maxOperations - maximum number of operations, which is allowed to low # on this server at ones # default = 1 'maxOperations':1, # # maxSize: maximum input file size in bytes # NOTE: maximum file size is 5MB, no care, if this number is higher 'maxSize':5242880, # 5 MB # # maxInputParamLength: maximal length of input values # NOTE: maximum length of input parameters is 256, no matter, how height # is this number 'maxInputParamLength':256,
This file servers for configuration of GRASS GIS environment (if your processes need one). Everything is stored in grassenv structure.
# PATH in which your modules (processes) should be able the search. # Default value: 'PATH': "/usr/local/grass-6.1.cvs/bin/:/usr/local/grass-6.1.cvs/scripts/:\ /usr/bin/:/bin/:", # Add eventually some other path, in which should GRASS search for modules 'GRASS_ADDON_PATH': "", # Version of GRASS, you are using 'GRASS_VERSION': "6.1.cvs", # GRASS_PERL, where is your PERL bin installed 'GRASS_PERL': "/usr/bin/perl", # GRASS_GUI should be always "text" unless you know, what you are doing 'GRASS_GUI': "text", # GISBASE is place, where your GRASS installation is 'GISBASE': "/usr/local/grass-6.1.cvs", # LD_LIBRARY_PATH 'LD_LIBRARY_PATH':"/usr/local/grass-6.1.cvs/lib", # HOME has to be set 'HOME':"/var/www",
All processes are stored in the processes directory. Put your file e.g. myprocess.py in there.
Process is python class with two functions: __init__(self) and execute(self). In the __init__(self) function, inputs, outputs and other configuration values are set. The GIS operations are called in execute(self) function. It is possible also to add as many your functions, as you wish.
The configuration part belongs to the __init__ function of the Process class.
Mandatory variables are
# Myprocess name self.Identifier = "spearpath" # Myprocess version self.processVersion = "0.1" # Is it allowed, store the data on the server? self.storeSupported = "true" # Do not wait, till the calculation is done -> return XML with status # immediately self.statusSupported = "true" # Myprocess Title self.Title="Find the shortest path on the roads map on Spearfish dataset"
Eventually optional attributes can be found in the table 38 - "Parts of ExecuteResponse data structure"
If your process should happen in existing GRASS-Location, and you just need the input parameters for GRASS modules, you can specify it's name by grassLocation variable:
grassLocation="/var/grassdata/spearfish57/"
If this variable is not set, new temporary GRASS Location && mapset will be generated and you can work in there. The projection of the location will be XY.
Data inputs are defined in self.Inputs array. Each input is an dictionary with several (mostly mandatory) parameters. Each input type (LiteralValue, ComplexValue, ComplexValueReference, BoundingBoxValue) must be a Python's dictionary ("{}") structure, which can be filled with aditional attributes.
Allowed values are set by array of values. If there is no values arry or it contains "*" in the array, AnyValue is assumed:
{ # example of "AnyValue" case with centimeters as default unit 'Identifier': 'my_input_value', 'Title': 'This is my input value', 'LiteralValue': {'UOMs':["cm"]}, # alternative for any value: # 'LiteralValue': {'values':["*"]}, 'dataType': type(0.0) }, { # example of "AllowedValues case with default units (meters) 'Identifier': 'my_input_value', 'Title': 'This is my input value', 'LiteralValue': {values:[250, "300", '40', "a"]}, # the default value: 'value': 250, },
{ 'Identifier':'input_map_file', 'Title': 'Input raster map', 'ComplexValueReference': { 'Formats': [ "image/tiff" ] }, },
{ 'Identifier':'vector', 'Title': 'Input vector map', 'Abstract': "This vector map must be part of the input XML document", 'ComplexValue': { 'Formats': [ "text/xml" ] }, },
{ 'Identifier':'bbox', 'Title': 'Bounding box', 'Abstract': "Bounding box", 'BoundingBoxValue': {}, },
Resulting value in your self.Input[NUMBER]['value'] will be array of four values in form [Lower East, Lower North, Upper East, Upper North].
Default values can be set like follows: 'value':"Default value",
NOTE: If the 'dataType' attribute is not set, control of the input value will not be possible, which could endanger your system
For more details look in the table 33 "Parts of ValueFormChoice data structure"
The self.Outputs structure defines the look of the outputs from your process. The definition is not much different from the Input structure:
{ 'Identifier': 'output', 'Title': 'Resulting output map', 'ComplexValue': { 'Formats':["text/xml"], } }, { 'Identifier': 'text', 'Title': 'Some text', 'Abstract': 'Some informative text', 'LiteralValue': { {'UOMs':["none"]}, } }
{ 'Identifier': 'mybbox', 'Title': 'Bounding Box of resulting map', 'BoundingBoxValue': {}, 'value' : [0, 0, 10, 10], },
The process must be defined in the execute(self) function. To each element in self.Inputs array, 'value' option will be added. Input variables are accessible via 'value' attribute of each element of the self.Inputs array.
Another way, how to access input values it to do so via new hash self.DataInputs. This way is more intiutive and less confusing. If order of Inputs will change, their identificators in DataInputs structure remain same.
Also new variable self.grassenv will be in your process at your service.
Output values can be stored either directly to self.Outputs[index]['value'] variable or to self.DataOutputs['identifier'] hash on similar way, how DataInputs are used. This makes the usage again more intuitive.
def execute(self): if os.system("""g.region -d >&2"""): return "Could not set region to default" os.system("r.in.gdal -o in=%s out=my_map >&2" %\ (self.Inputs[0]['value'])) os.system("r.mapcalc my_output=my_map+%d >&2" %\ (self.DataInputs['value'])) if os.system("r.out.gdal type=Float32 out=map.tif in=my_output >&2"): return "Could not export resulting raster map [map.tif]" self.Outputs[0]['value'] = "map.tif" self.DataOutputs['location'] = self.grassenv['LOCATION_NAME'] return
That is all, folks!
At the end of the execute function, None value should be returned. Any other value means, that the calculation will be stopped and error report will be returned back to the client.
The simplest way, how to call GRASS's (and other shell) commands is via python's os.system() or os.popen() function. Before you do so, it is important to import the os python package (usually one of the first lines in the file). This approach might not be the best, but it is the simplest one. Feel free to use any other low-end functions.
Unfortunately, the GRASS modules are very verbose. Some messages are written to STDOUT, some to STDERR. The STDERR will be stored in the error file of your web server. But you have to "catch" the messages, sent to STDOUT. This can be done e.g. by using "1>&2" statement (redirecting STDOUT to STDERR in shell):
os.system(""" echo "Rekni jim drazi, tatko, za to nic nedas." >&2 """)
wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\ request=getcapabilities" "http://localhost/cgi-bin/wps.py"
wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\ request=DescribeProcess&Identifier=your_process" \ "http://localhost/cgi-bin/wps.py"
wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\ request=Execute&Identifier=your_process&\ datainputs=input1,value1,input2,value2" \ "http://localhost/cgi-bin/wps.py"
To get response from PyWPS you have to formulate appropriate query string first. You can use HTTP GET style or HTTP POST style.
HTTP GET style is standard URL, with all parameters in one line. You can not set any ComplexValue data in your process via HTTP GET. Example:
wget -nv -q -O - --post-data="version=0.4.0&service=Wps&\ request=Execute&Identifier=your_process&\ datainputs=input1,value1,input2,value2"\ "http://localhost/cgi-bin/wps.py"
In HTTP POST style, you send one "request" parameter, which contains XML input. The XML file can contain also included ComplexValue data, e.g. GML file. Example:
wget --post-file=execute-post.txt \ "http://localhost/pywps/wps.py" -O - -nv -q
The execute-post.txt file can look like follows:
request=<?xml version="1.0" encoding="utf-8"?> <Execute service="WPS" version="0.4.0" store="false" status="false" xmlns="http://www.opengeospatial.net/wps" xmlns:ows="http://www.opengeospatial.net/ows" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengeospatial.net/wps/wpsDescribeProcess.xsd"> <ows:Identifier>searchpath</ows:Identifier> <DataInputs> <Input> <ows:Identifier>streetmap</ows:Identifier> <ows:Title>The map</ows:Title> <ows:ComplexValue> <Value> <ogr:FeatureCollection xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://ogr.maptools.org/ donut.xsd" xmlns:ogr="http://ogr.maptools.org/" xmlns:gml="http://www.opengis.net/gml"> <gml:boundedBy> <gml:Box> <gml:coord><gml:X>4.263256414560601e-14</gml:X> <gml:Y>-70.71067811865474</gml:Y></gml:coord> <gml:coord><gml:X>141.4213562373095</gml:X> <gml:Y>70.71067811865474</gml:Y></gml:coord> </gml:Box> </gml:boundedBy> <gml:featureMember> <ogr:donut fid="F0"> <ogr:geometryProperty><gml:LineString><gml:coordinates> 70.710678118654755,70.710678118654741,0 141.42135623730951,0.0, 0 70.710678118654741,-70.710678118654741,0 0.000000000000043, 0.000000000000057,0 70.710678118654755, 70.710678118654741,0</gml:coordinates> </gml:LineString></ogr:geometryProperty> </ogr:donut> </gml:featureMember> <gml:featureMember> <ogr:donut fid="F0"> <ogr:geometryProperty><gml:LineString><gml:coordinates>50.000000000000014, 0.000000000000021,0 71.213203435596427,-21.213203435596419,0 92.426406871192853,0.0,0 71.213203435596427,21.213203435596423,0 50.000000000000014,0.000000000000021,0</gml:coordinates> </gml:LineString></ogr:geometryProperty> </ogr:donut> </gml:featureMember> </ogr:FeatureCollection> </Value> </ows:ComplexValue> </Input> <Input> <ows:Identifier>x1</ows:Identifier> <ows:LiteralValue>591679.31</ows:LiteralValue> </Input> <Input> <ows:Identifier>y1</ows:Identifier> <ows:LiteralValue>4927205.07</ows:LiteralValue> </Input> <Input> <ows:Identifier>x2</ows:Identifier> <ows:LiteralValue>608642.625</ows:LiteralValue> </Input> <Input> <ows:Identifier>y2</ows:Identifier> <ows:LiteralValue>4915876.31</ows:LiteralValue> </Input> </DataInputs> </Execute>
You can see, that there are 4 inputs in this process:
The output from PyWPS can be either XML file or results of processes directly. In default configuration, no files are stored on the server, resulting values (maps) are returned to the client. If you want to return XML file with outputs encoding, you have to enable it in you process configuration with option storeSupported:
self.storeSupported = "true"
And you have to call the PyWPS with "store=true" option:
version=0.4.0&service=Wps&request=Execute&Identifier=your_process&\ datainputs=input1,value1,input2,value2&store=true
Or in XML input:
request=<?xml version="1.0" encoding="utf-8"?> <Execute service="WPS" version="0.4.0" store="true" status="false" xmlns="http://www.opengeospatial.net/wps" xmlns:ows="http://www.opengeospatial.net/ows" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengeospatial.net/wps/wpsDescribeProcess.xsd"> ...
This will cause PyWPS to look after self.status array in your process in form form
self.status = ["Message", Percent_Done]and generate XML file in statusLocation with this embed message. E.g.
self.status = ["Generating raster map", 50]will become
... <Status> <ProcessStarted message="Generating raster map" percentCompleted="50"/> </Status> ...
""" pywps process example: addvalue: Adds some value to raster map """ # Author: Jachym Cepicky # http://les-ejk.cz import os,time,string,sys class Process: def __init__(self): # # Mandatory parameters # # Identifier - name of this process self.Identifier = "addvalue" # processVersion - version of this process self.processVersion = "0.1" # Title - title for this process self.Title="Add some value to raster map" # # Inputs # Inputs = [ {input1},{input2},{...} ] # self.Inputs = [ # This module has 2 inputs: # 1) Input raster map # 2) Value to be added # 0 { 'Identifier':'input', 'Title': 'Input raster map', 'ComplexValueReference': { 'Formats': [ "image/tiff" ] }, 'value':None }, # 1 { 'Identifier': 'value', 'Title': 'Value to be added', 'LiteralValue': {"values":["*"]}, # will cause "AnyValue" 'dataType' : type(0.0), 'value':None }, ] # # Output # The structure is not much different from the input structure # self.Outputs = [ # 0 { 'Identifier': 'vector', 'Title': 'Resulting vector map', 'ComplexValue': { 'Formats':["text/xml"], }, 'value':None }, # 1 { 'Identifier': 'raster', 'Title': 'Resulting raster map', 'ComplexValueReference': { 'Formats':["image/tiff"], }, 'value':None } # 2 { 'Identifier': 'bbox', 'Title': 'Resulting map bbox', 'BoundingBoxValue': {} } ] # # Optional attributes # # # storeSupported = "true" or "false" # should the resulting map be stored on our disk? self.storeSupported = "true" # # statusSupported = "true" or "false" - run asynchronous self.statusSupported = "true" ############################################################## # Execute part of the process def execute(self): """ This function 1) Imports the raster map 2) runs r.mapcalc out=in+value 3) Exports the raster map 4) Sets the bounding box of resulting map 5) runs r.to.vect 6) Exports the vector map """ # for asynchronous process: self.status=["Importing the raster map", 5] # 1) import if os.system("r.in.gdal -o in=%s out=input >&2" %\ (self.DataInputs['input'])): return "Could not import raster map # check for more than one channel for gdalinfoln in os.popen("gdalinfo %s" % \ (self.DataInputs['input'])): if gdalinfoln.split()[0] == "Band" and gdalinfoln.split()[1] == "3": return "This module can work only with ONE channel raster maps" # set right region os.system("""g.region rast=input >&2""") # for asynchronous process: self.status=["Adding input value to raster map", 30] # 2) add the value, convert to int os.system("""r.mapcalc output="int(input+%f)" """ % \ (float(self.DataInputs['value']))) # for asynchronous process: self.status=["Exporting TIFF image", 50] # 3) export the tiff if os.system("r.out.gdal type=Int32 in=output out=%s 1>&2" %\ "output.tif"): return "Could not export raster map" # for asynchronous process: self.status=["Converting raster to vector", 75] # 4) seting the bounding box region = {} for b in os.popen("g.region -g"): b = b.strip() key,val = b.split("=") region[key] = val self.DataOutputs['bbox'] = [region['s'],region['e'],region['n'],region['w']] # 5) convert to vector if os.system("r.to.vect in=output out=output feature=area >&2"): return "Could not convert raster to vector" # for asynchronous process: self.status=["Exporting GML file", 95] # 6) export of vector map to GML if os.system( """v.out.ogr format=GML in=output dsn=output.gml olayer=output >&2"""): return "Could not export vector to GML" # setting output variables self.DataOutputs['vector'] = "output.gml" self.DataOutputs['raster'] = "output.tif" # end return
request=<?xml version='1.0' encoding='UTF-8' standalone='yes'?> <Execute service='wps' version='0.4.0' store='true' status='false' xmlns="http://www.opengeospatial.net/wps" xmlns:ows="http://www.opengeospatial.net/ows"> <ows:Identifier>addvalue</ows:Identifier> <DataInputs> <Input> <ows:Identifier>input</ows:Identifier> <ComplexValueReference reference='http://localhost/wps/data/soils.tif' /> </Input> <Input> <ows:Identifier>value</ows:Identifier> <LiteralValue>250</LiteralValue> </Input> <!-- Input> <ows:Identifier>bbox</ows:Identifier> <BoundingBoxValue> <BoundingBox> <LowerCorner>-1 -1</LowerCorner> <UpperCorner>10 10</UpperCorner> </BoundingBox> </BoundingBoxValue> </Input --> </DataInputs> </Execute>
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The ``Program'', below, refers to any such program or work, and a ``work based on the Program'' means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term ``modification''.) Each licensee is addressed as ``you''.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and ``any later version'', you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
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.
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.
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.
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.
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:
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.
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".
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.
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.
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.
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.
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.
This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -split 0 install.tex
The translation was initiated by Jachym Cepicky on 2006-10-11
Jachym Cepicky 2006-10-11