README.md in caracal-0.1.8 vs README.md in caracal-0.2.0

@@ -20,35 +20,35 @@
 ```ruby
 Caracal::Document.save 'example.docx' do |docx|
   # page 1
   docx.h1 'Page 1 Header'
   docx.hr
-  docx.br
+  docx.p
   docx.h2 'Section 1'
   docx.p  'Lorem ipsum dolor....'
-  docx.br
+  docx.p
   docx.table @my_data, border_size: 4 do
     cell_style rows[0], background: 'cccccc', bold: true
   end
   
   # page 2
   docx.page
   docx.h1 'Page 2 Header'
   docx.hr
-  docx.br
+  docx.p
   docx.h2 'Section 2'
   docx.p  'Lorem ipsum dolor....'
   docx.ul do
     li 'Item 1'
     li 'Item 2'
   end
-  docx.br
+  docx.p
   docx.img image_url('graph.png'), width: 500, height: 300
 end
 ```
 
-**You can! Read on.**
+**You can!** Read on.
 
 
 ## Why is Caracal Needed?
 
 We created Caracal to satisfy a genuine business requirement.  We were working on a system that produced a periodic PDF report and our clients asked if the report could instead be generated as a Word document, which would allow them to perform edits before passing the report along to their clients.
@@ -328,11 +328,12 @@
   italic    false           # sets the font style.
   underline false           # sets whether or not to underline the text.  
   align     :left           # sets the alignment. accepts :left, :center, :right, and :both.
   line      360             # sets the line height. units in twips.
   top       100             # sets the spacing above the paragraph. units in twips.
-  bottom    0               # sets the spacing below the paragraph. units in twips.end
+  bottom    0               # sets the spacing below the paragraph. units in twips.
+end
 ```
 
 Caracal establishes a standard set of default styles for every document. Default styles can be overridden by issuing a `style` command referencing an existing id. Default style ids are:
 
 * Normal
@@ -346,11 +347,11 @@
 * Heading6
 
 
 ### Paragraphs
 
-Paragrpah text can be added using the `p` method.  The method accepts several optional parameters for controlling the style and behavior of the paragrpah. 
+Paragraph text can be added using the `p` method.  The method accepts several optional parameters for controlling the style and behavior of the paragrpah. 
 
 In its simple form, a paragraph accepts a text string and formatting options.
 
 ```ruby
 docx.p 'Sample text.'
@@ -374,10 +375,12 @@
 docx.p do
   text 'Here is a sentence with a ', style: 'custom_style'
   link 'link', 'https://www.example.com'
   text ' to something awesome', color: '555555', size: 32, bold: true, italic: true, underline: true
   text '.'
+  br
+  text 'This text follows a line break.'
 end
 ```
 
 
 ### Links
@@ -429,17 +432,27 @@
 ```
 
 
 ### Line Breaks
 
-Line breaks can be added via the `br` method.  The method accepts no parameters.
+Line breaks can be added via the `br` method inside paragraphs.
 
 ```ruby
-docx.br     # adds a blank line using the default paragrpah style.
+docx.p do
+  text 'This sentence precedes the line break.'
+  br
+  text 'This sentence follows the line break.'
+end
 ```
 
+Line breaks only work instead paragraph-like commands. If you want to create an empty line between two paragraphs, use an empty paragraph instead.
 
+```ruby
+docx.p
+```
+
+
 ### Lists
 
 Ordered lists can be added using the `ol` and `li` methods.  The `li` method substantially follows the same rules as the the `p` method.
 
 ```ruby
@@ -447,10 +460,12 @@
   li 'First item'
   li do 
     text 'Second item with a '
     link 'link', 'http://www.google.com'
     text '.'
+    br
+    text 'This sentence follows a line break.'
   end
 end
 ```
 
 Similarly, unordered lists can be added using the `ul` and `li` methods.
@@ -460,10 +475,12 @@
   li 'First item'
   li do 
     text 'Second item with a '
     link 'link', 'http://www.google.com'
     text '.'
+    br
+    text 'This sentence follows a line break.'
   end
 end
 ```
 
 Lists can nested as many levels deep as you wish and mixed in any combination.
@@ -586,10 +603,10 @@
     left                 # sets the left margin. defaults to 0. units in twips.
     right                # sets the right margin. defaults to 0. units in twips.
   end
   
   p 'This is a sentence above an image.'
-  br
+  p
   img image_url('example.png'), width: 200, height: 100
 end  
 ```