Skip to content

Commit 83bd4dc

Browse files
BurdetteLamarBurdetteLamar
authored
Task-oriented documentation (#64)
1 parent 77be80e commit 83bd4dc

14 files changed

+1706
-0
lines changed

‎Rakefile

+2
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,5 @@ RDoc::Task.new do |rdoc|
2626
rdoc.rdoc_files.include(*spec.source_paths)
2727
rdoc.rdoc_files.include(*spec.extra_rdoc_files)
2828
end
29+
30+
load "#{__dir__}/tasks/tocs.rake"

‎doc/rexml/tasks/rdoc/child.rdoc

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
== Class Child
2+
3+
Class Child includes module Node;
4+
see {Tasks for Node}[node_rdoc.html].
5+
6+
:include: ../tocs/child_toc.rdoc
7+
8+
=== Relationships
9+
10+
==== Task: Set the Parent
11+
12+
Use method {Child#parent=}[../../../../REXML/Parent.html#method-i-parent-3D]
13+
to set the parent:
14+
15+
e0 = REXML::Element.new('foo')
16+
e1 = REXML::Element.new('bar')
17+
e1.parent # => nil
18+
e1.parent = e0
19+
e1.parent # => <foo/>
20+
21+
==== Task: Insert Previous Sibling
22+
23+
Use method {Child#previous_sibling=}[../../../../REXML/Parent.html#method-i-previous_sibling-3D]
24+
to insert a previous sibling:
25+
26+
xml_string = '<root><a/><c/></root>'
27+
d = REXML::Document.new(xml_string)
28+
d.root.to_a # => [<a/>, <c/>]
29+
c = d.root[1] # => <c/>
30+
b = REXML::Element.new('b')
31+
c.previous_sibling = b
32+
d.root.to_a # => [<a/>, <b/>, <c/>]
33+
34+
==== Task: Insert Next Sibling
35+
36+
Use method {Child#next_sibling=}[../../../../REXML/Parent.html#method-i-next-sibling-3D]
37+
to insert a previous sibling:
38+
39+
xml_string = '<root><a/><c/></root>'
40+
d = REXML::Document.new(xml_string)
41+
d.root.to_a # => [<a/>, <c/>]
42+
a = d.root[0] # => <a/>
43+
b = REXML::Element.new('b')
44+
a.next_sibling = b
45+
d.root.to_a # => [<a/>, <b/>, <c/>]
46+
47+
=== Removal or Replacement
48+
49+
==== Task: Remove Child from Parent
50+
51+
Use method {Child#remove}[../../../../REXML/Parent.html#method-i-remove]
52+
to remove a child from its parent; returns the removed child:
53+
54+
xml_string = '<root><a/><b/><c/></root>'
55+
d = REXML::Document.new(xml_string)
56+
d.root.to_a # => [<a/>, <b/>, <c/>]
57+
b = d.root[1] # => <b/>
58+
b.remove # => <b/>
59+
d.root.to_a # => [<a/>, <c/>]
60+
61+
==== Task: Replace Child
62+
63+
Use method {Child#replace_with}[../../../../REXML/Parent.html#method-i-replace]
64+
to replace a child;
65+
returns the replaced child:
66+
67+
xml_string = '<root><a/><b/><c/></root>'
68+
d = REXML::Document.new(xml_string)
69+
d.root.to_a # => [<a/>, <b/>, <c/>]
70+
b = d.root[1] # => <b/>
71+
d = REXML::Element.new('d')
72+
b.replace_with(d) # => <b/>
73+
d.root.to_a # => [<a/>, <d/>, <c/>]
74+
75+
=== Document
76+
77+
==== Task: Get the Document
78+
79+
Use method {Child#document}[../../../../REXML/Parent.html#method-i-document]
80+
to get the document for the child:
81+
82+
xml_string = '<root><a/><b/><c/></root>'
83+
d = REXML::Document.new(xml_string)
84+
d.root.to_a # => [<a/>, <b/>, <c/>]
85+
b = d.root[1] # => <b/>
86+
b.document == d # => true
87+
REXML::Child.new.document # => nil

‎doc/rexml/tasks/rdoc/document.rdoc

+276
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
== Class Document
2+
3+
Class Document has methods from its superclasses and included modules;
4+
see:
5+
6+
- {Tasks for Element}[element_rdoc.html].
7+
- {Tasks for Parent}[parent_rdoc.html].
8+
- {Tasks for Child}[child_rdoc.html].
9+
- {Tasks for Node}[node_rdoc.html].
10+
- {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html].
11+
12+
:include: ../tocs/document_toc.rdoc
13+
14+
=== New Document
15+
16+
==== Task: Create an Empty Document
17+
18+
Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
19+
to create an empty document.
20+
21+
d = REXML::Document.new
22+
23+
==== Task: Parse a \String into a New Document
24+
25+
Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
26+
to parse an XML string into a new document:
27+
28+
xml_string = '<root><a/>text<b/>more<c/></root>'
29+
d = REXML::Document.new(xml_string)
30+
d.root # => <root> ... </>
31+
32+
==== Task: Parse an \IO Stream into a New Document
33+
34+
Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
35+
to parse an XML \IO stream into a new document:
36+
37+
xml_string = '<root><a/>text<b/>more<c/></root>'
38+
File.write('t.xml', xml_string)
39+
d = File.open('t.xml', 'r') do |file|
40+
REXML::Document.new(file)
41+
end
42+
d.root # => <root> ... </>
43+
44+
==== Task: Create a Document from an Existing Document
45+
46+
Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
47+
to create a document from an existing document.
48+
The context and attributes are copied to the new document,
49+
but not the children:
50+
51+
xml_string = '<root><a/>text<b/>more<c/></root>'
52+
d = REXML::Document.new(xml_string)
53+
d.children # => [<root> ... </>]
54+
d.context = {raw: :all, compress_whitespace: :all}
55+
d.add_attributes({'bar' => 0, 'baz' => 1})
56+
d1 = REXML::Document.new(d)
57+
d1.context # => {:raw=>:all, :compress_whitespace=>:all}
58+
d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
59+
d1.children # => []
60+
61+
==== Task: Clone a Document
62+
63+
Use method {Document#clone}[../../../../REXML/Document.html#method-i-clone]
64+
to clone a document.
65+
The context and attributes are copied to the new document,
66+
but not the children:
67+
68+
xml_string = '<root><a/>text<b/>more<c/></root>'
69+
d = REXML::Document.new(xml_string)
70+
d.children # => [<root> ... </>]
71+
d.context = {raw: :all, compress_whitespace: :all}
72+
d.add_attributes({'bar' => 0, 'baz' => 1})
73+
d1 = d.clone # => < bar='0' baz='1'/>
74+
d1.context # => {:raw=>:all, :compress_whitespace=>:all}
75+
d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
76+
d1.children # => []
77+
78+
=== Document Type
79+
80+
==== Task: Get the Document Type
81+
82+
Use method {Document#doctype}[../../../../REXML/Document.html#method-i-doctype]
83+
to get the document type:
84+
85+
d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
86+
d.doctype.class # => REXML::DocType
87+
d = REXML::Document.new('')
88+
d.doctype.class # => nil
89+
90+
==== Task: Set the Document Type
91+
92+
Use method {document#add}[../../../../REXML/Document.html#method-i-add]
93+
to add or replace the document type:
94+
95+
d = REXML::Document.new('')
96+
d.doctype.class # => nil
97+
d.add(REXML::DocType.new('foo'))
98+
d.doctype.class # => REXML::DocType
99+
100+
=== XML Declaration
101+
102+
==== Task: Get the XML Declaration
103+
104+
Use method {document#xml_decl}[../../../../REXML/Document.html#method-i-xml_decl]
105+
to get the XML declaration:
106+
107+
d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
108+
d.xml_decl.class # => REXML::XMLDecl
109+
d.xml_decl # => <?xml ... ?>
110+
d = REXML::Document.new('')
111+
d.xml_decl.class # => REXML::XMLDecl
112+
d.xml_decl # => <?xml ... ?>
113+
114+
==== Task: Set the XML Declaration
115+
116+
Use method {document#add}[../../../../REXML/Document.html#method-i-add]
117+
to replace the XML declaration:
118+
119+
d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
120+
d.add(REXML::XMLDecl.new)
121+
122+
=== Children
123+
124+
==== Task: Add an Element Child
125+
126+
Use method
127+
{document#add_element}[../../../../REXML/Document.html#method-i-add_element]
128+
to add an element to the document:
129+
130+
d = REXML::Document.new('')
131+
d.add_element(REXML::Element.new('root'))
132+
d.children # => [<root/>]
133+
134+
==== Task: Add a Non-Element Child
135+
136+
Use method
137+
{document#add}[../../../../REXML/Document.html#method-i-add]
138+
to add a non-element to the document:
139+
140+
xml_string = '<root><a/>text<b/>more<c/></root>'
141+
d = REXML::Document.new(xml_string)
142+
d.add(REXML::Text.new('foo'))
143+
d.children # => [<root> ... </>, "foo"]
144+
145+
=== Writing
146+
147+
==== Task: Write to $stdout
148+
149+
Use method
150+
{document#write}[../../../../REXML/Document.html#method-i-write]
151+
to write the document to <tt>$stdout</tt>:
152+
153+
xml_string = '<root><a/>text<b/>more<c/></root>'
154+
d = REXML::Document.new(xml_string)
155+
d.write
156+
157+
Output:
158+
159+
<root><a/>text<b/>more<c/></root>
160+
161+
==== Task: Write to IO Stream
162+
163+
Use method
164+
{document#write}[../../../../REXML/Document.html#method-i-write]
165+
to write the document to <tt>$stdout</tt>:
166+
167+
xml_string = '<root><a/>text<b/>more<c/></root>'
168+
d = REXML::Document.new(xml_string)
169+
File.open('t.xml', 'w') do |file|
170+
d.write(file)
171+
end
172+
p File.read('t.xml')
173+
174+
Output:
175+
176+
"<root><a/>text<b/>more<c/></root>"
177+
178+
==== Task: Write with No Indentation
179+
180+
Use method
181+
{document#write}[../../../../REXML/Document.html#method-i-write]
182+
to write the document with no indentation:
183+
184+
xml_string = '<root><a><b><c></c></b></a></root>'
185+
d = REXML::Document.new(xml_string)
186+
d.write({indent: 0})
187+
188+
Output:
189+
190+
<root>
191+
<a>
192+
<b>
193+
<c/>
194+
</b>
195+
</a>
196+
</root>
197+
198+
==== Task: Write with Specified Indentation
199+
200+
Use method
201+
{document#write}[../../../../REXML/Document.html#method-i-write]
202+
to write the document with a specified indentation:
203+
204+
xml_string = '<root><a><b><c></c></b></a></root>'
205+
d = REXML::Document.new(xml_string)
206+
d.write({indent: 2})
207+
208+
Output:
209+
210+
<root>
211+
<a>
212+
<b>
213+
<c/>
214+
</b>
215+
</a>
216+
</root>
217+
218+
=== Querying
219+
220+
==== Task: Get the Document
221+
222+
Use method
223+
{document#document}[../../../../REXML/Document.html#method-i-document]
224+
to get the document (+self+); overrides <tt>Element#document</tt>:
225+
226+
xml_string = '<root><a><b><c></c></b></a></root>'
227+
d = REXML::Document.new(xml_string)
228+
d.document == d # => true
229+
230+
==== Task: Get the Encoding
231+
232+
Use method
233+
{document#document}[../../../../REXML/Document.html#method-i-document]
234+
to get the document (+self+); overrides <tt>Element#document</tt>:
235+
236+
xml_string = '<root><a><b><c></c></b></a></root>'
237+
d = REXML::Document.new(xml_string)
238+
d.encoding # => "UTF-8"
239+
240+
==== Task: Get the Node Type
241+
242+
Use method
243+
{document#node_type}[../../../../REXML/Document.html#method-i-node_type]
244+
to get the node type (+:document+); overrides <tt>Element#node_type</tt>:
245+
246+
xml_string = '<root><a><b><c></c></b></a></root>'
247+
d = REXML::Document.new(xml_string)
248+
d.node_type # => :document
249+
250+
==== Task: Get the Root Element
251+
252+
Use method
253+
{document#root}[../../../../REXML/Document.html#method-i-root]
254+
to get the root element:
255+
256+
xml_string = '<root><a><b><c></c></b></a></root>'
257+
d = REXML::Document.new(xml_string)
258+
d.root # => <root> ... </>
259+
260+
==== Task: Determine Whether Stand-Alone
261+
262+
Use method
263+
{document#stand_alone?}[../../../../REXML/Document.html#method-i-stand_alone-3F]
264+
to get the stand-alone value:
265+
266+
d = REXML::Document.new('<?xml standalone="yes"?>')
267+
d.stand_alone? # => "yes"
268+
269+
==== Task: Get the Version
270+
271+
Use method
272+
{document#version}[../../../../REXML/Document.html#method-i-version]
273+
to get the version:
274+
275+
d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>')
276+
d.version # => "2.0"

0 commit comments

Comments
 (0)