From 8fe2dbe723c413d7faf6d6c5a42305a858efc518 Mon Sep 17 00:00:00 2001
From: Dave Henderson <dhenderson@gmail.com>
Date: Sun, 23 Oct 2022 12:56:59 -0400
Subject: [PATCH] fixup! Deprecate non-pipelineable strings aliases

---
 docs-src/content/functions/strings.yml | 38 +++++++++++++++++++++----
 docs/content/functions/strings.md      | 39 ++++++++++++++++++++++----
 2 files changed, 67 insertions(+), 10 deletions(-)

diff --git a/docs-src/content/functions/strings.yml b/docs-src/content/functions/strings.yml
index 7bd02ac35..532136292 100644
--- a/docs-src/content/functions/strings.yml
+++ b/docs-src/content/functions/strings.yml
@@ -139,12 +139,24 @@ funcs:
         [bar baz foo]
   - name: strings.Split
     description: |
-      Creates a slice by splitting a string on a given delimiter.
+      Slices `input` into the substrings separated by `separator`, returning a
+      slice of the substrings between those separators. If `input` does not
+      contain `separator` and `separator` is not empty, returns a single-element
+      slice whose only element is `input`.
+
+      If `separator` is empty, it will split after each UTF-8 sequence. If
+      both inputs are empty (i.e. `strings.Split "" ""`), it will return an
+      empty slice.
+
+      This is equivalent to [`strings.SplitN`](#strings-splitn) with a `count`
+      of `-1`.
+
+      Note that the delimiter is not included in the resulting elements.
     pipeline: true
     arguments:
       - name: separator
         required: true
-        description: the string sequence to split
+        description: the delimiter to split on, can be multiple characters
       - name: input
         required: true
         description: the input string
@@ -155,15 +167,31 @@ funcs:
         Hello, Bart
         Hello, Lisa
         Hello, Maggie
+      - |
+        $ gomplate -i '{{range strings.Split "," "One,Two,Three" }}{{.}}{{"\n"}}{{end}}'
+        One
+        Two
+        Three
   - name: strings.SplitN
     description: |
-      Creates a slice by splitting a string on a given delimiter. The count determines
-      the number of substrings to return.
+      Slices `input` into the substrings separated by `separator`, returning a
+      slice of the substrings between those separators. If `input` does not
+      contain `separator` and `separator` is not empty, returns a single-element
+      slice whose only element is `input`.
+
+      The `count` determines the number of substrings to return:
+
+      * `count > 0`: at most `count` substrings; the last substring will be the
+        unsplit remainder.
+      * `count == 0`: the result is nil (zero substrings)
+      * `count < 0`: all substrings
+
+      See [`strings.Split`](#strings-split) for more details.
     pipeline: true
     arguments:
       - name: separator
         required: true
-        description: the string sequence to split
+        description: the delimiter to split on, can be multiple characters
       - name: count
         required: true
         description: the maximum number of substrings to return
diff --git a/docs/content/functions/strings.md b/docs/content/functions/strings.md
index dcbcda454..311bcf404 100644
--- a/docs/content/functions/strings.md
+++ b/docs/content/functions/strings.md
@@ -209,7 +209,19 @@ $ gomplate -i '{{ (coll.Slice "foo" "bar" "baz") | strings.Sort }}'
 
 ## `strings.Split`
 
-Creates a slice by splitting a string on a given delimiter.
+Slices `input` into the substrings separated by `separator`, returning a
+slice of the substrings between those separators. If `input` does not
+contain `separator` and `separator` is not empty, returns a single-element
+slice whose only element is `input`.
+
+If `separator` is empty, it will split after each UTF-8 sequence. If
+both inputs are empty (i.e. `strings.Split "" ""`), it will return an
+empty slice.
+
+This is equivalent to [`strings.SplitN`](#strings-splitn) with a `count`
+of `-1`.
+
+Note that the delimiter is not included in the resulting elements.
 
 ### Usage
 
@@ -224,7 +236,7 @@ input | strings.Split separator
 
 | name | description |
 |------|-------------|
-| `separator` | _(required)_ the string sequence to split |
+| `separator` | _(required)_ the delimiter to split on, can be multiple characters |
 | `input` | _(required)_ the input string |
 
 ### Examples
@@ -236,11 +248,28 @@ Hello, Bart
 Hello, Lisa
 Hello, Maggie
 ```
+```console
+$ gomplate -i '{{range strings.Split "," "One,Two,Three" }}{{.}}{{"\n"}}{{end}}'
+One
+Two
+Three
+```
 
 ## `strings.SplitN`
 
-Creates a slice by splitting a string on a given delimiter. The count determines
-the number of substrings to return.
+Slices `input` into the substrings separated by `separator`, returning a
+slice of the substrings between those separators. If `input` does not
+contain `separator` and `separator` is not empty, returns a single-element
+slice whose only element is `input`.
+
+The `count` determines the number of substrings to return:
+
+* `count > 0`: at most `count` substrings; the last substring will be the
+  unsplit remainder.
+* `count == 0`: the result is nil (zero substrings)
+* `count < 0`: all substrings
+
+See [`strings.Split`](#strings-split) for more details.
 
 ### Usage
 
@@ -255,7 +284,7 @@ input | strings.SplitN separator count
 
 | name | description |
 |------|-------------|
-| `separator` | _(required)_ the string sequence to split |
+| `separator` | _(required)_ the delimiter to split on, can be multiple characters |
 | `count` | _(required)_ the maximum number of substrings to return |
 | `input` | _(required)_ the input string |