* Template for specifying an extension to E57. * * Last Modified Date: October 19, 2011 * Revision: 2 * * Document Source: the E57 Extension at * * http://www.libe57.org/E57extension.txt * * Notes: * * Comments in this template document are preceded by an asterisk. * This entire section is one big comment. * * Extension documents are simple fixed-width ASCII text, up to 72 * characters wide. * Lines should end with a hard newline. Do not assume that any * special formatting or interpretation will be made by software * displaying the specification. * * When changes are made to the contents of a table, new, changed, * and removed table entries must be identified. All fields of * changed table entires should be included, even if not all fields * have changed. * * An extension specification is always written against given * version(s) of Specifications, which must be identified in the * Dependencies section. That is, the references and modifications in * the extension are applied to that version of the Specification. * * An extension document should by preference include all the * sections in this template unless a particular section indicates * its inclusion is optional. If there is no text in a section, * this is indicated by the word "None", such as: * * Dependencies * * None * * While this may appear excessively verbose, the purpose is to ensure * that extension authors document all affected parts of Specifications. * An exception is that headers for sections of Specifications that * are not altered by the extension may be omitted, once the extension * has been completed. * * In text, field names are distinguished by being surrounded * with angle brackets. For example, the pname field is written as . * All field names will be prefixed by the extension namespace followed * by a colon. * * Math symbols (such as the 'tau', 'lambda', and 'rho' defined * by the texturing section) should be completely written out * in ASCII as described, rather than assuming a non-ASCII * character set. * * The template proper follows. ************************************************************************ Extension Name * The formal name of the extension. The prefix of the name always * starts with E57_. Next the prefix continues with the * vendor-specific tag. This is a short, capitalized string unique * to that vendor, such as "SGI" and "IBM" for those respective * companies. The prefix may also be "EXT" if two or more vendors * have agreed to support the extension. * * The prefix is separated from the body of the name by an * underscore. Words within the name are also separated by * underscores. There is no capitalization used in the body of the * name. For example: * * Extension Name * * E57_SGI_new_extension * * Extension Name * * E57_EXT_normals * * This name can be used during implementation of the extension * like * #define E57_EXT_surface_normals * * #ifdef E57_EXT_surface_normals * ... * #endif XML namespace * All XML namespaces for extension should be declard in the * element as an XML attribute in the following format: * xmlns:=" is the namespace * prefix and is a uniform resource identifier (URI). * Every extension to the E57 file format shall define a unique * namespace. * * XML namespace * * NOR xmlns:nor="http://www.libe57.org/E57_EXT_surface_normals.txt" * Contact * Name, company, and email address of people responsible for the * extension. For multivendor extensions, contacts from each * vendor supporting the extension are preferred. * A backup contact, in case the principal moves on, will be * helpful. Example: * * Contact * * Stan Coleby, Intelisum (scoleby @ intelisum.com) Contributors * Name and company of other people who helped develop the * extension. Credit may be given to an entire Working * Group if contributions are too diffuse. * * Contributors * * Members of the ASTM E57.04 Committee Version * It's hard to generate good version numbers with version control * systems, since extension specs may live in many different source * trees. We now suggest including a manually-inserted date of last * modification and version number. These should be updated only * for meaningful changes to the extension, not just formatting. * * Version * * Last Modified Date: September 20, 2011 * Revision: 1 Dependencies * Separately list all extensions that must be present * for this extension to be implemented, and all extensions * whose presence or absence modifies the operation of this * extension. * * Dependencies * * E57_EXT_surface_normals September 20, 2011 Overview * What does the extension do? What problem does it solve? This * can include background and rationale. A common format is a single sentence * summarizing the extension, followed by greater levels of detail * which will help people understand the extension. Note that the * E57 Specification explicitly does not include rationale, so the * overview is a good place to put it instead. IP Status * Document any known patents or other IP claims that may prohibit * royalty-free implementation of an extension, or impose other * constraints on implementations. It is better to write "No * known IP claims" rather than "None", since the vendor for * vendor extensions, may not know of relevant IP. * * Examples: * IP Status * * ReallyBigCo has made unspecified IP claims against * all implementations of this extension. * IP Status * * US Patent #7,654,321, owned by ReallyBigCo, may * be infringed by implementations of this extension. * IP Status * * No known IP claims. New Fields * List all new XML tags and structures defined by this extension. New Fields * List all new XML tags and structures defined by this extension. * Include enough information to define the field name, data type, * minumum, maximum, default value, and description. * * New Fields * * * * * * * * New Fields * List all new XML tags and structures defined by this extension. * Include enough information to define the field name, data type, * minumum, maximum, default value, and description. * * New Fields * * * * * * * * New PointRecord Fields * List all new XML tags and structures defined by this point * data extension. Include information to define the field * name, data type, precision, minimum, maximum, and * description. * * New PointRecord Fields * * * * * * * * * * XML Example * An xml example would help in understanding the extension. Errors * This list summarizes all possible errors generated by the * extension and should be complete (however, errors are best * described in the extension body text as well). Sample Code * For complex extensions, it may be worthwhile to include * code samples of how to use and implement the extension. Issues * List remaining open issues, or closed issues whose resolution * set a precedent or was otherwise especially interesting. * Briefly describe each issue, options considered, the choice * made, and the reason for that choice. Add contact information * on who is bring up the issue or who made the decision. The Issues * section documents motivation, rationale, etc. while not being a * normative part of the extension. We suggest a numerically * order list so that issues can refer to other issues. * * We now recommend placing the Issues list near the end of * the extension, since it can grow very long yet is ancillary * to the specification itself. ASTM E57 Listed * List the date that the ASTM E57.04 sub committee reviewed * and approved this extension. Revision History * Include important changes in the evolution of the extension. * It's especially important to include this section if the * extension is modified after a version has been shipped. * * Example (and actual revision history of the template): * * Revision History * * Revision 1, 2011/09/20 * - Initial version of this template document * Revision 2, 2011/10/19 * - Added Copyright notice and disclaimer Copyright * A copyright notice sets out the copyright position of your extension * * Copyright (c) [your name] 2010 , All Rights Reserved. * * Permission is hereby granted, free of charge, to any person or organization obtaining a copy of this extension * and accompanying documentation covered by this license (this "Extension") to use, reproduce, display, distribute, * execute, and transmit this Extension, and to prepare derivative works of this Extension, and to permit third-parties * to whom this Extension is furnished to do so, all subject to the following: * * The copyright notices in this Extension and this entire statement, including the above license grant, this restriction * and the following disclaimer, must be included in all copies of this Extension, in whole or in part, and all derivative * works of this Extension, unless such copies or derivative works are solely in the form of machine-executable object code * generated by a source language processor. Disclaimer * THIS EXTENSION IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL * THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THIS EXTENSION BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THIS EXTENSION OR THE USE OR OTHER DEALINGS * IN THIS EXTENSION.