diff options
Diffstat (limited to 'lib/liblame/ACM/tinyxml/readme.txt')
| -rw-r--r-- | lib/liblame/ACM/tinyxml/readme.txt | 309 |
1 files changed, 0 insertions, 309 deletions
diff --git a/lib/liblame/ACM/tinyxml/readme.txt b/lib/liblame/ACM/tinyxml/readme.txt deleted file mode 100644 index c98c0f37f6..0000000000 --- a/lib/liblame/ACM/tinyxml/readme.txt +++ /dev/null @@ -1,309 +0,0 @@ -/** @mainpage - -<h1> TinyXml </h1> - -TinyXml is a simple, small, C++ XML parser that can be easily -integrating into other programs. - - -<h2> What it does. </h2> - -In brief, TinyXml parses an XML document, and builds from that a -Document Object Model that can be read, modified, and saved. - -XML stands for "eXtensible Markup Language." It allows you to create -your own document markups. Where HTML does a very good job of marking -documents for browsers, XML allows you to define any kind of document -markup, for example a document that describes a "to do" list for an -organizer application. XML is a very structured and convenient format. -All those random file formats created to store application data can -all be replaced with XML. One parser for everything. - -There are different ways to access and interact with XML data. -TinyXml uses a Document Object Model, meaning the XML data is parsed -into a tree objects that can be browsed and manipulated, and then -written back to disk. You can also construct an XML document from -scratch with C++ objects and write this to disk. - -TinyXml is designed to be easy and fast. It is one header and three cpp -files. Simply add these to your project and off you go. There is an -example to get you started. It is released under the ZLib license, -so you can use it in open source or commercial code. - -It attempts to be a flexible parser, but with truly correct and -compliant XML output (with the exception of the character set, -below.) TinyXml should compile on any reasonably C++ -system. It does not rely on exceptions or RTTI, and only uses the STL -string class. - - -<h2> What it doesn't do. </h2> - -It doesn’t parse or use DTDs (Document Type Definitions) or XSL’s -(eXtensible Stylesheet Language.) It is limited to the ASCII -character set. There are other parsers out there (check out -www.sourceforge.org, search for XML) that are much more fully -featured. But they are also much bigger, take longer to set up in -your project, have a higher learning curve, and often have a more -restrictive license. If you are working with browsers or have more -complete XML needs, TinyXml is not the parser for you. - - -<h2> Code Status. </h2> - -Currently in use, TinyXml is looking pretty stable. If you find -bugs, send them in and we'll get them straightened out as soon as possible. - -There are some areas of improvement; please check sourceforge if you are -interested in working on TinxXml. - - -<h2> Changes between version 1 and 2 </h2> - - -<h3> Entities </h3> -TinyXml recognizes the pre-defined "entity references", meaning special -characters. Namely: - -@verbatim - & & - < < - > > - " " - ' ‘ -@endverbatim - -These are recognized when the XML document is read, and translated to there -ASCII equivalents. For instance, text with the XML of: - -@verbatim - Far & Away -@endverbatim - -will have the Value() of "Far & Away" when queried from the TiXmlText object, -but will be written back to the XML stream/file as an entitity. - -TiXml will ignore unknown entities and the -@verbatim -"&#x" -@endverbatim -entities, and leave them unprocessed. - - -<h3> Streams </h3> -TiXml has been modified to support both C (FILE) and C++ (operator <<,>>) -streams. There are some differences that you may need to be aware of. - -C style output: - - based on FILE* - - the Print() and SaveFile() methods - - Generates formatted output, with plenty of white space, intended to be as - human-readable as possible. They are very fast, and tolerant of ill formed - XML documents. For example, an XML document that contains 2 root elements - and 2 declarations, will print. - -C style input: - - based on FILE* - - the Parse() and LoadFile() methods - - A fast, tolerant read. Use whenever you don't need the C++ streams. - -C++ style ouput: - - based on std::ostream - - operator<< - - Generates condensed output, intended for network transmission rather than - readability. Depending on your system's implementation of the ostream class, - these may be somewhat slower. (Or may not.) Not tolerant of ill formed XML: - a document should contain the correct one root element. Additional root level - elements will not be streamed out. - -C++ style input: - - based on std::istream - - operator>> - - Reads XML from a stream, making it useful for network transmission. The tricky - part is knowing when the XML document is complete, since there will almost - certainly be other data in the stream. TinyXml will assume the XML data is - complete after it reads the root element. Also not that operator>> is somewhat - slower than Parse, due to both implementation of the STL and limitations of - TinyXml. - -<h3> White space </h3> -The world simply does not agree on whether white space should be kept, or condensed. -For example, pretend the '_' is a space, and look at "Hello____world". HTML, and -at least some XML parsers, will interpret this as "Hello_world". They condense white -space. Some XML parsers do not, and will leave it as "Hello____world". (Remember -to keep pretending the _ is a space.) - -It's an issue that hasn't been resolved to my satisfaction. TinyXml supports both -motifs. Call TiXmlBase::SetCondenseWhiteSpace( bool ) to set the desired behavior. -The default is to condense white space. - -If you change the default, you should call TiXmlBase::SetCondenseWhiteSpace( bool ) -before making any calls to Parse XML data, and I don't recommend changing it after -it has been set. - - -<h2> Using and Installing </h2> - -To Compile and Run xmltest: - -A Linux Makefile and a Windows Visual C++ .dsp file is provided. -Simply compile and run. It will write the file demotest.xml to your -disk and generate output on the screen. It also tests walking the -DOM by printing out the number of nodes found using different -techniques. - -The Linux makefile is very generic and will -probably run on other systems, but is only tested on Linux. You no -longer need to run 'make depend'. The dependecies have been -hard coded. - - -To Use in an Application: - -Add tinyxml.cpp, tinyxml.h, tinyxmlerror.cpp, and tinyxmlparser.cpp to your -project or make file. That's it! It should compile on any reasonably -compliant C++ system. You do not need to enable exceptions or -RTTI for TinyXml. - - -<h2> Where it may go. </h2> - -At this point, I'm focusing on tightening up remaining issues. -Bug fixes (though comfortably rare) and minor interface -corrections. - -There are some "it would be nice if..." items. I'll keep those -posted as tasks on SourceForge. (www.sourceforge.net/projects/tinyxml) - - -<h2> How TinyXml works. </h2> - -An example is probably the best way to go. Take: -@verbatim - <?xml version="1.0" standalone=‘no’> - <?-- Our to do list data --> - <ToDo> - <Item priority="1"> Go to the <bold>Toy store!</bold></Item> - <Item priority="2"> Do bills</Item> - </ToDo> -@endverbatim - -It’s not much of a To Do list, but it will do. To read this file -(say "demo.xml") you would create a document, and parse it in: -@verbatim - TiXmlDocument doc( "demo.xml" ); - doc.LoadFile(); -@endverbatim - -And it’s ready to go. Now let’s look at some lines and how they -relate to the DOM. - -<?xml version="1.0" standalone=‘no’> - - The first line is a declaration, and gets turned into the - TiXmlDeclaration class. It will be the first child of the - document node. - - This is the only directive/special tag parsed by by TinyXml. - Generally directive targs are stored in TiXmlUnknown so the - commands won’t be lost when it is saved back to disk. - -<?-- Our to do list data --> - - A comment. Will become a TiXmlComment object. - -<ToDo> - - The ToDo tag defines a TiXmlElement object. This one does not have - any attributes, but will contain 2 other elements, both of which - are items. - -<Item priority="1"> - - Creates another TiXmlElement which is a child of the "ToDo" element. - This element has 1 attribute, with the name ‘priority’ and the value - ‘1’. - -Go to the - - A TiXmlText. This is a leaf node and cannot contain other nodes. - It is a child of the ‘Item" Element. - -<bold> - - Another TiXmlElement, this one a child of the "Item" element. - -Etc. - -Looking at the entire object tree, you end up with: -@verbatim -TiXmlDocument "demo.xml" - TiXmlDeclaration "version='1.0'" "standalone=‘no’" - TiXmlComment " Our to do list data" - TiXmlElement "ToDo" - TiXmlElement "Item" Attribtutes: priority = 1 - TiXmlText "Go to the " - TiXmlElement "bold" - TiXmlText "Toy store!" - TiXmlElement "Item" Attributes: priority=2 - TiXmlText "bills" -@endverbatim - -<h2> Contributors </h2> - -Thanks very much to everyone who sends suggestions, bugs, ideas, and -encouragement. It all helps, and makes this project fun. A special thanks -to the contributors on the web pages that keep it lively. - -So many people have sent in bugs and ideas, that rather than list here I -try to give credit due in the "changes.txt" file. - -<h2> Documentation </h2> - -The documentation is build with Doxygen, using the 'dox' -configuration file. - -<h2> License </h2> - -TinyXml is released under the zlib license: - -This software is provided 'as-is', without any express or implied -warranty. In no event will the authors be held liable for any -damages arising from the use of this software. - -Permission is granted to anyone to use this software for any -purpose, including commercial applications, and to alter it and -redistribute it freely, subject to the following restrictions: - -1. The origin of this software must not be misrepresented; you must -not claim that you wrote the original software. If you use this -software in a product, an acknowledgment in the product documentation -would be appreciated but is not required. - -2. Altered source versions must be plainly marked as such, and -must not be misrepresented as being the original software. - -3. This notice may not be removed or altered from any source -distribution. - -<h2> References </h2> - -The World Wide Web Consortium is the definitive standard body for -XML, and there web pages contain huge amounts of information. I also -recommend "XML Pocket Reference" by Robert Eckstein and published by -O’Reilly. - -<h2> Contact Me: </h2> - -I’d appreciates your suggestions, and would love to know if you -use TinyXml. I hope you enjoy it and find it useful. Please post -questions, comments, file bugs, or contact me at: - -www.sourceforge.net/projects/tinyxml - -Lee Thomason -*/ |