Clean up and enhance high-level RDoc (#65)

README.md

@@ -4,21 +4,9 @@ REXML was inspired by the Electric XML library for Java, which features an easy-
 
 REXML supports both tree and stream document parsing. Stream parsing is faster (about 1.5 times as fast). However, with stream parsing, you don't get access to features such as XPath.
 
-## Installation
+## API
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'rexml'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install rexml
+See the {API documentation}[https://ruby.github.io/rexml/]
 
 ## Usage
 

doc/rexml/tasks/tocs/master_toc.rdoc

@@ -1,4 +1,4 @@
-== Table of Contents
+== Tasks
 
 === {Child}[../../tasks/rdoc/child_rdoc.html]
 - {Relationships}[../../tasks/rdoc/child_rdoc.html#label-Relationships]

lib/rexml/document.rb

@@ -23,6 +23,15 @@ module REXML
   # - A document type.
   # - Processing instructions.
   #
+  # == In a Hurry?
+  #
+  # If you're somewhat familiar with XML
+  # and have a particular task in mind,
+  # you may want to see the
+  # {tasks pages}[../doc/rexml/tasks/tocs/master_toc_rdoc.html],
+  # and in particular, the
+  # {tasks page for documents}[../doc/rexml/tasks/tocs/document_toc_rdoc.html].
+  #
   class Document < Element
     # A convenient default XML declaration. Use:
     #

lib/rexml/element.rb

@@ -27,6 +27,15 @@ module REXML
   #   (other elements, text, CDATA, processing instructions, and comments).
   # - Has zero or more named attributes.
   #
+  # == In a Hurry?
+  #
+  # If you're somewhat familiar with XML
+  # and have a particular task in mind,
+  # you may want to see the
+  # {tasks pages}[../doc/rexml/tasks/tocs/master_toc_rdoc.html],
+  # and in particular, the
+  # {tasks page for elements}[../doc/rexml/tasks/tocs/element_toc_rdoc.html].
+  #
   # === Name
   #
   # An element has a name, which is initially set when the element is created:

lib/rexml/light/node.rb

@@ -1,14 +1,6 @@
 # frozen_string_literal: false
 require_relative '../xmltokens'
 
-# [ :element, parent, name, attributes, children* ]
-  # a = Node.new
-  # a << "B"            # => <a>B</a>
-  # a.b                 # => <a>B<b/></a>
-  # a.b[1]                      # => <a>B<b/><b/><a>
-  # a.b[1]["x"] = "y"   # => <a>B<b/><b x="y"/></a>
-  # a.b[0].c            # => <a>B<b><c/></b><b x="y"/></a>
-  # a.b.c << "D"                # => <a>B<b><c>D</c></b><b x="y"/></a>
 module REXML
   module Light
     # Represents a tagged XML element.  Elements are characterized by

lib/rexml/rexml.rb

@@ -1,26 +1,31 @@
 # -*- coding: utf-8 -*-
 # frozen_string_literal: false
-# REXML is an XML toolkit for Ruby[http://www.ruby-lang.org], in Ruby.
-#
-# REXML is a _pure_ Ruby, XML 1.0 conforming,
-# non-validating[http://www.w3.org/TR/2004/REC-xml-20040204/#sec-conformance]
-# toolkit with an intuitive API.  REXML passes 100% of the non-validating Oasis
-# tests[http://www.oasis-open.org/committees/xml-conformance/xml-test-suite.shtml],
-# and provides tree, stream, SAX2, pull, and lightweight APIs.  REXML also
-# includes a full XPath[http://www.w3c.org/tr/xpath] 1.0 implementation. Since
-# Ruby 1.8, REXML is included in the standard Ruby distribution.
-#
-# Main page:: http://www.germane-software.com/software/rexml
-# Author:: Sean Russell <serATgermaneHYPHENsoftwareDOTcom>
-# Date:: 2008/019
-# Version:: 3.1.7.3
-#
-# This API documentation can be downloaded from the REXML home page, or can
-# be accessed online[http://www.germane-software.com/software/rexml_doc]
-#
-# A tutorial is available in the REXML distribution in docs/tutorial.html,
-# or can be accessed
-# online[http://www.germane-software.com/software/rexml/docs/tutorial.html]
+#
+# \Module \REXML provides classes and methods for parsing,
+# editing, and generating XML.
+#
+# == Implementation
+#
+# \REXML:
+# - Is pure Ruby.
+# - Provides tree, stream, SAX2, pull, and lightweight APIs.
+# - Conforms to {XML version 1.0}[https://www.w3.org/TR/REC-xml/].
+# - Fully implements {XPath version 1.0}[http://www.w3c.org/tr/xpath].
+# - Is {non-validating}[https://www.w3.org/TR/xml/].
+# - Passes 100% of the non-validating {Oasis tests}[http://www.oasis-open.org/committees/xml-conformance/xml-test-suite.shtml].
+#
+# == In a Hurry?
+#
+# If you're somewhat familiar with XML
+# and have a particular task in mind,
+# you may want to see {the tasks pages}[doc/rexml/tasks/tocs/master_toc_rdoc.html].
+#
+# == API
+#
+# Among the most important classes for using \REXML are:
+# - REXML::Document.
+# - REXML::Element.
+#
 module REXML
   COPYRIGHT = "Copyright © 2001-2008 Sean Russell <[email protected]>"
   DATE = "2008/019"

tasks/tocs.rake

@@ -45,7 +45,7 @@ class TOCsGenerator
 
   def generate_files(lis_by_name)
     File.open('tocs/master_toc.rdoc', 'w') do |master_toc_file|
-      master_toc_file.write("== Table of Contents\n\n")
+      master_toc_file.write("== Tasks\n\n")
       cd('tocs') do
         entries = Dir.entries('.')
         entries.delete_if {|entry| entry.start_with?('.') }