diff --git a/Docs/README.IO b/Docs/README.IO
index 6e838c6e9..38607916e 100644
--- a/Docs/README.IO
+++ b/Docs/README.IO
@@ -15,6 +15,50 @@ The general form of the command line option is as follows:
hz = number of times to process channel per second (floating
point values are ok.
+Generic Communction:
+
+ --generic=params
+
+ With this option it is possible to output a pre-configured
+ ASCII string using a predefined seperator. The configuration is
+ defined in an XML file located in the Protocol directiory of
+ the base package.
+
+ params can be:
+ serial port communication: serial,dir,hz,device,baud,protocol
+ socket communication: socket,dir,hz,machine,port,style,protocol
+ output to a file: file,dir,hz,filename,protocol
+
+
+ The confinfiguration file is defined as follows:
+
+
+
+
+
+
+
+
+
+
Serial Port Communication:
--nmea=serial,dir,hz,device,baud
diff --git a/Docs/README.Joystick b/Docs/README.Joystick
new file mode 100644
index 000000000..955bf3835
--- /dev/null
+++ b/Docs/README.Joystick
@@ -0,0 +1 @@
+Replaced by Docs/README.Joystick.html in the base package.
diff --git a/Docs/README.multiplayer b/Docs/README.multiplayer
new file mode 100644
index 000000000..ee081a139
--- /dev/null
+++ b/Docs/README.multiplayer
@@ -0,0 +1,72 @@
+The commands are of the form:
+
+--multiplay=in | out,Hz,destination address,destination port
+--callsign=a_unique_name
+
+
+Below are some examples of startup commands that demonstrate the use of the
+multiplayer facilities.
+
+For two players on a local network or across the internet:
+----------------------------------------------------------
+Player1:
+--multiplay=out,10,192.168.0.3,5500 --multiplay=in,10,192.168.0.2,5501
+--callsign=player1
+
+Player2:
+--multiplay=out,10,192.168.0.2,5501 --multiplay=in,10,192.168.0.3,5500
+--callsign=player2
+
+
+For multiple players on a local network:
+----------------------------------------
+Player1:
+--multiplay=out,10,255.255.255.255,5500
+--multiplay=in,10,255.255.255.255,5500 --callsign=player1
+
+Playern:
+--multiplay=out,10,255.255.255.255,5500
+--multiplay=in,10,255.255.255.255,5500 --callsign=playern
+
+Note that the callsign is used to identify each player in a multiplayer game
+so the callsigns must be unique. The multiplayer code ignores packets that
+are sent back to itself, as would occur with broadcasting when the rx and tx
+ports are the same.
+
+
+Multiple players sending to a single player:
+--------------------------------------------
+Player1:
+--multiplay=out,10,192.168.0.2,5500 --callsign=player1
+
+Player2:
+--multiplay=out,10,192.168.0.2,5500 --callsign=player2
+
+Player3:
+--multiplay=out,10,192.168.0.2,5500 --callsign=player3
+
+Player4 (rx only):
+--multiplay=in,10,192.168.0.2,5500 --callsign=player4
+
+This demonstrates that it is possible to have multiple instances of
+Flightgear that send to a single instance that displays all the traffic. This
+is the sort of implementation that we are considering for use as a tower
+visual simulator.
+
+
+For use with a server (when one is created):
+--------------------------------------------
+Player1:
+--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5500
+--callsign=player1
+
+Player2:
+--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5501
+--callsign=player2
+
+Playern:
+--multiplay=out,10,serveraddress,6000 --multiplay=in,10,myaddress,5502
+--callsign=playern
+
+The server would simply act as a packet forwarding mechanism. When it
+receives a packet, it sends it to all other active players.
diff --git a/Docs/README.sound b/Docs/README.sound
new file mode 100644
index 000000000..a180cec62
--- /dev/null
+++ b/Docs/README.sound
@@ -0,0 +1,62 @@
+
+ALSA surround sound (5.1) setup
+-------------------------------------
+(taken from http://floam.ascorbic.com/how-to/alsa5.1)
+
+Make a ~/.openalrc, we are telling OpenAL that we want surround sound and
+we want to use ALSA instead of OSS.
+
+(define speaker-num 4)
+(define devices '(alsa))
+(define alsa-out-device "surround40:0,0")
+
+
+ALSA and Arts
+-------------------------------------
+
+I'm using kernel 2.6.5 with alsa, my sound module is snd-intel8x0. When I ran
+fgfs, I'd get quite 'choppy' sound (wasn't smooth, there'd be a couple of
+breaks in the sound every second or so). Running arts, and starting fgfs with
+"artsdsp fgfs" (from the artsdsp website: "When an application is run under
+artsdsp all accesses to the /dev/dsp audio device are intercepted and mapped
+into aRts API calls. While the device emulation is not perfect, most
+applications work this way, albeit with some degradation in performance and
+latency.") would improve the situation, but it seemed to still be choppy.
+
+This command:
+echo "fgfs 0 0 direct" >/proc/asound/card0/pcm0p/oss
+
+(from the alsa kernel OSS emulation website:
+ "The direct option is used, as mentioned above, to bypass the automatic
+ conversion and useful for MMAP-applications")
+
+made my sound work beautifully when fgfs was run with artsdsp. Running without
+artsdsp however (with artsd suspended or killed), would give me no sound at all
+(which I find a bit strange)
+
+The following websites might help people with similar troubles:
+http://www.alsa-project.org/~iwai/OSS-Emulation.html
+http://www.arts-project.org/doc/handbook/artsdsp.html
+
+Computer info:
+
+kernel 2.6.5
+
+flightgear 0.9.4
+simgear 0.3.5
+plib 1.8.3
+
+soundcard is onboard an asus p4p800-e deluxe mobo (using snd-intel8x0), alsa, related modules from lsmod:
+Module Size Used by
+snd_pcm_oss 53252 1
+snd_mixer_oss 19968 1 snd_pcm_oss
+snd_intel8x0 33476 1
+snd_ac97_codec 63492 1 snd_intel8x0
+snd_pcm 97408 2 snd_pcm_oss,snd_intel8x0
+snd_timer 26112 1 snd_pcm
+snd_page_alloc 11396 2 snd_intel8x0,snd_pcm
+snd_mpu401_uart 7936 1 snd_intel8x0
+snd_rawmidi 24832 1 snd_mpu401_uart
+snd_seq_device 8324 1 snd_rawmidi
+snd 53892 9 snd_pcm_oss,snd_mixer_oss,snd_intel8x0,snd_ac97_codec,snd_pcm,snd_timer,snd_mpu401_uart,snd_rawmidi,snd_seq_device
+soundcore 10208 2 snd
diff --git a/Docs/README.xmlpanel b/Docs/README.xmlpanel
new file mode 100644
index 000000000..960dd2e63
--- /dev/null
+++ b/Docs/README.xmlpanel
@@ -0,0 +1,654 @@
+Users Guide to FlightGear panel configuration
+Version 0.7.7, May 16 2001
+Author: John Check
+
+This document is an attempt to describe the configuration of
+FlightGear flight simulator's aircraft panel display via XML. The
+information was culled from the fgfs-devel@flightgear.org mailing list
+and my experiences making alternate panels. Corrections and additions
+are encouraged.
+
+Some History:
+------------
+Older versions of FGFS had a hard coded display of instruments. This
+was a less than ideal state of affairs due to FGFS ability to use
+different aircraft models. Being primarily developed on UNIX type
+systems, a modular approach is taken towards the simulation. To date,
+most alternatives to the default Cessna 172 aircraft are the product
+of research institutions interested in the flight characteristics and
+not cosmetics. The result of this was that one could fly the X-15 or
+a Boeing 747 but be limited to C172 instrumentation.
+
+A rewrite of the panel display code was done around v0.7.5 by
+developer David Megginson allowing for configuration of the panel via
+XML to address this limitation. Some major changes and additions were
+made during the course of version 0.7.7 necessitating a rewrite and
+expansion of this document.
+
+
+About The Property Manager:
+--------------------------
+While not absolutely necessary in order to create aircraft panels,
+some familiarity with the property manager is beneficial....
+FlightGear provides a hierarchical representation of all aspects of
+the state of the running simulation that is known as the property
+tree. Some properties, such as velocities are read only. Others such
+as the frequencies to which the navcom radios are tuned or the
+position of control surfaces can be set by various means. FlightGear
+can optionally provide an interface to these properties for external
+applications such as Atlas, the moving map program, or even lowly
+telnet, via a network socket. Data can even be placed on a serial port
+and connected to, say a GPS receiver. Aside from its usefulness in a
+flight training context, being able to manipulate the property tree on
+a running copy of FG allows for switching components on the fly, a
+positive boon for panel authors. To see the property tree start FG
+with the following command line:
+
+fgfs --props=socket,bi,5,localhost,5500,tcp
+
+Then use telnet to connect to localhost on port 5500. You can browse
+the tree as you would a filesystem.
+
+XML and the Property Manager:
+----------------------------
+Panel instruments interface with the property tree to get/set values
+as appropriate. Properties for which FG doesn't yet provide a value
+can be created by simply making them up. Values can be adjusted using
+the telnet interface allowing for creation and testing of instruments
+while code to drive them is being developed.
+
+If fact, the XML configuration system allows a user to combine
+components such as flight data model, aircraft exterior model, heads
+up display, and of course control panel. Furthermore, such a
+preconfigured aircraft.xml can be included into a scenario with
+specific flight conditions. These can be manually specified or a FG
+session can be saved and/or edited and reloaded later. Options
+specified in these files can be overridden on the command line. For
+example:
+
+--prop:/sim/panel/path=Aircraft/c172/Panels/c172-panel.xml
+
+passed as an option, would override a panel specified elsewhere.
+Property tree options all have the same format, specify the node and
+supply it a value.
+
+The order of precedence for options is thus:
+
+Source Location Format
+------ -------- ------
+command line
+.fgfsrc Users home directory. command line options
+system.fgfsrc $FG_ROOT "" ""
+preferences.xml $FG_ROOT XML property list
+
+
+Loading Panels on the fly:
+-------------------------
+When editing a panel configuration, pressing Shift +F3 will reload the
+panel. If your changes don't seem to be taking effect, check the
+console output. It will report the success or failure of the panel
+reload*. Editing textures requires restarting FGFS so the new textures
+can be loaded. Panels can be switched on the fly by setting the
+/sim/panel/path property value and reloading.
+
+Regarding Window Geometry:
+-------------------------
+For the sake of simplicity the FGFS window is always considered to be
+1024x768 so all x/y values for instrument placement should relative to
+these dimensions. Since FG uses OpenGL 0,0 represents the lower left
+hand corner of the screen. Panels may have a virtual size larger than
+1024x768. Vertical scrolling is accomplished with
+Shift+F5/F6. Horizontal scrolling is via Shift+F7/F8. An offset should
+be supplied to set the default visible area. It is possible to place
+items to overlap the 3D viewport.
+
+Panel Architecture:
+-------------------
+All of the panel configuration files are XML-encoded* property lists.
+The root element of each file is always named . Tags are
+almost always found in pairs, with the closing tag having a slash
+prefixing the tag name, i.e . The exception is the tag
+representing an aliased property. In this case a slash is prepended to
+the closing angle bracket. (see section Aliasing)
+
+The top level panel configuration file is composed of a , a
+ texture and zero or more .Earlier versions
+required instruments to have a unique name and a path specification
+pointing to the instruments configuration file.
+
+[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
+[ Absolute paths may be used.Comments are bracketed with . ]
+
+Old style instrument call in top level panel.xml:
+------------------------------------------------
+
+ Aircraft/c172/Instruments/clock.xml
+ 110
+ 320
+ 72
+ 72
+
+
+The difference between the old and new styles, while subtle, is rather
+drastic. The old and new methods are indeed incompatible. I cover the
+old style only to acknowledge the incompatibility. This section will
+be removed after the next official FGFS release.
+
+New Style Example Top Level Panel Config:
+----------------------------------------
+
+ Example Panel
+ Aircraft/c172/Panels/Textures/panel-bg.rgb
+ 1024
+ 768
+ -305
+ 172
+
+
+
+
+ Chronometer
+ 150
+ 645
+ 72
+ 72
+
+
+
+
+
+
+
+Indexed Properties
+------------------
+This is a lot to do with the compatibility break so lets get it out of
+the way. The property manager now assigns incremental indices to
+repeated properties with the same parent node, so that
+
+
+ 1
+ 2
+ 3
+
+
+shows up as
+
+ /x[0] = 1
+ /x[1] = 2
+ /x[2] = 3
+
+This means that property files no longer need to make up a separate
+name for each item in a list of instruments, layers, actions,
+transformations, or text chunks. In fact, the new panel I/O code now
+insists that every instrument have the XML element name "instrument",
+every layer have the name "layer", every text chunk have the name
+"chunk", every action have the name "action", and every transformation
+have the name "transformation" -- this makes the XML more regular (so
+that it can be created in a DTD-driven tool) and also allows us to
+include other kinds of information (such as doc strings) in the lists
+without causing confusion.
+
+Inclusion:
+----------
+The property manager now supports file inclusion and aliasing.
+Inclusion means that a node can include another property file as if it
+were a part of the current file. To clarify how inclusion works,
+consider the following examples:
+
+If bar.xml contains
+
+
+ 1
+
+ 2
+
+
+
+then the declaration
+
+
+
+
+is exactly equivalent to
+
+
+ 1
+
+ 2
+
+
+
+However, it is also possible to selectively override properties in the
+included file. For example, if the declaration were
+
+
+ 3
+
+
+then the property manager would see
+
+
+ 3
+
+ 2
+
+
+
+with the original 'a' property's value replaced with 3.
+
+This new inclusion feature allows property files to be broken up and
+reused arbitrarily -- for example, there might be separate cropping
+property lists for commonly-used textures or layers, to avoid
+repeating the information in each instrument file.
+
+
+Aliasing
+--------
+Properties can now alias other properties, similar to a symbolic link
+in Unix. When the target property changes value, the new value will
+show up in the aliased property as well. For example,
+
+
+ 3
+
+
+
+will look the same to the application as
+
+
+ 3
+ 3
+
+
+except that when foo changes value, bar will change too.
+
+
+The combination of inclusions and aliases is very powerful, because it
+allows for parameterized property files. For example, the XML file for
+the NAVCOM radio can include a parameter subtree at the start, like
+this:
+
+
+
+ /radios/comm1/frequencies/selected
+ /radios/nav1/frequencies/selected
+
+
+ ...
+
+
+ number-value
+
+
+
+ ...
+
+
+Now, the same instrument file can be used for navcomm1 and navcomm2,
+for example, simply by overriding the parameters at inclusion:
+
+
+
+ /radios/comm1/frequencies/selected
+ /radios/nav1/frequencies/selected
+
+
+
+
+
+ /radios/comm2/frequencies/selected
+ /radios/nav2/frequencies/selected
+
+
+
+Instrument Architecture:
+-----------------------
+Instruments are defined in separate configuration files. An instrument
+consists of a base width and height, one or more stacked layers, and
+zero or more actions. Base dimensions are specified as follows:
+
+
+ Airspeed Indicator
+ 128
+ 128
+
+
+Height and width can be overriden in the top level panel.xml by
+specifying and . Transformations are caculated against the base
+size regardless of the display size. This ensures that instruments
+remain calibrated
+
+Textures:
+--------
+FG uses red/green/blue/alpha .rgba files for textures. Dimensions for
+texture files should be power of 2 with a maximum 8:1 aspect ratio.
+The lowest common denominator for maximum texture size is 256 pixels.
+This is due to the limitations of certain video accelerators, most
+notably those with 3Dfx chipset such as the Voodoo2.
+
+Instrument Layers**:
+-------------------
+The simplest layer is a . These can be combined in layers
+
+
+A texture layer looks like this:
+
+
+ face
+
+ Aircraft/c172/Instruments/Textures/faces-2.rgb
+ 0
+ 0.51
+ 0.49
+ 1.0
+
+
+
+The texture cropping specification is represented as a decimal. There
+is a table at the end of this document for converting from pixel
+coordinates to percentages.
+
+This particular layer, being a gauge face has no transformations
+applied to it. Layers with that aren't static *must* include and
+ parameters to be visible.
+
+ May be either text or switch..
+
+switch
+A switch layer is composed of two or more nested layers and will
+display one of the nested layers based on a boolean property. For a
+simple example of a switch see
+$FG_ROOT/Aircraft/c172/Instruments/brake.xml.
+
+
+ Brake light
+ switch
+ /controls/brakes
+
+ on
+
+ Aircraft/c172/Instruments/Textures/brake.rgb
+ 0.25
+ 0.0
+ 0.5
+ 0.095
+
+ 64
+ 24
+
+
+ off
+
+ Aircraft/c172/Instruments/Textures/brake.rgb
+ 0.0
+ 0.0
+ 0.25
+ 0.095
+
+ 64
+ 24
+
+
+
+Switches can have more than 2 states. This requires nesting one switch
+inside another. One could make, for example, a 3 color LED by nesting
+switch layers.
+
+text
+A text layer may be static, as in a label, generated from a property
+or a combination of both. This example is a switch that contains both
+static and dynamic text:
+
+
+ display
+ text
+ 12
+
+ 1.0
+ 0.5
+ 0.0
+
+
+
+ number-value
+ /radios/nav1/dme/distance
+ 0.00053995680
+ %5.1f
+
+
+
+
+ display
+ text
+ 10
+
+ 1.0
+ 0.5
+ 0.0
+
+
+
+ literal
+ ---.--
+
+
+
+
+
+Transformations:
+---------------
+A transformation is a rotation, an x-shift, or a
+y-shift. Transformations can be static or they can be based on
+properties. Static rotations are useful for flipping textures
+horizontally or vertically. Transformations based on properties are
+useful for driving instrument needles. I.E. rotate the number of
+degrees equal to the airspeed. X and y shifts are relative to the
+center of the instrument. Each specified transformation type takes an
+. Offsets are relative to the center of the instrument. A
+shift without an offset has no effect. For example, let's say we have
+a texure that is a circle. If we use this texture in two layers, one
+defined as having a size of 128x128 and the second layer is defined as
+64x64 and neither is supplied a shift and offset the net result
+appears as 2 concentric circles.
+
+
+About Transformations and Needle Placement:
+------------------------------------------
+
+When describing placement of instrument needles, a transformation
+offset must be applied to shift the needles fulcrum or else the needle
+will rotate around it's middle. The offset will be of x-shift
+or y-shift depending on the orientation of the needle section in the
+cropped texture.
+
+This example comes from the altimeter.xml
+
+
+ long needle (hundreds)
+
+ Aircraft/c172/Instruments/Textures/misc-1.rgb
+ 0.8
+ 0.78125
+ 0.8375
+ 1.0
+
+ 8
+ 56
+
+
+ rotation
+ /steam/altitude
+ 100000.0
+ 0.36
+
+
+ y-shift
+ 24.0
+
+
+
+
+This needles has its origin in the center of the instrument. If the
+needles fulcrum was towards the edge of the instrument, the
+transformations to place the pivot point must precede those which
+drive the needle,
+
+Interpolation
+-------------
+Non linear transformations are now possible via the use of
+interpolation tables.
+
+
+ ...
+
+
+ 0.0
+ 0.0
+
+
+ 10.0
+ 100.0
+
+
+ 20.0
+ -5.0
+
+
+ 30.0
+ 1000.0
+
+
+
+
+Of course, interpolation tables are useful for non-linear stuff, as in
+the above example, but I kind-of like the idea of using them for
+pretty much everything, including non-trivial linear movement -- many
+instrument markings aren't evenly spaced, and the interpolation tables
+are much nicer than the older min/max/scale/offset stuff and should
+allow for a more realistic panel without adding a full equation parser
+to the property manager.
+
+If you want to try this out, look at the airspeed.xml file in the base
+package, and uncomment the interpolation table in it for a very funky,
+non-linear and totally unreliable airspeed indicator.
+
+
+Actions:
+-------
+An action is a hotspot on an instrument where something will happen
+when the user clicks the left or center mouse button. Actions are
+always tied to properties: they can toggle a boolean property, adjust
+the value of a numeric property, or swap the values of two properties.
+The x/y placement for actions specifies the origin of the lower left
+corner. In the following example the first action sets up a hotspot
+32 pixels wide and 16 pixels high. It lower left corner is placed 96
+pixels (relative to the defined base size of the instrument) to the
+right of the center of the instrument. It is also 32 pixels below the
+centerline of the instrument. The actual knob texture over which the
+action is superimposed is 32x32. Omitted here is a second action,
+bound to the same property, with a positive increment value. This
+second action is placed to cover the other half of the knob. The
+result is that clicking on the left half of the knob texture decreases
+the value and clicking the right half increases the value. Also
+omitted here is a second pair of actions with the same coordinates but
+a larger increment value. This second pair is bound to a different
+mouse button. The net result is that we have both fine and coarse
+adjustments in the same hotspot, each bound to a different mouse
+button.
+
+These examples come from the radio stack:
+
+
+ small nav frequency decrease
+ adjust
+
+ 96
+ -32
+ 16
+ 32
+ /radios/nav1/frequencies/standby
+ -0.05
+ 108.0
+ 117.95
+ 1
+
+
+ swap nav frequencies
+ swap
+
+ 48
+ -32
+ 32
+ 32
+ /radios/nav1/frequencies/selected
+ /radios/nav1/frequencies/standby
+
+
+ ident volume on/off
+ adjust
+
+ 40
+ -24
+ 16
+ 16
+ /radios/nav1/ident
+ 1.0
+ 0
+ 1
+ 1
+
+
+
+More About Textures:
+-------------------
+As previously stated, the usual size instrument texture files in FGFS
+are 256x256 pixels, red/green/blue/alpha format. However the mechanism
+for specifying texture cropping coordinates is decimal in nature. When
+calling a section of a texture file the 0,0 lower left convention is
+used. There is a pair of x/y coordinates defining which section of
+the texture to use.
+
+The following table can be used to calculate texture cropping
+specifications.
+
+# of divisions | width in pixels | decimal specification
+per axis
+ 1 = 256 pixels 1
+ 2 = 128 pixels, 0.5
+ 4 = 64 pixels, 0.25
+ 8 = 32 pixels, 0.125
+ 16 = 16 pixels, 0.0625
+ 32 = 8 pixels, 0.03125
+ 64 = 4 pixels, 0.015625
+ 128 = 2 pixels, 0.0078125
+
+A common procedure for generating gauge faces is to use a vector
+graphics package such as xfig, exporting the result as a postscript
+file. 3D modeling tools may also be used and I prefer them for pretty
+items such as levers, switches, bezels and so forth. Ideally, the
+size of the item in the final render should be of proportions that fit
+into the recommended pixel widths. The resulting files can be
+imported into a graphics manipulation package such as GIMP, et al for
+final processing.
+
+How do I get my panels/instruments into the base package?
+-------------------------------------------------------
+Cash bribes always help ;) Seriously though, there are two main
+considerations. Firstly, original artwork is a major plus since you
+as the creator can dictate the terms of distribution.All Artwork must
+have a license compatible with the GPL. Artwork of unverifiable
+origin is not acceptable. Secondly, texture sizes must meet the
+lowest common denominator of 256e2 pixels. Artwork from third parties
+may be acceptable if it meets these criteria.
+
+* If there are *any* XML parsing errors, the panel will fail to load,
+ so it's worth downloading a parser like Expat (http://www.jclark.com/xml/)
+ for checking your XML. FlightGear will print the location of errors, but
+ the messages are a little cryptic right now.
+
+** NOTE: There is one built-in layer -- for the mag compass ribbon --
+ and all other layers are defined in the XML files. In the future,
+ there may also be built-in layers for special things like a
+ weather-radar display or a GPS (though the GPS could be handled with
+ text properties).
+
diff --git a/Docs/README.xmlsound b/Docs/README.xmlsound
new file mode 100644
index 000000000..9307d64ef
--- /dev/null
+++ b/Docs/README.xmlsound
@@ -0,0 +1,272 @@
+Users Guide to FlightGear sound configuration
+Version 0.7.11, apr 27 2002
+Author: Erik Hofman
+
+This document is an attempt to describe the configuration of
+FlightGear flight simulator's aircraft sound via XML.
+
+Some History:
+------------
+Older versions of FGFS had a hard coded audio layer. This was a
+than ideal state of affairs due to FGFS ability to use different
+aircraft models. Being primarily developed on UNIX type systems, a
+modular approach is taken towards the simulation. To date, most
+alternatives to the default Cessna 172 aircraft are the product
+of research institutions interested in the flight characteristics and
+not cosmetics. The result of this was that one could fly the X-15 or
+a Boeing 747 but be limited to C172 sounds.
+
+A rewrite of the sound code was done around v0.7.10 by Erik Hofman
+allowing for configuration of the sounds via XML to address this
+limitation.
+
+Sound Architecture:
+------------------
+All of the sound configuration files are XML-encoded* property lists.
+The root element of each file is always named . Tags are
+almost always found in pairs, with the closing tag having a slash
+prefixing the tag name, i.e . The exception is the tag
+representing an aliased property. In this case a slash is prepended to
+the closing angle bracket. (see section Aliasing)
+
+The top level sound configuration file is composed of a , a
+, a sound file and zero or more and/or
+definitions.
+
+[ Paths are relative to $FG_ROOT (the installed location of FGFS data files.) ]
+[ Absolute paths may be used.Comments are bracketed with . ]
+
+A limited sound configuration file would look something like this:
+
+
+
+
+ engine
+ Sounds/wasp.wav
+ looped
+
+ /engines/engine/running
+
+
+ /engines/engine/mp-osi
+ 0.005
+ 0.15
+ 0.5
+ 0.15
+
+
+ /engines/engine/rpm
+ 0.0012
+ 0.3
+ 5.0
+ 0.3
+
+
+
+
+
+This would define an engine sound event handler for a piston engine driven
+aeroplane. The sound representing the engine is located in $FG_ROOT/Sounds
+and is named wasp.wav. The event is started when the property
+/engines/engine/running becomes non zero.
+
+When that happens, the sound will be played looped (see ) until the
+property returns zero again. As you can see the volume is mp-osi dependant,
+and the pitch of the sound depents on the engine rpm.
+
+Configuration description:
+-------------------------
+
+
+ Named FX subtree living under /sim/sound
+
+ < ... >
+ This is the event seperator. The text inside the brackets
+ can be anything. Bit it is adviced to give it a meaningfull name
+ like: crank, engine, rumble, gear, squeal, flap, wind or stall
+
+ The value can be defined multiple times, thus anything which is
+ related may have the same name (grouping them together).
+
+
+ This defines the name of the event. This name is used internally
+ and, although it can me defined multiple times in the same file,
+ should normally have an unique value.
+
+ Multiple definitions of the same name will allow multiple sections
+ to interfere in the starting and stopping of the sample.
+
+ This method can't be used to controll the pitch or volume of the
+ sample, but instead multiple volume or pitch section should be
+ included inside the same event.
+
+ The types "raise" and "fall" will stop the playback of the sample
+ regardless of any other event. This means that when the type "raise"
+ is supplied, sample playback will stop when the event turns false.
+ Using the type "fall" will stop playback when the event turns true.
+
+ IMPORTANT:
+ If the trigger is used for anything else but stopping the sound
+ at a certain event, all sections with the same name *should* have
+ exactly the same sections for everything but property and type.
+
+ In the case of just stopping the sample at a certain event, the
+ sections for path, volume and pitch may be omitted.
+
+
+ This defined th path to the sound file. The path is relative to the
+ FlightGear root directory but could be specified absolute.
+
+
+ Define a condition that triggers the event.
+ For a complete description of the FlightGear conditions,
+ please read docs-mini/README.conditions
+
+ An event should define either a condition or a property.
+
+
+ Define which property triggers the event, and reffers to a node
+ in the FlightGear property tree. Action is taken when the property
+ is non zero.
+
+ A more sophisticated mechanism to trigger the event is described
+ in
+
+
+ This defines how the sample should be played:
+
+ once: the sample is played once.
+ this is the default.
+
+ looped: the sample plays continuesly,
+ until the event turns false.
+
+ in-transit: the sample plays continuesly,
+ while the property is changing its value.
+
+ /
+ Volume or Pitch definition. Currently there may be up to 5
+ volume and up to 5 pitch definitions defined within one sound
+ event. Normally all offset values are added together and the
+ results after property calculations will be miltplied.
+ A special condition occurs when the value of factor is negative,
+ in which case the offset doesn't get added to the other offset values
+ but instead will be used in the multiplication section.
+
+
+ Defins which property supplies the value for the calculation.
+ Either a or an should be defined.
+ The value is treatened as a floating point number.
+
+
+ Defins which internal variable should be used for the calculation.
+ The value is treatened as a floating point number.
+ The following internals are available at this time:
+
+ dt_play: the number of seconds since the sound started playing.
+
+ dt_stop: the number of seconds after the sound has stopped.
+
+
+ Defines the function that should be used upon the property
+ before it is used for calculating the net result:
+
+ lin: lineair handling of the property value.
+ this is the default.
+
+ ln: convert the property value to a natural logarithmic
+ value before scaling it. Anything below 1 will return
+ zero.
+
+ log: convert the property value to a true logarithmic
+ value before scaling it. Anything below 1 will return
+ zero.
+
+ inv: inverse lineair handling (1/x).
+
+ abs: absolute handling of the value (always positive).
+
+ sqrt: calculate the square root of the absolute value
+ before scaling it.
+
+
+ Defines the multiplication factor for the property value.
+ A special condition is when scale is defined as a negative
+ value. In this case the result of || *
+
+
+ The initial value for this sound. This value is also used as an
+ offset value for calulating the end result.
+
+
+ Minimum allowed value.
+ This is usefull if sounds start to sound funny. Anything lower
+ will be truncated to this value.
+
+
+ Maximum allowed value.
+ This is usefull if sounds gets to loud. Anything higher will be
+ truncated to this value.
+
+
+ Specify the position of the sounds source relative to the
+ pilot's ears. The coordinate system used is a right hand
+ coordinate system where -X = left, +X = right, -Y = down, +Y =
+ up, -Z = forward, +Z = aft. Distances are in meters.
+
+
+ X dimension offset
+
+
+ Y dimension offset
+
+
+ Z dimension offset
+
+
+ Set a reference distance of sound in meters. This is the
+ distance where the gain/volume will be halved. This can be
+ useful for limiting cockpit sounds to the cockpit.
+
+
+ Set the maximum audible distance for the sound in meters.
+ This can be useful for limiting cockpit sounds to the cockpit.
+
+
+Creating a configrationfile:
+---------------------------
+
+To make things easy, there is a default falue for most entries to allow a
+sane configuration when a certain entry is omitted.
+
+Default values are:
+
+type: lin
+factor: 1.0
+offset: 0.0 for volume, 1.0 for pitch
+min: 0.0
+max: 0.0 (don't check)
+
+
+
+Calculations are made the following way (for both pitch and volume):
+
+ value = 0;
+ offs = 0;
+
+ for (n = 0; n < max; n++) {
+ if (factor < 0)
+ {
+ value += offset[n] - abs(factor[n]) * function(property[n]);
+ }
+ else
+ {
+ value += factor[n] * function(property[n]);
+ offs += offset[n];
+ }
+ }
+
+ volume = offs + value;
+
+where function can be one of: lin, ln, log, inv, abs or sqrt
diff --git a/Docs/README.xmlsyntax b/Docs/README.xmlsyntax
new file mode 100644
index 000000000..6c55c1969
--- /dev/null
+++ b/Docs/README.xmlsyntax
@@ -0,0 +1,186 @@
+XML IN FIFTEEN MINUTES OR LESS
+
+Written by David Megginson, david@megginson.com
+Last modified: $Date$
+
+This document is in the Public Domain and comes with NO WARRANTY!
+
+
+1. Introduction
+---------------
+
+FlightGear uses XML for much of its configuration. This document
+provides a minimal introduction to XML syntax, concentrating only on
+the parts necessary for writing and understanding FlightGear
+configuration files. For a full description, read the XML
+Recommendation at
+
+ http://www.w3.org/TR/
+
+This document describes general XML syntax. Most of the XML
+configuration files in FlightGear use a special format called
+"Property Lists" -- a separate document will describe the specific
+features of the property-list format.
+
+
+2. Elements and Attributes
+--------------------------
+
+An XML document is a tree structure with a single root, much like a
+file system or a recursive, nested list structure (for LISP fans).
+Every node in the tree is called an _element_: the start and end of
+every element is marked by a _tag_: the _start tag_ appears at the
+beginning of the element, and the _end tag_ appears at the end.
+
+Here is an example of a start tag:
+
+
+
+Here is an example of an end tag:
+
+
+
+Here is an example of an element:
+
+ Hello, world!
+
+The element in this example contains only data element, so it is a
+leaf node in the tree. Elements may also contain other elements, as
+in this example:
+
+
+ Hello, world!
+ Goodbye, world!
+
+
+This time, the 'bar' element is a branch that contains other, nested
+elements, while the 'foo' elements are leaf elements that contain only
+data. Here's the tree in ASCII art (make sure you're not using a
+proportional font):
+
+ bar +-- foo -- "Hello, world!"
+ |
+ +-- foo -- "Goodbye, world!"
+
+There is always one single element at the top level: it is called the
+_root element_. Elements may never overlap, so something like this is
+always wrong (try to draw it as a tree diagram, and you'll understand
+why):
+
+
+
+Every element may have variables, called _attributes_, attached to
+it. The attribute consists of a simple name=value pair in the start
+tag:
+
+ Hello, world!
+
+Attribute values must be quoted with '"' or "'" (unlike in HTML), and
+no two attributes may have the same name.
+
+There are rules governing what can be used as an element or attribute
+name. The first character of a name must be an alphabetic character
+or '_'; subsequent characters may be '_', '-', '.', an alphabetic
+character, or a numeric character. Note especially that names may not
+begin with a number.
+
+
+3. Data
+-------
+
+Some characters in XML documents have special meanings, and must
+always be escaped when used literally:
+
+ < <
+ & &
+
+Other characters have special meanings only in certain contexts, but
+it still doesn't hurt to escape them:
+
+ > >
+ ' '
+ " "
+
+Here is how you would escape "x < 3 && y > 6" in XML data:
+
+ x < 3 && y > 6
+
+Most control characters are forbidden in XML documents: only tab,
+newline, and carriage return are allowed (that means no ^L, for
+example). Any other character can be included in an XML document as a
+character reference, by using its Unicode value; for example, the
+following represents the French word "cafe" with an accent on the
+final 'e':
+
+ café
+
+By default, 8-bit XML documents use UTF-8, **NOT** ISO 8859-1 (Latin
+1), so it's safest always to use character references for characters
+above position 127 (i.e. for non-ASCII).
+
+Whitespace always counts in XML documents, though some specific
+applications (like property lists) have rules for ignoring it in some
+contexts.
+
+
+4. Comments
+-----------
+
+You can add a comment anywhere in an XML document except inside a tag
+or declaration using the following syntax:
+
+
+
+The comment text must not contain "--", so be careful about using
+dashes.
+
+
+5. XML Declaration
+------------------
+
+Every XML document may begin with an XML declaration, starting with
+"". Here is an example:
+
+
+
+The XML declaration must always give the XML version, and it may also
+specify the encoding (and other information, not discussed here).
+UTF-8 is the default encoding for 8-bit documents; you could also try
+
+
+
+to get ISO Latin 1, but some XML parsers might not support that
+(FlightGear's does, for what it's worth).
+
+
+6. Other Stuff
+--------------
+
+There are other kinds of things allowed in XML documents. You don't
+need to use them for FlightGear, but in case anyone leaves one lying
+around, it would be useful to be able to recognize it.
+
+XML documents may contain different kinds of declarations starting
+with "":
+
+
+
+
+
+
+
+and so on. They may also contain processing instructions, which look
+a bit like the XML declaration:
+
+
+
+Finally, they may contain references to _entities_, like the ones used
+for escaping special characters, but with different names (we're
+trying to avoid these in FlightGear):
+
+ &chapter1;
+
+ &myname;
+
+
+Enjoy.