diff options
| author | Hiroshi SHIBATA <hsbt@ruby-lang.org> | 2020-01-11 21:37:00 +0900 |
|---|---|---|
| committer | SHIBATA Hiroshi <hsbt@ruby-lang.org> | 2020-01-12 12:28:29 +0900 |
| commit | c3ccf23d5807f2ff20127bf5e42df0977bf672fb (patch) | |
| tree | d3953c32b61645c7af65d30e626af944f143cf58 /test/rexml/data/documentation.xml | |
| parent | 012f297311817ecb19f78c55854b033bb4b0397c (diff) | |
Make rexml library to the bundle gems
[Feature #16485][ruby-core:96683]
Notes
Notes:
Merged: https://github.com/ruby/ruby/pull/2832
Diffstat (limited to 'test/rexml/data/documentation.xml')
| -rw-r--r-- | test/rexml/data/documentation.xml | 542 |
1 files changed, 0 insertions, 542 deletions
diff --git a/test/rexml/data/documentation.xml b/test/rexml/data/documentation.xml deleted file mode 100644 index a1ad6e878b..0000000000 --- a/test/rexml/data/documentation.xml +++ /dev/null @@ -1,542 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<?xml-stylesheet type="text/css" href="http://www.germane-software.com/repositories/public/documentation/documentation.css"?> -<?xml-stylesheet alternative="yes" type="text/css" href="file:/home/ser/Work/documentation/documentation.css"?> -<?xml-stylesheet alternative="yes" type="text/xsl" href="http://www.germane-software.com/repositories/public/documentation/paged.xsl"?> -<!DOCTYPE documentation SYSTEM "http://www.germane-software.com/repositories/public/documentation/documentation.dtd"> -<documentation> - <head> - <title>REXML</title> - - <banner href="img/rexml.png" /> - - <version>@ANT_VERSION@</version> - - <date>@ANT_DATE@</date> - - <home>http://www.germane-software.com/software/rexml</home> - - <base>rexml</base> - - <language>ruby</language> - - <author email="ser@germane-software.com" - href="http://www.ser1.net/" jabber="seanerussell@gmail.com">Sean - Russell</author> - </head> - - <overview> - <purpose lang="en"> - <p>REXML is a conformant XML processor for the Ruby programming - language. REXML passes 100% of the Oasis non-validating tests and - includes full XPath support. It is reasonably fast, and is implemented - in pure Ruby. Best of all, it has a clean, intuitive API. REXML is - included in the standard library of Ruby</p> - - <p>This software is distribute under the <link href="LICENSE.txt">Ruby - license</link>.</p> - </purpose> - - <general> - <p>REXML arose out of a desire for a straightforward XML API, and is an - attempt at an API that doesn't require constant referencing of - documentation to do common tasks. "Keep the common case simple, and the - uncommon, possible."</p> - - <p>REXML avoids The DOM API, which violates the maxim of simplicity. It - does provide <em>a</em> DOM model, but one that is Ruby-ized. It is an - XML API oriented for Ruby programmers, not for XML programmers coming - from Java.</p> - - <p>Some of the common differences are that the Ruby API relies on block - enumerations, rather than iterators. For example, the Java code:</p> - - <example>for (Enumeration e=parent.getChildren(); e.hasMoreElements(); ) { - Element child = (Element)e.nextElement(); // Do something with child -}</example> - - <p>in Ruby becomes:</p> - - <example>parent.each_child{ |child| # Do something with child }</example> - - <p>Can't you feel the peace and contentment in this block of code? Ruby - is the language Buddha would have programmed in.</p> - - <p>One last thing. If you use and like this software, and you're in a - position of power in a company in Western Europe and are looking for a - software architect or developer, drop me a line. I took a lot of French - classes in college (all of which I've forgotten), and I lived in Munich - long enough that I was pretty fluent by the time I left, and I'd love to - get back over there.</p> - </general> - - <features lang="en"> - <item>Four intuitive parsing APIs.</item> - - <item>Intuitive, powerful, and reasonably fast tree parsing API (a-la - DOM</item> - - <item>Fast stream parsing API (a-la SAX)<footnote>This is not a SAX - API.</footnote></item> - - <item>SAX2-based API<footnote>In addition to the native REXML streaming - API. This is slower than the native REXML API, but does a lot more work - for you.</footnote></item> - - <item>Pull parsing API.</item> - - <item>Small</item> - - <item>Reasonably fast (for interpreted code)</item> - - <item>Native Ruby</item> - - <item>Full XPath support<footnote>Currently only available for the tree - API</footnote></item> - - <item>XML 1.0 conformant<footnote>REXML passes all of the non-validating - OASIS tests. There are probably places where REXML isn't conformant, but - I try to fix them as they're reported.</footnote></item> - - <item>ISO-8859-1, UNILE, UTF-16 and UTF-8 input and output; also, - support for any encoding the iconv supports.</item> - - <item>Documentation</item> - </features> - </overview> - - <operation lang="en"> - <subsection title="Installation"> - <p>You don't <em>have</em> to install anything; if you're running a - version of Ruby greater than 1.8, REXML is included. However, if you - choose to upgrade from the REXML distribution, run the command: - <code>ruby bin/install.rb</code>. By the way, you really should look at - these sorts of files before you run them as root. They could contain - anything, and since (in Ruby, at least) they tend to be mercifully - short, it doesn't hurt to glance over them. If you want to uninstall - REXML, run <code>ruby bin/install.rb -u</code>.</p> - </subsection> - - <subsection title="Unit tests"> - <p>If you have Test::Unit installed, you can run the unit test cases. - Run the command: <code>ruby bin/suite.rb</code>; it runs against the - distribution, not against the installed version.</p> - </subsection> - - <subsection title="Benchmarks"> - <p>There is a benchmark suite in <code>benchmarks/</code>. To run the - benchmarks, change into that directory and run <code>ruby - comparison.rb</code>. If you have nothing else installed, only the - benchmarks for REXML will be run. However, if you have any of the - following installed, benchmarks for those tools will also be run:</p> - - <list> - <item>NQXML</item> - - <item>XMLParser</item> - - <item>Electric XML (you must copy <code>EXML.jar</code> into the - <code>benchmarks</code> directory and compile - <code>flatbench.java</code> before running the test)</item> - </list> - - <p>The results will be written to <code>index.html</code>.</p> - </subsection> - - <subsection title="General Usage"> - <p>Please see <link href="docs/tutorial.html">the Tutorial</link>.</p> - - <p>The API documentation is available <link - href="http://www.germane-software.com/software/XML/rexml/doc">on-line</link>, - or it can be downloaded as an archive <link - href="http://www.germane-software.com/software/archives/rexml_api_@ANT_VERSION@.tgz">in - tgz format (~70Kb)</link> or (if you're a masochist) <link - href="http://www.germane-software.com/software/archives/rexml_api_@ANT_VERSION@.zip">in - zip format (~280Kb)</link>. The best solution is to download and install - Dave Thomas' most excellent <link - href="http://rdoc.sourceforge.net">rdoc</link> and generate the API docs - yourself; then you'll be sure to have the latest API docs and won't have - to keep downloading the doc archive.</p> - - <p>The unit tests in <code>test/</code> and the benchmarking code in - <code>benchmark/</code> provide additional examples of using REXML. The - Tutorial provides examples with commentary. The documentation unpacks - into <link href="doc/index.html"><code>rexml/doc</code></link>.</p> - - <p>Kouhei Sutou maintains a <link - href="http://www.germane-software.com/software/rexml_doc_ja/current/index.html">Japanese - version</link> of the REXML API docs. <link - href="http://www.germane-software.com/software/rexml_doc_ja/current/japanese_documentation.html">Kou's - documentation page</link> contains links to binary archives for various - versions of the documentation.</p> - </subsection> - </operation> - - <status> - <subsection title="Speed and Completeness"> - <p>Unfortunately, NQXML is the only package REXML can be compared - against; XMLParser uses expat, which is a native library, and really is - a different beast altogether. So in comparing NQXML and REXML you can - look at four things: speed, size, completeness, and API.</p> - - <p><link href="benchmarks/index.html">Benchmarks</link></p> - - <p>REXML is faster than NQXML in some things, and slower than NQXML in a - couple of things. You can see this for yourself by running the supplied - benchmarks. Most of the places where REXML are slower are because of the - convenience methods<footnote>For example, - <code>element.elements[index]</code> isn't really an array operation; - index can be an Integer or an XPath, and this feature is relatively time - expensive.</footnote>. On the positive side, most of the convenience - methods can be bypassed if you know what you are doing. Check the <link - href="benchmarks/index.html"> benchmark comparison page</link> for a - <em>general</em> comparison. You can look at the benchmark code yourself - to decide how much salt to take with them.</p> - - <p>The sizes of the XML parsers are close<footnote>As measured with - <code>ruby -nle 'print unless /^\s*(#.*|)$/' *.rb | wc -l</code> - </footnote>. NQXML 1.1.3 has 1580 non-blank, non-comment lines of code; - REXML 2.0 has 2340<footnote>REXML started out with about 1200, but that - number has been steadily increasing as features are added. XPath - accounts for 541 lines of that code, so the core REXML has about 1800 - LOC.</footnote>.</p> - - <p>REXML is a conformant XML 1.0 parser. It supports multiple language - encodings, and internal processing uses the required UTF-8 and UTF-16 - encodings. It passes 100% of the Oasis non-validating tests. - Furthermore, it provides a full implementation of XPath, a SAX2 and a - PullParser API.</p> - </subsection> - - <subsection title="XPath"> - <p>As of release 2.0, XPath 1.0 is fully implemented.</p> - - <p>I fully expect bugs to crop up from time to time, so if you see any - bogus XPath results, please let me know. That said, since I'm now - following the XPath grammar and spec fairly closely, I suspect that you - won't be surprised by REXML's XPath very often, and it should become - rock solid fairly quickly.</p> - - <p>Check the "bugs" section for known problems; there are little bits of - XPath here and there that are not yet implemented, but I'll get to them - soon.</p> - - <p>Namespace support is rather odd, but it isn't my fault. I can only do - so much and still conform to the specs. In particular, XPath attempts to - help as much as possible. Therefore, in the trivial cases, you can pass - namespace prefixes to Element.elements[...] and so on -- in these cases, - XPath will use the namespace environment of the base element you're - starting your XPath search from. However, if you want to do something - more complex, like pass in your own namespace environment, you have to - use the XPath first(), each(), and match() methods. Also, default - namespaces <em>force</em> you to use the XPath methods, rather than the - convenience methods, because there is no way for XPath to know what the - mappings for the default namespaces should be. This is exactly why I - loath namespaces -- a pox on the person(s) who thought them up!</p> - </subsection> - - <subsection title="Namespaces"> - <p>Namespace support is now fairly stable. One thing to be aware of is - that REXML is not (yet) a validating parser. This means that some - invalid namespace declarations are not caught.</p> - </subsection> - - <subsection title="Mailing list"> - <p>There is a low-volume mailing list dedicated to REXML. To subscribe, - send an empty email to <link - href="mailto:ser-rexml-subscribe@germane-software.com">ser-rexml-subscribe@germane-software.com</link>. - This list is more or less spam proof. To unsubscribe, similarly send a - message to <link - href="mailto:ser-rexml-unsubscribe@germane-software.com">ser-rexml-unsubscribe@germane-software.com</link>.</p> - </subsection> - - <subsection title="RSS"> - <p>An <link - href="http://www.germane-software.com/projects/rexml/timeline?ticket=on&max=50&daysback=90&format=rss">RSS - file</link> for REXML is now being generated from the change log. This - allows you to be alerted of bug fixes and feature additions via "pull". - <link href="http://www.germane-software.com/software/rexml/rss.xml">Another - RSS</link> is available which contains a single item: the release notice - for the most recent release. This is an abuse of the RSS - mechanism, which was intended to be a distribution system for headlines - linked back to full articles, but it works. The headline for REXML is - the version number, and the description is the change log. The links all - link back to the REXML home page. The URL for the RSS itself is - http://www.germane-software.com/software/rexml/rss.xml.</p> - - <p>The <link href="release.html">changelog itself is here</link>.</p> - - <p>For those who are interested, there's a <link - href="docs/sloccount.txt">SLOCCount</link> (by David A. Wheeler) file - with stats on the REXML sourcecode. Note that the SLOCCount output - includes the files in the test/, benchmarks/, and bin/ directories, as - well as the main sourcecode for REXML itself.</p> - </subsection> - - <subsection title="Applications that use REXML"> - <list> - <item><link - href="http://www.pablotron.org/software/raggle/">Raggle</link> is a - console-based RSS aggregator.</item> - - <item><link - href="http://www.zweknu.org/technical/index.rhtml?s=p|10/">getrss</link> - is an RSS aggregator</item> - - <item>Ned Konz's <link - href="http://www.bikenomad.microship.com/ruby/">ruby-htmltools</link> - uses REXML</item> - - <item>Hiroshi NAKAMURA's <link - href="http://www.ruby-lang.org/en/raa-list.rhtml?name=SOAP4R">SOAP4R</link> - package can use REXML as the XML processor.</item> - - <item>Chris Morris' <link href="http://clabs.org/clxmlserial.htm">XML - Serializer</link>. XML Serializer provides a serialization mechanism - for Ruby that provides a bidirectional mapping between Ruby classes - and XML documents.</item> - - <item>Much of the <link href="http://www.rubyxml.com">RubyXML</link> - site is generated with scripts that use REXML. RubyXML is a great - place to find information about th intersection between Ruby and - XML.</item> - </list> - </subsection> - - <bugs lang="en"> - <p>You can submit bug reports and feature requests, and view the list of - known bugs, at the <link - href="http://www.germane-software.com/projects/rexml">REXML bug report - page.</link> Please do submit bug reports. If you really want your bug - fixed fast, include an runit or Test::Unit method (or methods) that - illustrates the problem. At the very least, send me some XML that REXML - doesn't process properly.</p> - - <p>You don't have to send an entire test suite -- just the unit test - methods. If you don't send me a unit test, I'll have to write one - myself, which will mean that your bug will take longer to fix.</p> - - <p>When submitting bug reports, please include the version of Ruby and - of REXML that you're using, and the operating system you're running on. - Just run: <code>ruby -vrrexml/rexml -e 'p - REXML::VERSION,PLATFORM'</code> and paste the results in your bug - report. Include your email if you want a response about the bug.</p> - - <item>Attributes are not handled internally as nodes, so you can't - perform node functions on them. This will have to change. It'll also - probably mean that, rather than returning attribute values, XPath will - return the Attribute nodes.</item> - - <item>Some of the XPath <em>functions</em> are untested<footnote>Mike - Stok has been testing, debugging, and implementing some of these - Functions (and he's been doing a good job) so there's steady improvement - in this area.</footnote>. Any XPath functions that don't work are also - bugs... please report them. If you send a unit test that illustrates the - problem, I'll try to fix the problem within a couple of days (if I can) - and send you a patch, personally.</item> - - <item>Accessing prefixes for which there is no defined namespace in an - XPath should throw an exception. It currently doesn't -- it just fails - to match.</item> - </bugs> - - <todo lang="en"> - <item>Reparsing a tree with a pull/SAX parser</item> - - <item>Better namespace support in SAX</item> - - <item>Lazy tree parsing</item> - - <item>Segregate parsers, for optimized minimal distributions</item> - - <item>XML <-> Ruby</item> - - <item>Validation support</item> - - <item>True XML character support</item> - - <item>Add XPath support for streaming APIs</item> - - <item status="request">XQuery support</item> - - <item status="request">XUpdate support</item> - - <item>Make sure namespaces are supported in pull parser</item> - - <item status="request">Add document start and entity replacement events - in pull parser</item> - - <item>Better stream parsing exception handling</item> - - <item>I'd like to hack XMLRPC4R to use REXML, for my own - purposes.</item> - </todo> - </status> - - <faq> - <q>REXML is hanging while parsing one of my XML files.</q> - - <a>Your XML is probably malformed. Some malformed XML, especially XML that - contains literal '<' embedded in the document, causes REXML to hang. - REXML should be throwing an exception, but it doesn't; this is a bug. I'm - aware that it is an extremely annoying bug, and it is one I'm trying to - solve in a way that doesn't significantly reduce REXML's parsing - speed.</a> - - <q>I'm using the XPath '//foo' on an XML branch node X, and keep getting - all of the 'foo' elements in the entire document. Why? Shouldn't it return - only the 'foo' element descendants of X?</q> - - <a>No. XPath specifies that '/' returns the document root, regardless of - the context node. '//' also starts at the document root. If you want to - limit your search to a branch, you need to use the self:: axe. EG, - 'self::node()//foo', or the shorthand './/foo'.</a> - - <q>I want to parse a document both as a tree, and as a stream. Can I do - this?</q> - - <a>Yes, and no. There is no mechanism that directly supports this in - REXML. However, aside from writing your own traversal layer, there is a - way of doing this. To turn a tree into a stream, just turn the branch you - want to process as a stream back into a string, and re-parse it with your - preferred API. EG: pp = PullParser.new( some_element.to_s ). The other - direction is more difficult; you basically have to build a tree from the - events. REXML will have one of these builders, eventually, but it doesn't - currently exist.</a> - - <q>Why is Element.elements indexed off of '1' instead of '0'?</q> - - <a>Because of XPath. The XPath specification states that the index of the - first child node is '1'. Although it may be counter-intuitive to base - elements on 1, it is more undesireable to have element.elements[0] == - element.elements[ 'node()[1]' ]. Since I can't change the XPath - specification, the result is that Element.elements[1] is the first child - element.</a> - - <q>Why isn't REXML a validating parser?</q> - - <a>Because validating parsers must include code that parses and interprets - DTDs. I hate DTDs. REXML supports the barest minimum of DTD parsing, and - even that isn't complete. There is DTD parsing code in the works, but I - only work on it when I'm really, really bored. Rumor has it that a - contributor is working on a DTD parser for REXML; rest assured that any - such contribution will be included with REXML as soon as it is - available.</a> - - <q>I'm trying to create an ISO-8859-1 document, but when I add text to the - document it isn't being properly encoded.</q> - - <a>Regardless of what the encoding of your document is, when you add text - programmatically to a REXML document you <em>must</em> ensure that you are - only adding UTF-8 to the tree. In particular, you can't add ISO-8859-1 - encoded text that contains characters above 0x80 to REXML trees -- you - must convert it to UTF-8 before doing so. Luckily, this is easy: - <code>text.unpack('C*').pack('U*')</code> will do the trick. 7-bit ASCII - is identical to UTF-8, so you probably won't need to worry about this.</a> - - <q>How do I get the tag name of an Element?</q> - - <a>You take a look at the APIs, and notice that <code>Element</code> - includes <code>Namespace</code>. Then you click on the - <code>Namespace</code> link and look at the methods that - <code>Element</code> includes from <code>Namespace</code>. One of these is - <code>name()</code>. Another is <code>expanded_name()</code>. Yet another - is <code>prefix()</code>. Then, you email the author of rdoc and ask him - to extend rdoc so that it lists methods in the API that are included from - other files, so that you don't have to do all of that looking around for - your method.</a> - </faq> - - <credits> - <p>I've had help from a number of resources; if I haven't listed you here, - it means that I just haven't gotten around to adding you, or that I'm a - dork and have forgotten. In either case, feel free to write me and - complain.</p> - - <list> - <item>Mike Stok has been very active, sending not only fixes for bugs - (especially in Functions), but also by providing unit tests and making - sure REXML runs under Ruby 1.7. He also sent the most awesome hand - knitted tea cozy, with "REXML" and the Ruby knitted into it.</item> - - <item>Kouhei Sutou translated the REXML API documentation to Japanese! - Links are in the API docs section of the main documentation. He has also - contributed a large number of bug reports and patches to fix bugs in - REXML.</item> - - <item>Erik Terpstra heard my pleas and submitted several logos for - REXML. After sagely procrastinating for several weeks, I finally forced - my poor slave of a wife to pick one (this is what we call "delegation"). - She did, with caveats; Erik quickly made the changes, and the result is - what you now see at the top of this page. He also supplied a <link - href="img/rexml_50p.png">smaller version</link> that you can include - with your projects that use REXML, if you'd like.</item> - - <item>Ernest Ellingson contributed the sourcecode for turning UTF16 and - UNILE encodings into UTF8, which allowed REXML to get the 100% OASIS - valid tests rating.</item> - - <item>Ian Macdonald provided me with a comprehensive, well written RPM - spec file.</item> - - <item>Oliver M . Bolzer is maintaining a Debian package distribution of - REXML. He also has provided good feedback and bug reports about - namespace support.</item> - - <item>Michael Granger supplied a patch for REXML that make the unit - tests pass under Ruby 1.7.</item> - - <item>James Britt contributed code that makes using - Document.parse_stream easier to use by allowing it to be passed either a - Source, File, or String.</item> - - <item>Tobias Reif: Numerous bug reports, and suggestions for - improvement.</item> - - <item>Stefan Scholl, who provided a lot of feedback and bug reports - while I was trying to get ISO-8859-1 support working.</item> - - <item>Steven E Lumos for volunteering information about XPath - particulars.</item> - - <item>Fumitoshi UKAI provided some bug fixes for CData metacharacter - quoting.</item> - - <item>TAKAHASHI Masayoshi, for information on UTF</item> - - <item>Robert Feldt: Bug reports and suggestions/recommendations about - improving REXML. Testing is one of the most important aspects of - software development.</item> - - <item><link - href="http://www.themindelectric.com/exml/index.html">Electric - XML</link>: This was, after all, the inspiration for REXML. Originally, - I was just going to do a straight port, and although REXML doesn't in - any way, shape or form resemble Electric XML, still the basic framework - and philosophy was inspired by E-XML. And I still use E-XML in my Java - projects.</item> - - <item><link - href="http://www.io.com/~jimm/downloads/nqxml/index.html">NQXML</link>: - While I may complain about the NQXML API, I wrote a few applications - using it that wouldn't have been written otherwise, and it was very - useful to me. It also encouraged me to write REXML. Never complain about - free software *slap*.</item> - - <item>See my <link - href="http://www.germane-software.com/~ser/technology.html">technologies - page</link> for a more comprehensive list of computer technologies that - I depend on for my day-to-day work.</item> - - <item>rdoc, an excellent JavaDoc analog<footnote>When I was first - working on REXML, rdoc wasn't, IMO, very good, so I wrote API2XML. - API2XML was good enough for a while, and then there was a flurry of work - on rdoc, and it quickly surpassed API2XML in features. Since I was never - really interested in maintaining a JavaDoc analog, I stopped support of - API2XML, and am now recommending that people use - rdoc.</footnote>.</item> - - <item>Many, many other people who've submitted bug reports, suggestions, - and positive feedback. You're all co-developers!</item> - </list> - </credits> -</documentation> |