Revise ref and relref function pages

Closes #1212

content/en/functions/ref.md

@@ -1,17 +1,17 @@
 ---
 title: ref
 linktitle: ref
-description: Looks up a content page by logical name.
+description: Returns the absolute permalink to a page.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2019-12-28
+lastmod: 2020-09-05
 categories: [functions]
 menu:
   docs:
     parent: "functions"
 keywords: [cross references, anchors]
-signature: ["ref . CONTENT"]
+signature: ["ref . PAGE"]
 workson: []
 hugoversion:
 relatedfuncs: [relref]
@@ -19,22 +19,33 @@ deprecated: false
 aliases: []
 ---
 
-`ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink:
+This function takes two parameters:
 
-```
+- The context of the page from which to resolve relative paths, typically the current page (`.`)
+- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site.
+
+```go-html-template
+{{ ref . "about" }}
+{{ ref . "about#anchor" }}
 {{ ref . "about.md" }}
+{{ ref . "about.md#anchor" }}
+{{ ref . "#anchor" }}
+{{ ref . "/blog/my-post" }}
+{{ ref . "/blog/my-post.md" }}
 ```
 
-{{% note "Usage Note" %}}
+To return the absolute permalink to another language version of a page:
-`ref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc.
-{{% /note %}}
 
-It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path.
+```go-html-template
-
+{{ ref . (dict "path" "about.md" "lang" "fr") }}
-``` 
-{{ ref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }} 
 ```
 
-These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
+To return the absolute permalink to another Output Format of a page:
 
-For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
+```go-html-template
+{{ ref . (dict "path" "about.md" "outputFormat" "rss") }}
+```
+
+Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). 
+
+This function is used by Hugo's built-in [`ref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/).

content/en/functions/relref.md

@@ -1,17 +1,17 @@
 ---
 title: relref
-# linktitle: relref
+linktitle: relref
-description: Looks up a content page by relative path.
+description: Returns the relative permalink to a page.
 godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
-lastmod: 2019-12-28
+lastmod: 2020-09-05
 categories: [functions]
 menu:
   docs:
     parent: "functions"
 keywords: [cross references, anchors]
-signature: ["relref . CONTENT"]
+signature: ["relref . PAGE"]
 workson: []
 hugoversion:
 relatedfuncs: [ref]
@@ -19,22 +19,40 @@ deprecated: false
 aliases: []
 ---
 
-`ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink:
+This function takes two parameters:
 
-```
+- The context of the page from which to resolve relative paths, typically the current page (`.`)
+- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site.
+
+```go-html-template
+{{ relref . "about" }}
+{{ relref . "about#anchor" }}
 {{ relref . "about.md" }}
+{{ relref . "about.md#anchor" }}
+{{ relref . "#anchor" }}
+{{ relref . "/blog/my-post" }}
+{{ relref . "/blog/my-post.md" }}
 ```
 
-{{% note "Usage Note" %}}
+The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example:
-`relref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc.
-{{% /note %}}
 
-It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path. 
+Code|baseURL|Permalink
+:--|:--|:--
+`{{ relref . "/about" }}`|`http://example.org/`|`/about/`
+`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/`
 
-``` 
+To return the relative permalink to another language version of a page:
-{{ relref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }}
+
+```go-html-template
+{{ relref . (dict "path" "about.md" "lang" "fr") }}
 ```
 
-These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref).
+To return the relative permalink to another Output Format of a page:
 
-For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/).
+```go-html-template
+{{ relref . (dict "path" "about.md" "outputFormat" "rss") }}
+```
+
+Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). 
+
+This function is used by Hugo's built-in [`relref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/).