Task-oriented documentation (#64)

Rakefile

@@ -26,3 +26,5 @@ RDoc::Task.new do |rdoc|
   rdoc.rdoc_files.include(*spec.source_paths)
   rdoc.rdoc_files.include(*spec.extra_rdoc_files)
 end
+
+load "#{__dir__}/tasks/tocs.rake"

doc/rexml/tasks/rdoc/child.rdoc

@@ -0,0 +1,87 @@
+== Class Child
+
+Class Child includes module Node;
+see {Tasks for Node}[node_rdoc.html].
+
+:include: ../tocs/child_toc.rdoc
+
+=== Relationships
+
+==== Task: Set the Parent
+
+Use method {Child#parent=}[../../../../REXML/Parent.html#method-i-parent-3D]
+to set the parent:
+
+  e0 = REXML::Element.new('foo')
+  e1 = REXML::Element.new('bar')
+  e1.parent # => nil
+  e1.parent = e0
+  e1.parent # => <foo/>
+
+==== Task: Insert Previous Sibling
+
+Use method {Child#previous_sibling=}[../../../../REXML/Parent.html#method-i-previous_sibling-3D]
+to insert a previous sibling:
+
+  xml_string = '<root><a/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a   # => [<a/>, <c/>]
+  c = d.root[1] # => <c/>
+  b = REXML::Element.new('b')
+  c.previous_sibling = b
+  d.root.to_a   # => [<a/>, <b/>, <c/>]
+
+==== Task: Insert Next Sibling
+
+Use method {Child#next_sibling=}[../../../../REXML/Parent.html#method-i-next-sibling-3D]
+to insert a previous sibling:
+
+  xml_string = '<root><a/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a   # => [<a/>, <c/>]
+  a = d.root[0] # => <a/>
+  b = REXML::Element.new('b')
+  a.next_sibling = b
+  d.root.to_a   # => [<a/>, <b/>, <c/>]
+
+=== Removal or Replacement
+
+==== Task: Remove Child from Parent
+
+Use method {Child#remove}[../../../../REXML/Parent.html#method-i-remove]
+to remove a child from its parent; returns the removed child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a   # => [<a/>, <b/>, <c/>]
+  b = d.root[1] # => <b/>
+  b.remove      # => <b/>
+  d.root.to_a   # => [<a/>, <c/>]
+
+==== Task: Replace Child
+
+Use method {Child#replace_with}[../../../../REXML/Parent.html#method-i-replace]
+to replace a child;
+returns the replaced child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a       # => [<a/>, <b/>, <c/>]
+  b = d.root[1]     # => <b/>
+  d = REXML::Element.new('d')
+  b.replace_with(d) # => <b/>
+  d.root.to_a       # => [<a/>, <d/>, <c/>]
+
+=== Document
+
+==== Task: Get the Document
+
+Use method {Child#document}[../../../../REXML/Parent.html#method-i-document]
+to get the document for the child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a     # => [<a/>, <b/>, <c/>]
+  b = d.root[1]   # => <b/>
+  b.document == d # => true
+  REXML::Child.new.document # => nil

doc/rexml/tasks/rdoc/document.rdoc

@@ -0,0 +1,276 @@
+== Class Document
+
+Class Document has methods from its superclasses and included modules;
+see:
+
+- {Tasks for Element}[element_rdoc.html].
+- {Tasks for Parent}[parent_rdoc.html].
+- {Tasks for Child}[child_rdoc.html].
+- {Tasks for Node}[node_rdoc.html].
+- {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html].
+
+:include: ../tocs/document_toc.rdoc
+
+=== New Document
+
+==== Task: Create an Empty Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to create an empty document.
+
+  d = REXML::Document.new
+
+==== Task: Parse a \String into a New Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to parse an XML string into a new document:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root # => <root> ... </>
+
+==== Task: Parse an \IO Stream into a New Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to parse an XML \IO stream into a new document:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  File.write('t.xml', xml_string)
+  d = File.open('t.xml', 'r') do |file|
+    REXML::Document.new(file)
+  end
+  d.root # => <root> ... </>
+
+==== Task: Create a Document from an Existing Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to create a document from an existing document.
+The context and attributes are copied to the new document,
+but not the children:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.children    # => [<root> ... </>]
+  d.context = {raw: :all, compress_whitespace: :all}
+  d.add_attributes({'bar' => 0, 'baz' => 1})
+  d1 = REXML::Document.new(d)
+  d1.context    # => {:raw=>:all, :compress_whitespace=>:all}
+  d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
+  d1.children   # => []
+
+==== Task: Clone a Document
+
+Use method {Document#clone}[../../../../REXML/Document.html#method-i-clone]
+to clone a document.
+The context and attributes are copied to the new document,
+but not the children:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.children    # => [<root> ... </>]
+  d.context = {raw: :all, compress_whitespace: :all}
+  d.add_attributes({'bar' => 0, 'baz' => 1})
+  d1 = d.clone  # => < bar='0' baz='1'/>
+  d1.context    # => {:raw=>:all, :compress_whitespace=>:all}
+  d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
+  d1.children   # => []
+
+=== Document Type
+
+==== Task: Get the Document Type
+
+Use method {Document#doctype}[../../../../REXML/Document.html#method-i-doctype]
+to get the document type:
+
+  d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
+  d.doctype.class # => REXML::DocType
+  d = REXML::Document.new('')
+  d.doctype.class # => nil
+
+==== Task: Set the Document Type
+
+Use method {document#add}[../../../../REXML/Document.html#method-i-add]
+to add or replace the document type:
+
+  d = REXML::Document.new('')
+  d.doctype.class # => nil
+  d.add(REXML::DocType.new('foo'))
+  d.doctype.class # => REXML::DocType
+
+=== XML Declaration
+
+==== Task: Get the XML Declaration
+
+Use method {document#xml_decl}[../../../../REXML/Document.html#method-i-xml_decl]
+to get the XML declaration:
+
+  d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
+  d.xml_decl.class # => REXML::XMLDecl
+  d.xml_decl       # => <?xml ... ?>
+  d = REXML::Document.new('')
+  d.xml_decl.class # => REXML::XMLDecl
+  d.xml_decl       # => <?xml ... ?>
+
+==== Task: Set the XML Declaration
+
+Use method {document#add}[../../../../REXML/Document.html#method-i-add]
+to replace the XML declaration:
+
+  d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
+  d.add(REXML::XMLDecl.new)
+
+=== Children
+
+==== Task: Add an Element Child
+
+Use method
+{document#add_element}[../../../../REXML/Document.html#method-i-add_element]
+to add an element to the document:
+
+  d = REXML::Document.new('')
+  d.add_element(REXML::Element.new('root'))
+  d.children # => [<root/>]
+
+==== Task: Add a Non-Element Child
+
+Use method
+{document#add}[../../../../REXML/Document.html#method-i-add]
+to add a non-element to the document:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.add(REXML::Text.new('foo'))
+  d.children # => [<root> ... </>, "foo"]
+
+=== Writing
+
+==== Task: Write to $stdout
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document to <tt>$stdout</tt>:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.write
+
+Output:
+
+  <root><a/>text<b/>more<c/></root>
+
+==== Task: Write to IO Stream
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document to <tt>$stdout</tt>:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  File.open('t.xml', 'w') do |file|
+    d.write(file)
+  end
+  p File.read('t.xml')
+
+Output:
+
+  "<root><a/>text<b/>more<c/></root>"
+
+==== Task: Write with No Indentation
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document with no indentation:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.write({indent: 0})
+
+Output:
+
+  <root>
+  <a>
+  <b>
+  <c/>
+  </b>
+  </a>
+  </root>
+
+==== Task: Write with Specified Indentation
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document with a specified indentation:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.write({indent: 2})
+
+Output:
+
+  <root>
+    <a>
+      <b>
+        <c/>
+      </b>
+    </a>
+  </root>
+
+=== Querying
+
+==== Task: Get the Document
+
+Use method
+{document#document}[../../../../REXML/Document.html#method-i-document]
+to get the document (+self+); overrides <tt>Element#document</tt>:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.document == d # => true
+
+==== Task: Get the Encoding
+
+Use method
+{document#document}[../../../../REXML/Document.html#method-i-document]
+to get the document (+self+); overrides <tt>Element#document</tt>:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.encoding # => "UTF-8"
+
+==== Task: Get the Node Type
+
+Use method
+{document#node_type}[../../../../REXML/Document.html#method-i-node_type]
+to get the node type (+:document+); overrides <tt>Element#node_type</tt>:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.node_type # => :document
+
+==== Task: Get the Root Element
+
+Use method
+{document#root}[../../../../REXML/Document.html#method-i-root]
+to get the root element:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.root # => <root> ... </>
+
+==== Task: Determine Whether Stand-Alone
+
+Use method
+{document#stand_alone?}[../../../../REXML/Document.html#method-i-stand_alone-3F]
+to get the stand-alone value:
+
+  d = REXML::Document.new('<?xml standalone="yes"?>')
+  d.stand_alone? # => "yes"
+
+==== Task: Get the Version
+
+Use method
+{document#version}[../../../../REXML/Document.html#method-i-version]
+to get the version:
+
+  d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>')
+  d.version # => "2.0"