by Laura Bottelier
This document describes the Glass Cockpit Library (libGC) that is developed for the Airbus A340 Glass Cockpit Project (a340gc). And is intended as an reference manual and specification draft for the Glass Cockpit Library.
This is edition 1 that applies to version 0.3 of libGC.
Copyright 2001-2013 Laura Bottelier
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy, distribute and / or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being all sections, with the Front-Cover Texts being "libGC Glass Cockpit Library by Laura Bottelier", and with the Back-Cover Texts stating this license text.
A copy of the license is included in the section entitled "GNU Free Documentation License".
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.
The Glass Cockpit Library - libGC is free software; you can redistribute it and / or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.
The Glass Cockpit Library - libGC is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should receive a copy of the GNU General Public License along with The Glass Cockpit Library - libGC; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
The Glass Cockpit Library (hereafter only referred to as libGC) is created for the Airbus A340 Glass Cockpit (a340gc) which is an Open Source project. The a340gc project is part of the Airbus A340 simulator project of the IRADIS Foundation.
The goal of libGC is to create a free framework that can be used to build an glass cockpit upon.
The Glass Cockpit Library (libGC) provides the basic framework for building an glass cockpit. The preliminary version described here will need additional C++ code to implement the glass cockpit. Later versions of libGC will be able to compile the glass cockpit from an intermediate language. Either implemented as an widget set or as a pre compiled descriptive language.
The configuration file mechanism defined by the libGC is based on a sectionalised file format. This allows storage of configuration data of which the contents and layout can be unknown to libGC and its components like the DIOM.
Each section starts on a new line. The first character must be an '[' and the last character on the line must be an ']'. A section name is located in between and can contain all characters except line break characters.
Example:
[name of section] section data lines follow [second section] with one data line
The libGC provides functions to the glass cockpit application to open sections by name, read lines, and split a data line into a key and value pair on any character.
int cf_openSection(FILE *file, const char *sSection);
This function searches for a section with the specified name in the opened file specified by the file parameter.
Return value: 0 - Section could not be found in file 1 - Section found and opened for reading
char *cf_readline(FILE *file, char* sLine, int iLineSize);
This function reads one line from the currently opened section and places the data in the buffer specified by the sLine parameter up to iLineSize characters. Lines are read until the end of a section or the end of the file. All trailing white spaces, cr, and lf characters are removed.
Return value: NULL - No more lines in section sLine - Line has been read
char *cf_splitValuePair(char *sLine, char *sSeperator);
This function tries to spilt the line specified to by the sLine parameter into an key and value pair separated by any of the characters specified by the sSeperator parameter. All leading white spaces of both key and value are removed.
Return value: NULL - sLine is NULL Empty string - key and value pair could not be split string - the spilt value, sLine now contains the key.
libGC provides a minimal set of functions to provide cross platform access to BSD socket based networking services.
int net_openSocket(int domain, int type, int protocol);
This function opens a network socket for the specified type of network and protocol. If required by the platform the network services are started before the socket is opened if this is the first socket opened.
Return value: -1 is returned if an error occurs; otherwise the return value is a descriptor referencing the socket.
Example: // Open a TCP-UDP socket int socket = net_openSocket(PF_INET, SOCK_DGRAM, IPPROTO_UDP);
int net_closeSocket(int iSocket);
This function closes the specified network socket. If required by the platform the network services are cleanup if this is the last socket in use.
Return value: 0 - The socket is closed -1 - An error occurred while closing the socket
The information that is displayed on glass cockpit is driven by an simulator independent distribution capable manner. The Data Input Output Module (hereafter DIOM) forms an abstract layer / interface between the Glass Cockpit and the simulator / craft.
To accomplish this the DIOM provide methods to check, read, and write to variables. The first DIOM implementation will do this at runtime using an variable lookup table. Later versions will be capable of generating pre-compiled code from an descriptive language and tokenised C code. For backward compatibility it may be possible that the tokens used for this pre-compilation process are the first version DIOM calls.
The DIOM takes the name of the DIOM-DL and optionally not yet
defined general settings from the DIOM section of the
specified configuration file.
[diom] diom-dl rddp
This section describes the software interface for the data input / output modules.
bool diom_init(); bool diom_init(const char *configfile, const char *searchpath); int diom_error(); const char *diom_errorString();
This function initialises the data input / output module.
The configuration file is parsed and the DIOM-DL specified in
the configuration file is loaded and executed. The DIOM-DL is
first searched for in the current directory. If the DIOM-DL
couldn't be found; the searchpath parameter is used.
The search path contains zero to more directories to search.
Each directory must be separated by a colon ':' character.
Depending on the platform the DIOM-DL specified in the config file is sought as is and with either the file extension '.so' or '.dll' appended to it.
The diom_error and diom_errorString function
return the reason of the failed diom_init.
Return value: FALSE - failed to initialise TRUE - initialise Ok
bool diom_variableExists(const char *varname); bool diom_variableExists(int varid);
This function check if the specified variable is known to the DIOM.
Return value: FALSE - Variable is not known to the DIOM TRUE - Variable is known by the DIOM
typedef int diomvar_t; diomvar_t diom_loadVariable(const char *varname);
The diomvar_t type is used to hold the internal reference to the variable. (Note this internal reference does not equal the DDT variable ID)
Use the diom_loadVariable to get a reference to the variable that can be used to retrieve and manipulate the value of the variable.
Return value: The reference number this variable can be referenced by. -1 - Variable is not known to the DIOM
typedef enum {
DIOMbool,
DIOMint,
DIOMfloat,
DIOMdouble,
DIOMstring
} diomtype_t;
diomtype_t diom_variableType(int varid);
This function returns the type of the variable.
Return value: The type of the variable -1 - Variable is not known to the DIOM
[type] diom_defaultValue[Type](int varid);
This function returns the default value for the variable.
Replace [type] with the desired type for this variable.
Return value: The default value for the variable
Example:
int idAltitude = diom_variableID("altitude");
float fAltitudeDef = diom_defaultValueFloat(idAltitude);
printf("The default altitude is %f\n", fAltitudeDef);
[type] diom_minimalValue[type](int varid);
This function returns the minimal value for the variable.
Replace [type] with the desired type for this variable. Note that the boolean type doesn't have a minimal and maximal value.
Return value: The minimal value for the variable
Example:
int idFlaps = diom_variableID("flaps");
float fFlapsMin = diom_minimalValueFloat(idFlaps);
printf("The minimal flap position is %f\n", fAltitudeMin);
[type] diom_maximalValue[type](int varid);
This function returns the maximal value for the variable.
Replace [type] with the desired type for this variable. Note that the boolean type doesn't have a minimal and maximal value.
Return value: The maximal value for the variable
Example:
int idFlaps = diom_variableID("flaps");
float fFlapsMax = diom_maximalValueFloat(idFlaps);
printf("The maximal flap position is %f\n", fAltitudeMax);
[type] diom_getValue[type](int varid);
This function returns the current value for the variable.
Replace [type] with the desired type for this variable.
Return value: The current value for the variable
Example:
int idMasterWarning = diom_variableID("master_warning");
bool bMasterWanring = diom_getValueBoolean(idMasterWarning);
printf("MasterWarning is currently %u\n", bMasterWarning);
void diom_setValue[type](int varid, [type] value);
This function updates the current value for the variable.
Replace [type] with the desired type for this variable.
Example:
int idMasterWarning = diom_variableID("master_warning");
diom_setValueBoolean(idMasterWarning, true);
printf("MasterWarning is now active\n");
Most of the functionality of the DIOM is implemented in the DIOM-Dynamic Library hereafter called DIOM-DL. Every DIOM-DL is a dynamic linked library (.so or .dll file) which exports the following functions:
int openDIOMDL(const char*sConfigFileName); void closeDIOMDL(); diom_entry_t *loadVariableByName(const char*sName); diom_entry_t *loadVariableByID(int iID);
The diom_entry_t structure holds all information about a variable and 2 pointers for a get and set function. The diom_entry_t structure is allocated and filled by the loadVariableByName or loadVariableByID function.
struct diom_entry_t;
typedef void *getValueProc_t(diom_entry_t *entry);
typedef void setValueProc_t(diom_entry_t *entry, void *data);
typedef struct diom_entry_t {
int iID;
char * sName;
diomvar_t tType;
void * pCurrent;
void * pDefault;
void * pMinimal;
void * pMaximal;
bool bNew;
getValueProc_t * getValue;
setValueProc_t * setValue;
} diom_entry_t;
int openDIOMDL(const char*sConfigFileName);
When a DIOM-DL is loaded by the DIOM the openDIOMDL is called with the name of the configuration file. The DIOM-DL may use this configuration file to load its settings or get the name of its own configuration file. There are no restriction on the keywords used.
Return value: -1 - failed to initialise 0 - initialise Ok
Example:
float fValue;
int openDIOMDL(const char*sConfigFileName)
{
printf("DIOM-DL Sine is loaded\n");
return 0;
}
void closeDIOMDL()
{
}
diom_entry_t *loadVariableByName(const char*sName); diom_entry_t *loadVariableByID(int iID);
When the glass cockpit program requests for an variable the DIOM first looks if the variable is already known to the DIOM. If not the DIOM calls the loadVariableByName or loadVariableByID function of the DIOM-DL. Depending on if the glass cockpit program asked for an variable by name or by id.
The DIOM-DL should allocate memory (using malloc) for a new diom_entry_t structure and fill its members. Or when the DIOM-DL doesn't know the variable return NULL.
The DIOM-DL is free to allocate more space for internal use than the space needed for the diom_entry_t structure. The DIOM-DL should allocate the space needed for the diom_entry_t structure and the sName, pDefault, pMimimal, and pMaximal fields in one malloc. The sName, pDefault, pMimimal, and pMaximal fields should point to the end of the space allocated so all memory is freed in one free() call.
Return value: NULL - failed to load variable Pointer to allocated en filled diom_entry_t structure.
Example:
diom_entry_t *createEntry(const char*sName, int iID)
{
int iSize = sizeof(diom_entry_t) + strlen(sName)+1 + sizeof(float)*4;
diom_entry_t *entry = (diom_entry_t*)malloc(iSize);
entry->iID = iID;
entry->sName = (char*)entry+sizeof(diom_entry_t);
entry->tType = DIOMfloat;
entry->pCurrent = (char*)entry+iSize-sizeof(float)*1;
entry->pDefault = (char*)entry+iSize-sizeof(float)*2;
entry->pMinimal = (char*)entry+iSize-sizeof(float)*3;
entry->pMaximal = (char*)entry+iSize-sizeof(float)*4;
entry->bNew = false;
entry->getValue = getValue;
entry->setValue = setValue;
*(float*)entry->pCurrent = 0.0;
*(float*)entry->pDefault = 0.0;
*(float*)entry->pMinimal = -1.0;
*(float*)entry->pMaximal = 1.0;
strcpy(entry->sName, sName);
return entry;
}
diom_entry_t *loadVariableByName(const char*sName)
{
return createEntry(sName, 0);
}
diom_entry_t *loadVariableByID(int iID)
{
return createEntry("", iID);
}
void *getValue(diom_entry_t *entry); void setValue(diom_entry_t *entry, void *data);
Each of the diom_entry_t structures have pointers to a getValue and a setValue function. Whenever the glass cockpit program asks the DIOM for a current value or to alter the correct value these functions are called.
The getValue function should return the current value for the variable. This can either be done by looking it up somewhere or by using some of the extra allocated space in the diom_entry_t structure.
The setValue function should process, write, or send the new value pointer to by the data parameter or save it in the extra allocated space in the diom_entry_t structure.
Example:
void *getValue(diom_entry_t *entry)
{
float *fIndex = (float*)entry->pCurrent;
fValue = sin(*fIndex)*100;
*fIndex += 0.173;
return &fValue;
}
void setValue(diom_entry_t *entry, void *data)
{
}
The Raw Distributed Data Protocol (hereafter RDDP.) Is an DIOM-DL binary implementation protocol that is alike XML and based upon protocols used by some professional simulators such as HLA/RTI.
RDDP is an open standard that may be used without restrictions. RDDP is not covered by the GNU Lesser Public Licence / Library Public License. And there fore it may be used/implemented in/by non GPL software products.
The RDDP specification is maintained by the International Research And Development Institute for Simulation (the IRADIS Foundation), and is described in this document. It is possible that the RDDP specification will be moved to a separate document. When this happens a reference to that document will be inserted in this chapter of this document.
The current RDDP specification is 1.
RDDP is a pure binary protocol. It can be transmitted through any form of transport medium ( LAN, WAN, CAN, RS232, RS485, or named pipes.)
An RDDP based simulator infrastructure is formed by 2 or more RDDP Components.. The Components communicate through the RDDP TupelSpace using its RDDP EntryPoint (RDDP EP). A Component is a logical block that has exactly 1 EntryPoint in the RDDP TupelSpace. 1 or more Componets can form a functional block. All Components involved in the process of a simulated entity form a federate.
.................................................................... .Federation . .................................................................... ..Federate .................................. .. . Functional block ... ..+-----------+ +-----------+ . +-----------+ +-----------+ ... ..| Component | | Component | . | Component | | Component | ... ..| | | | . | | | | ... ..| Flight | | Mockup | . | Logging | | Tracking | ... ..| Model | | Simulator | . | | | | ... ..| Simulator | | | . | | | | ... ..| | | | . | | | | ... ..| +------------------------------------------------------+ | ... ..| | RDDP Tupel space | | ... ..|--+----+----------------+----------------+--------------++ | ... ..|RDDP EP| | |RDDP EP| | . |RDDP EP| | |RDDP EP| | ... ..+-----------+ +-----------+ . +-----------+ +-----------+ ... .. | | ........|..............|.......... ........|................|................|..............|.......... . +----------------+----------------+--------------+ . . PTP or MP Network . ....................................................................
An attribute is a placeholder for one data value also knwon as variable. Each attribute has an identifier unique to the federation which is an 32 bits wide unsigned integer.
A component realizes a specific task within the simulation. A component has an identifier unique to the federation. This identifier is an 32 bits wide unsigned integer.
A functiona block is a group of components that realize a related task. That either produce no attribute changes, or do not share each others attribute changes. From the point of both a federate or the federation a function block is seen as one component. Therefore aal components within the same functional block share the same component identifier.
A federate is a set of components that together realize a simulated entity. Each federate has its own identifier unique to the federation and is an 32 bits wide identifier.
The federation is formed by all federates to form the simulation environment.
The RDDP Tupelspace is an abstract definition for all attributes within the federation.
The RDDP DIOM-DL defines two configuration file sections
being rddp and rddp-ddt. The rddp
section defines the connection method used by RDDP.
The rddp-ddt section lists the definition of the data
send through the protocol, containing the tags and the
descriptions of the data.
[rddp] protocol udp port 9000 federate 41 [rddp-ddt] # ID Variable-name Type Default Min Max 1002001 MasterWarning boolean false 1002002 MasterCaution boolean false 0011001 Elevator float 0 -100 +100 0011002 ElevatorTrim float 0 -100 +100 0011003 ElevatorActuator float 0 -100 +100
The RDDP packets can be sent using any method. Currently only an UDP/IP connection will be supported. With very little effort it's possible to use other network protocols or pipes.
An RDDP packet is contructed of 1 RDDP Packet header and 0 to 255 RDDP Data Records.
RDDP Packet: +-------------+-------------------//-----------------+ | RDDP Header | RDDP Data Record // RDDP Data Record | +-------------+-----------------//-------------------+
Each RDDP packet starts with the RDDP packet header.
RDDP Packet Header: +-----+-----+-----+-------+-----+------+--//+ | VER | FED | COM | STAMP | REC | OLEN | FB | +-----+-----+-----+-------+-----+------+//--+
| Field | Type | Description
|
| VER | 8bit UInteger | Version number of RDDP
|
| FED | 32bit UInteger | Federate ID number
|
| COM | 32bit UInteger | Component ID number
|
| STAMP | 32bit UInteger | Timestamp
|
| REC | 8bit UInteger | The number of RDDP data records
|
| OLEN | 8bit UInteger | Length of the future block
|
| FB #tab Variable | Future block
|
The version number of the RDDP specification / implementation. This version number should be used to determine the contents of the FB.
The unique identification number of the federate the component belongs to
The unique identification number of the component.
The timestamp field identfies the Attribute change number for the component. The first attribute change is marked as '0'.
The number of RDDP Data Records that follow the RDDP Header.
This field indicates the length of the FB. The first RDDP Data Record can be found by adding this value to the length of the RDDP Header excluding the length of the known BF size. For the first RDDP implementation this value will be '0' since the FB is not utilised.
The Future Block will be used in future RDDP Spcification that require the RDDP Header to be expanded for new information. Fute expantions of the Data Records will be appended after the base RDDP Data Record array.
After the RDDP packet header there can be 0 to 255 data record.
RDDP Data Record: +------+----+---//--+ | TYPE | ID | VALUE | +------+----+--//---+
| Field | Type | Description
|
| TYPE | 8bit UInteger | Data type of variable
|
| ID | 32bit SInteger | Variable identifier
|
| VALUE | [N] bytes | New values for variable
|
This section lists the defines RDDP variable types
| Type | Data Record | Size | Range
|
| boolean | 10 | 8bit | 0=FALSE, 1=TRUE
|
| integer | 40 | 32bit | -2147483648 - +2147483647
|
| float | 80 | 16bit | Standard ANSI float
|
| double | 84 | 32bit | Standard ANSI double
|
| string | 120 | 1+[N] byte | Length byte + 0 to 255 characters
|
Version 1.1, March 2000
Copyright © 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
The purpose of this License is to make a manual, textbook, or other written 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 that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".
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. (For example, 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.
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 "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and 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 has been designed to thwart or discourage subsequent modification by readers is not Transparent. 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 designed for human modification. Opaque formats include PostScript, PDF, 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 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.
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 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 publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. 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.
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 "Acknowledgments", 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, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they 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 quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around 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 provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
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.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (C) year your name. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being list their titles, with the Front-Cover Texts being list, and with the Back-Cover Texts being list. A copy of the license is included in the section entitled ``GNU Free Documentation License''.
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being list"; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.