Task-oriented documentation

doc/rexml/tasks/mktocs.rb

@@ -0,0 +1,72 @@
+Dir.chdir(File.dirname(__FILE__)) do
+
+  # Get the correct links from actual (temporary) rdoc html.
+  toc_lis_by_name = {}
+  require 'tmpdir'
+  Dir.mktmpdir do |tmpdir|
+    system("rdoc --op #{tmpdir} --force-output rdoc")
+    Dir.chdir("#{tmpdir}/rdoc") do
+      Dir.new('.').entries.each do |html_file_path|
+        next if html_file_path.start_with?('.')
+        toc_lis = []
+        File.open(html_file_path, 'r') do |file|
+          in_toc = false
+          file.each_line do |line|
+            unless in_toc
+              if line.include?('<ul class="link-list" role="directory">')
+                in_toc = true
+                next
+              end
+            end
+            if in_toc
+              break if line.include?('</ul>')
+              toc_lis.push(line.chomp)
+            end
+          end
+        end
+        key = html_file_path.sub('_rdoc.html', '')
+        toc_lis_by_name[key] = toc_lis
+      end
+    end
+  end
+
+  File.open('tocs/master_toc.rdoc', 'w') do |master_toc_file|
+    master_toc_file.write("== Table of Contents\n\n")
+    Dir.chdir('tocs') do
+      entries = Dir.entries('.')
+      entries.delete_if {|entry| entry.start_with?('.') }
+      entries.delete_if {|entry| entry == 'master_toc.rdoc' }
+      toc_lis_by_name.each_pair do |name, lis|
+        toc_file_name = name + '_toc.rdoc'
+        entries.delete(toc_file_name)
+        File.open(toc_file_name, 'w') do |class_file|
+          class_file.write("Tasks on this page:\n\n")
+          lis.each_with_index do |li, i|
+            _, temp = li.split('"', 2)
+            link, temp = temp.split('">', 2)
+            text = temp.sub('</a>', '')
+            indentation = text.start_with?('Task') ? '  ' : ''
+            toc_entry = "#{indentation}- {#{text}}[#{link}]\n"
+            if i == 0
+              text = text.split(' ')[1]
+              link = "../../tasks/rdoc/#{text.downcase}_rdoc.html"
+              master_toc_file.write("=== {#{text}}[#{link}]\n")
+              next
+            end
+            master_link = "../../tasks/rdoc/#{toc_file_name.sub('_toc.rdoc', '_rdoc.html')}#{link}"
+            master_toc_entry = "#{indentation}- {#{text}}[#{master_link}]\n"
+            master_toc_file.write(master_toc_entry)
+            class_file.write(toc_entry)
+          end
+          master_toc_file.write("\n")
+          class_file.write("\n")
+        end
+      end
+      unless entries.empty?
+        message = "Some entries not updated: #{entries}"
+        fail message
+      end
+    end
+  end
+
+end

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