diff --git a/manual/src/ch05-05-method.md b/manual/src/ch05-05-method.md
index f05077a882b2ec8f96bce65c4b85c3008d25ac5d..f9c251151d147378f6654e793c66590091421341 100644
--- a/manual/src/ch05-05-method.md
+++ b/manual/src/ch05-05-method.md
@@ -1,22 +1,28 @@
# Method Expansions
-There are two forms of methods within Ion: array and string methods. Array methods are methods which return arrays,
-and string methods are methods which return strings. Invoking an array method requires denoting that the method
-is an array method with the '@' character, whereas using '$' for string methods -- same as process and variable
-expansions. The general syntax of a method is '<sigil><name_of_method>(<input>, <arg1> <arg2> <args>...)'.
+There are two forms of methods within Ion: array methods, and string methods. Array methods are
+methods which return arrays, and string methods are methods which return strings. The distinction
+is made between the two by the sigil that is invoked when calling a method. For example, if the
+method is denoted by the `$` sigil, then it is a string method. Otherwise, if it is denoted by the
+`@` sigil, then it is an array method. Example as follows:
-Methods are executed at the same time as other expansions, so this leads to a performance optimization when combining
-methods with other methods or expansions. Ion includes a number of these methods for common use cases, but it is
-possible to create and/or install new methods to enhance the functionality of Ion. Just ensure that systems executing
-your Ion scripts that require those plugins are equipped with and have those plugins enabled.
+```ion
+echo $method_name(variable)
+for elem in @method_name(variable); echo $elem; end
+```
+
+Methods are executed at the same time as other expansions, so this leads to a performance
+optimization when combining methods with other methods or expansions. Ion includes a number of these
+methods for common use cases, but it is possible to create and/or install new methods to enhance the
+functionality of Ion. Just ensure that systems executing your Ion scripts that require those plugins
+are equipped with and have those plugins enabled. If you have ideas for useful methods that would
+be worth including in Ion by default, feel free to open a feature request to discuss the idea.
## Methods Support Inline Expressions
-When parsing the input element, if the element is a literal that is not defined as an expression, the given value
-will be treated as the name of a variable that corresponds to the default input type for that method. Basically,
-`array` would indicate to the parser that we are calling a variable of that name, whereas `"array"`, `'array'`,
-`@array`, `$array`, `$(cmd)`, etc. would indicate to the parser that we are evaluating and using the expression's
-output as the input.
+So we heard that you like methods, so we put methods in your methods. Ion methods accept taking
+expressions as their arguments -- both for the input parameter, and any supplied arguments to
+control the behavior of the method.
```ion
echo $method($(cmd...), arg)
@@ -27,6 +33,31 @@ echo $method(string_var)
echo $method("actual value", arg)
```
+## Overloaded Methods
+
+Some methods may also perform different actions when supplied a different type. The `$len()` method,
+for example, will report the number of graphemes within a string, or the number of elements within
+an array. Ion is able to determine which of the two were provided based on the first character
+in the expression. Quoted expressions, and expressions with start with `$`, are strings; whereas
+expressions that start with either `[` or `@` are treated as arrays.
+
+```ion
+echo $len("a string")
+echo $len([1 2 3 4 5])
+```
+
+## Method Arguments
+
+Some methods may have their behavior tweaked by supplying some additional arguments. The `@split()`
+method, for example, may be optionally supplied a pattern for splitting. At the moment, a comma
+is used to specify that arguments are to follow the input, but each argument supplied after that
+is space-delimited.
+
+```ion
+for elem in @split("some space-delimited values"); echo $elem; end
+for elem in @split("some, comma-separated, values", ", "); echo $elem; end
+```
+
## String Methods
The following are the currently-supported string methods:
@@ -45,154 +76,152 @@ The following are the currently-supported string methods:
- [to_lowercase](#to_lowercase)
- [to_uppercase](#to_uppercase)
-### len
+### basename
-Defaults to string variables. Counts the number of graphemes in the output. If an array expression
-is supplied, it will print the number of elements in the array.
+Defaults to string variables. When given a path-like string as input, this will return the
+basename (complete filename, extension included). IE: `/parent/filename.ext` -> `filename.ext`
#### Examples
```ion
-echo $len("foobar")
-echo $len("â¤ï¸")
-echo $len([one two three four])
+echo $basename("/parent/filename.ext")
```
#### Output
```
-6
-1
-4
+filename.ext
```
-### len_bytes
+### extension
-Defaults to string variables. Similar to the `len` method, but counts the number of actual bytes
-in the output, not the number of graphemes.
+Defaults to string variables. When given a path-like string as input, this will return the
+extension of the complete filename. IE: `/parent/filename.ext` -> `ext`.
#### Examples
```ion
-echo $len_bytes("foobar")
-echo $len_bytes("â¤ï¸")
+echo $extension("/parent/filename.ext")
```
#### Output
```
-6
-6
+ext
```
-### parent
+### filename
Defaults to string variables. When given a path-like string as input, this will return the
-parent directory's name. IE: `/root/parent/filename.ext` -> `/root/parent`
+file name portion of the complete filename. IE: `/parent/filename.ext` -> `filename`.
#### Examples
```ion
-echo $parent("/root/parent/filename.ext")
+echo $filename("/parent/filename.ext")
```
#### Output
```
-/root/parent
+filename
```
-### repeat
+### join
-Defaults to string variables. When supplied with a number, it will repeat the input N
-amount of times, where N is the supplied number.
+Defaults to array variables. When given an array as input, the join string method will concatenate
+each element in the array and return a string. If no argument is given, then those elements will
+be joined by a single space. Otherwise, each element will be joined with a given pattern.
#### Examples
```ion
-echo $repeat("abc, ", 3)
+let array = [1 2 3 4 5]
+echo $join(array)
+echo $join(array, ", ")
```
#### Output
```
-abc, abc, abc
+1 2 3 4 5
+1, 2, 3, 4, 5
```
-### basename
+### len
-Defaults to string variables. When given a path-like string as input, this will return the
-basename (complete filename, extension included). IE: `/parent/filename.ext` -> `filename.ext`
+Defaults to string variables. Counts the number of graphemes in the output. If an array expression
+is supplied, it will print the number of elements in the array.
#### Examples
```ion
-echo $basename("/parent/filename.ext")
+echo $len("foobar")
+echo $len("â¤ï¸")
+echo $len([one two three four])
```
#### Output
```
-filename.ext
+6
+1
+4
```
-### extension
+### len_bytes
-Defaults to string variables. When given a path-like string as input, this will return the
-extension of the complete filename. IE: `/parent/filename.ext` -> `ext`.
+Defaults to string variables. Similar to the `len` method, but counts the number of actual bytes
+in the output, not the number of graphemes.
#### Examples
```ion
-echo $extension("/parent/filename.ext")
+echo $len_bytes("foobar")
+echo $len_bytes("â¤ï¸")
```
#### Output
```
-ext
+6
+6
```
-### filename
+### parent
Defaults to string variables. When given a path-like string as input, this will return the
-file stem of the complete filename. IE: `/parent/filename.ext` -> `filename`.
+parent directory's name. IE: `/root/parent/filename.ext` -> `/root/parent`
#### Examples
```ion
-echo $filename("/parent/filename.ext")
+echo $parent("/root/parent/filename.ext")
```
#### Output
```
-filename
+/root/parent
```
-### join
+### repeat
-Defaults to array variables. When given an array as input, the join string method will concatenate
-each element in the array and return a string. If no argument is given, then those elements will
-be joined by a single space. Otherwise, each element will be joined with a given pattern.
+Defaults to string variables. When supplied with a number, it will repeat the input N
+amount of times, where N is the supplied number.
#### Examples
```ion
-let array = [1 2 3 4 5]
-echo $join(array)
-echo $join(array, ", ")
+echo $repeat("abc, ", 3)
```
#### Output
```
-1 2 3 4 5
-1, 2, 3, 4, 5
+abc, abc, abc
```
-###
-
### replace
Defaults to string variables. Given a pattern to match, and a replacement to replace each match