Skip to content

Commit

Permalink
explain the difference between elements and nodes
Browse files Browse the repository at this point in the history
  • Loading branch information
@kraih
kraih committed Sep 18, 2015
1 parent 0cd1aa3 commit ecaadeb
Showing 1 changed file with 26 additions and 0 deletions.
26 changes: 26 additions & 0 deletions lib/Mojo/DOM.pm
View file
Expand Up @@ -401,6 +401,32 @@ L<Mojo::DOM> is a minimalistic and relaxed HTML/XML DOM parser with CSS
selector support. It will even try to interpret broken HTML and XML, so you
should not use it for validation.
=head1 ELEMENTS AND NODES
When we parse an HTML/XML fragment, it gets turned into a tree of nodes.
<!DOCTYPE html>
<html>
<head><title>Hello</title></head>
<body>World</body>
</html>
There are currently eight different node types, called C<cdata>, C<comment>,
C<doctype>, C<pi>, C<raw>, C<root>, C<tag> and C<text>. But only nodes of the
type C<tag> are considered elements.
root
|- doctype (html)
+- tag (html)
|- tag (head)
| +- tag (title)
| +- raw (Hello)
+- tag (body)
+- text (World)
While all node types are represented as L<Mojo::DOM> objects, some methods like
L</"attr"> and L</"namespace"> only apply to elements.
=head1 CASE-SENSITIVITY
L<Mojo::DOM> defaults to HTML semantics, that means all tags and attribute
Expand Down

6 comments on commit ecaadeb

@nicomen
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since you have a paragraph titled something that insinuates the difference between elements and nodes are described, I would move the last sentence of the node type paragraph to its own paragraph to define what elements are.

(Rationale: I would scan for "elements" when looking for what elements are, and it's a bit hidden now)

@zoffixznet
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, I'd leave it the way it is. That paragraph is just two sentences and the proposal would make an awkward two 1-sentence paragraphs. The entire section is just 3 paragraphs/4 sentences—there's not much to "scan".

@nicomen
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well I skipped the entire section looking for something elements-related, probably given that I do not know upfront the exact difference (that elements are considered a small subset of nodes). For end users I think elements are the thing they care about the most.

@zoffixznet
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then, I would suggest this modification:

Elements are nodes of type C<tag>. Other possible node types are C<cdata>,
C<comment>, C<doctype>, C<pi>, C<raw>, C<root>, and C<text>.

@nicomen
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1

@mrenvoize
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to the alteration.. I didn't have issue with the original, but the alteration does add further clarity. :)

Please sign in to comment.