[Docs] Correct description of "Read More" links in Summaries

Also revise some paragraphs for succinctness.

Fixes #788

docs/content/content/summaries.md

@@ -10,25 +10,28 @@ title: Summaries
 weight: 65
 ---
 
-Hugo generates summaries of content for easily showing snippets in summary views. The summary view snippets are automatically generated by Hugo. Where a piece of content is split for the content summary depends on whether the split is Hugo-defined or user-defined.
+With the use of the `.Summary` [page variable](/templates/variables/), Hugo can generate summaries of content for easily showing snippets in summary views. The summary view snippets are automatically generated by Hugo. Where a piece of content is split for the content summary depends on whether the split is Hugo-defined or user-defined.
 
-Content summaries provide links to the original content, usually in the form of a `Read More` link.
+Content summaries may also provide links to the original content, usually in the form of a "Read More..." link, with the help of the `.RelPermalink` or `.Permalink` variable, as well as the `.Truncated` boolean variable to determine whether such "Read More..." link is necessary.
 
 ## Hugo-defined: automatic summary split
 
-By default, Hugo automatically splits content after 70 words, with the content prior to the split being used for the content summary. This way you don't have to worry about content summary unless you want to customize it; the summary is automatically created for you, and available to be used by Hugo, without any additional work on your part.
+By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` variable, which you may use in your templates.
 
-When using automatic summaries, Hugo will strip all HTML tags from the summary.
+* Pros: Automatic, no additional work on your part.
+* Cons: All HTML tags are stripped from the summary, and the first 70 words, whether they belong to a heading or to different paragraphs, are all lumped into one paragraph.  Some people like it, but some people don't.
 
 ## User-defined: manual summary split:
 
-Hugo also provides an easy way to customize where a piece of content will be split with its summary content divider: <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code>. The summary content divider is Hugo's version of a "more tag", "summary divider", "excerpt separator", etc. found in other systems. For the summary content divider to be valid, it must be entered exactly as <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code>, all lowercase with no additional spaces or other characters between the <code>&#60;&#33;&#45;&#45;</code> and <code>&#45;&#45;&#62;</code> tags.
+Alternatively, you may adding the <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider[^1] where you want to split the article.  Content prior to the summary divider will be used as that content's summary, and stored into the `.Summary` variable with all HTML formatting intact.
 
-If the summary content divider exists within a piece of content, Hugo will split the content at that point instead of its default split point of 70 words. The content prior to the summary content divider will be used as that content's summary, and the summary content divider will be replaced with a `Read More` link. When the full content is rendered, the summary content divider, <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code>, is elided from the output.
+[^1]: The **summary divider** is also called "more tag", "excerpt separator", etc. in other literature.
 
-When using user-defined summaries, <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code>, Hugo will preserve the HTML in the summary.
+* Pros: Freedom, precision, and improved rendering.  All formatting is preserved.
+* Cons: Need to remember to type <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> in your content file.  :-)
+
+Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly, i.e. all lowercase with no whitespace, otherwise it would be treated as regular comment and ignored.
 
-The summary content divider only applies to the content that it appears in.
 
 ## Showing Summaries
 
@@ -36,7 +39,14 @@ You can show content summaries with the following code. You could do this, for e
 
     {{ range first 10 .Data.Pages }}
       <div class="summary">
-        <h4><a href="{{ .Permalink }}">{{ .Title }}</a></h4>
+        <h4><a href="{{ .RelPermalink }}">{{ .Title }}</a></h4>
         {{ .Summary }}
       </div>
+      {{ if .Truncated }}
+      <div class="read-more-link">
+        <a href="{{ .RelPermalink }}">Read More…</a>
+      </div>
+      {{ end }}
     {{ end }}
+
+Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated, i.e. when the summary contains the entire article.

docs/content/templates/variables.md

@@ -24,7 +24,8 @@ matter, content or derived from file location.
 
 **.Title**  The title for the content.<br>
 **.Content** The content itself, defined below the front matter.<br>
-**.Summary** A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page.<br>
+**.Summary** A generated summary of the content for easily showing a snippet in a summary view. Note that the breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page.  See [Summaries](/content/summaries/) for more details.<br>
+**.Truncated** A boolean, `true` if the `.Summary` is truncated.  Useful for showing a "Read more..." link only if necessary.  See [Summaries](/content/summaries/) for more details.<br>
 **.Description** The description for the content.<br>
 **.Keywords** The meta keywords for this content.<br>
 **.Date** The date the content is associated with.<br>