Revises Signature

:tick: Reflow
:tick: Eliminates Unneeded Caps
:tick: Eliminates uneeded categories refs #1410

Author: JJ

doc/Type/Signature.pod6

@@ -13,9 +13,9 @@ you need to pass to the code or function in order to call it.
 Passing arguments to a signature I<binds> the arguments, contained in
 a L<Capture>, to the signature.
 
-X<|signature literal (Signature)>
-X<|:() (Signature)>
-=head1 Signature Literals
+X<|signature literal>
+X<|:()>
+=head1 Signature literals
 
 Signatures appear inside parentheses after L<subroutine|/type/Sub> and
 L<method|/type/Method> names, on blocks after a C<< -> >> or C<< <-> >> arrow,
@@ -79,7 +79,7 @@ keys of the Hash.
     say %h ~~ :(:$left, :$right);
     # OUTPUT: «True␤»
 
-=head2 Parameter Separators
+=head2 Parameter separators
 
 A signature consists of zero or more I<L<parameters|Parameter>>, separated by
 commas.
@@ -102,7 +102,7 @@ is bound to.
     }
     say Foo.whoami; # OUTPUT: «Well I'm class Foo, of course!␤»
 
-X<|type constraint (Signature)>
+X<|type constraint>
 X<|Constraint>
 =head2 Type constraints
 
@@ -128,9 +128,9 @@ subset is based, in this case C<Int>. If it fails, a C<Type check> error is
 produced. Once that filter is cleared, the constraint that defined the subset is
 checked, producing a C<I<Constraint> type check> error if it fails.
 
-X<|anonymous arguments (Signature)> Anonymous arguments are fine too, if you
-don't actually need to refer to a parameter by name, for instance to distinguish
-between different signatures in a
+X<|anonymous arguments>
+Anonymous arguments are fine too, if you don't actually need to refer to a
+parameter by name, for instance to distinguish between different signatures in a
 L<multi|/language/functions#index-entry-declarator_multi-Multi-dispatch> or to
 check the signature of a L<Callable>.
 
@@ -140,7 +140,7 @@ check the signature of a L<Callable>.
 
 Type constraints may also be L<type captures|/type/Signature#Type_Captures>.
 
-X<|where clause (Signature)>
+X<|where clause>
 In addition to those I<nominal> types, additional constraints can
 be placed on parameters in the form of code blocks which must return
 a true value to pass the type check
@@ -193,7 +193,7 @@ the C<where>-clause inside the sub-signature.
     # foo 2, 3;
     # OUTPUT: «Constraint type check failed in binding to parameter '$b'…»
 
-=head3 Constraining Optional Arguments
+=head3 Constraining optional arguments
 
 L<Optional arguments|#Optional_and_Mandatory_Parameters> can have constraints,
 too. Any C<where> clause on any parameter will be executed, even if it's
@@ -202,7 +202,7 @@ against undefined values within the C<where> clause.
 
     sub f(Int $a, UInt $i? where { !$i.defined or $i > 5 } ) { ... }
 
-=head3 Constraining Slurpy Arguments
+=head3 Constraining slurpy arguments
 
 L<Slurpy arguments|#Slurpy_(A.K.A._Variadic)_Parameters> can not have type
 constraints. A C<where>-clause in conjunction with a L<Junction|/type/Junction>
@@ -214,7 +214,7 @@ can be used to that effect.
     CATCH { default { say .^name, ' ==> ', .Str }  }
     # OUTPUT: «[42]␤Constraint type check failed in binding to parameter '@a' ...»
 
-=head3 Constraining named Arguments
+=head3 Constraining named arguments
 
 Constraints against L<Named arguments|#Positional_vs._Named> apply to the value
 part of the L<colon-pair|/type/Pair>.
@@ -225,8 +225,11 @@ part of the L<colon-pair|/type/Pair>.
     # OUTPUT: «X::TypeCheck::Binding::Parameter ==> Type check failed in
     # binding to parameter '$i'; expected Int but got Str ("forty-two")␤»
 
-=head3 X<Constraining Defined and Undefined Values|
-         type constraint,:D;type constraint,:U;type constraint,:_>
+    |
+X<|type constraint,:D>
+X<|type constraint,:U>
+X<|type constraint,:_>
+=head3 Constraining defined and undefined values
 
 Normally, a type constraint only checks whether the value of the parameter is of
 the correct type. Crucially, both I<object instances> and I<type objects> will
@@ -254,10 +257,10 @@ and type objects (C<Int>). Consider the following code:
     #     (Str:D $: *%_)»
     say limit-lines "a \n b", Int # Always returns the max number of lines
 
-Here we really only want to deal with string instances, not
-type objects. To do this, we can use the C<:D> type constraint.  This constraint
-checks that the value passed is an I<object instance>, in a similar fashion to calling
-its L<DEFINITE|/language/mop#DEFINITE> method.
+Here we really only want to deal with string instances, not type objects. To do
+this, we can use the C<:D> type constraint.  This constraint checks that the
+value passed is an I<object instance>, in a similar fashion to calling its
+L<DEFINITE|/language/mop#DEFINITE> method.
 
 To warm up, let's apply C<:D> to the right-hand side of our humble C<Int> example:
 
@@ -349,7 +352,7 @@ a type object, which would fail the definiteness constraint.
     sub divide (Int:D :$a = 2, Int:D :$b!) { say $a/$b }
     divide :1a, :2b; # OUTPUT: «0.5␤»
 
-=head3 X«Constraining signatures of Callables|Callable (constrain)»
+=head3 Constraining signatures of C<Callable>s
 
 A L<Callable> parameter can be constrained by its signature, by specifying
 a L<Signature> literal right after the parameter (no whitespace allowed):
@@ -368,14 +371,15 @@ others, you need to use the long version:
     # f(&g); # Constraint type check failed
     f(&h);   # OUTPUT: «ten10␤»
 
-=head3 X«Constraining Return Types|-->;returns»
+=head3 Constraining return types
 
-There are multiple ways to constrain return types on a L<Routine|/type/Routine>. All versions below
-are currently valid and will force a type check on successful execution of a routine.
+There are multiple ways to constrain return types on a L<Routine|/type/Routine>.
+All versions below are currently valid and will force a type check on successful
+execution of a routine.
 
-L<C<Nil>|/type/Nil> and L<C<Failure>|/type/Failure> are always allowed as return types,
-regardless of any type constraint. This allows L<Failure|/type/Failure> to be returned
-and passed on down the call chain.
+L<C<Nil>|/type/Nil> and L<C<Failure>|/type/Failure> are always allowed as return
+types, regardless of any type constraint. This allows L<Failure|/type/Failure>
+to be returned and passed on down the call chain.
 
     sub foo(--> Int) { Nil };
     say foo.perl; # OUTPUT: «Nil␤»
@@ -449,7 +453,7 @@ except the C<$var> is a definition for a routine.
     =for code :skip-test
     my 42 sub bad-answer {};  # This will fail.
 
-=head3 X<Coercion Type|coercion type (signature)>
+=head3 X<Coercion type>
 
 To accept one type but coerce it automatically to another, use the
 accepted type as an argument to the target type. If the accepted type is
@@ -489,9 +493,13 @@ for 2,4, *²  … 256 -> $a {
 #          256² is 5 figures long␤»
 =end code
 
-In this example, coercing the return type to C<String> allows us to directly apply string methods, such as the number of characters.
+In this example, coercing the return type to C<String> allows us to directly
+apply string methods, such as the number of characters.
 
-=head2 X<Slurpy (A.K.A. Variadic) Parameters|parameter,*@;parameter,*%,slurpy argument (Signature)>
+X<|parameter,*@>
+X<|parameter,*%>
+X<|slurpy argument>
+=head2 Slurpy (A.K.A. variadic) parameters
 
 A function is X<variadic> if it can take a varying number of arguments; that is,
 its arity is not fixed. Therefore, optional, named, and slurpy parameters are
@@ -535,7 +543,7 @@ Slurpy parameters have special behaviors when combined with some
 L<traits and modifiers|#Parameter_Traits_and_Modifiers>,
 as described in L<the section on slurpy array parameters|/type/Signature#Types_of_Slurpy_Array_Parameters>.
 
-=head2 Types of Slurpy Array Parameters
+=head2 Types of slurpy array parameters
 
 There are three variations to slurpy array parameters.
 
@@ -549,7 +557,7 @@ Each will be described in detail in the next few sections. As the difference
 between each is a bit nuanced, examples are provided for each to demonstrate how
 each slurpy convention varies from the others.
 
-=head3 Flattened Slurpy
+=head3 Flattened slurpy
 
 Slurpy parameters declared with one asterisk will flatten arguments by
 dissolving one or more layers of bare L<Iterable|/type/Iterable>s.
@@ -568,10 +576,11 @@ a(($_ for 1, 2, 3));       # OUTPUT: «[1, 2, 3]»
 A single asterisk slurpy flattens all given iterables, effectively hoisting any
 object created with commas up to the top level.
 
-=head3 X<Unflattened Slurpy|parameter, **@>
+=head3 X<Unflattened slurpy|parameter, **@>
 
-Slurpy parameters declared with two stars do not flatten any L<Iterable|/type/Iterable> arguments
-within the list, but keep the arguments more or less as-is:
+Slurpy parameters declared with two stars do not flatten any
+L<Iterable|/type/Iterable> arguments within the list, but keep the arguments
+more or less as-is:
 
 =begin code
 my @array = <a b c>;
@@ -587,14 +596,15 @@ b(($_ for 1, 2, 3));       # OUTPUT: «[(1, 2, 3),]␤»
 The double asterisk slurpy hides the nested comma objects and leaves them as-is
 in the slurpy array.
 
-=head3 Single Argument Rule Slurpy
-X<|+ (Single Argument Rule Slurpy)>
+X<|+ (Single argument rule slurpy)>
+=head3 Single argument rule slurpy
+
 
 A slurpy parameter created using a plus engages the I<"single argument rule">,
 which decides how to handle the slurpy argument based upon context. Basically,
-if only a single argument is passed and that argument is L<Iterable|/type/Iterable>, that argument
-is used to fill the slurpy parameter array. In any other case, C<+@> works like
-C<**@>.
+if only a single argument is passed and that argument is
+L<Iterable|/type/Iterable>, that argument is used to fill the slurpy parameter
+array. In any other case, C<+@> works like C<**@>.
 
 =begin code
 my @array = <a b c>;
@@ -609,10 +619,10 @@ c(($_ for 1, 2, 3));       # OUTPUT: «[1, 2, 3]␤»
 
 For additional discussion and examples, see L<Slurpy Conventions for Functions|/language/functions#Slurpy_Conventions>.
 
-=head2 Type Captures
-X<|Type Capture (signature)>
+X<|Type capture>
+=head2 Type captures
 
-Type Captures allow deferring the specification of a type constraint to the time
+Type captures allow deferring the specification of a type constraint to the time
 the function is called. They allow referring to a type both in the signature and
 the function body.
 
@@ -630,9 +640,9 @@ the function body.
     my &s = f(10, 2, Int.new / Int.new);
     say s(2); # 10 / 2 * 2 == 10
 
-X<|positional argument (Signature)>
-X<|named argument (Signature)>
-=head2 Positional vs. Named Arguments
+X<|positional argument>
+X<|named argument>
+=head2 Positional vs. named arguments
 
 An argument can be I<positional> or I<named>. All arguments are positional,
 except slurpy hash and arguments marked with a leading colon C<:>.
@@ -664,8 +674,8 @@ variable name:
     sub named(:official($private)) { "Official business!" if $private }
     named :official;
 
-X<|aliases (Signature)>
-=head2 Argument Aliases
+X<|aliases>
+=head2 Argument aliases
 The L<colon-pair|/type/Pair> syntax can be used to provide aliases for arguments:
 
     sub alias-named(:color(:$colour), :type(:class($kind))) {
@@ -709,8 +719,8 @@ before slipping.
     say C.new(|%h.Map);
     # OUTPUT: «C.new(x => 5, y => 20, z => [1, 2])␤»
 
-X<|optional argument (Signature)>
-=head2 Optional and Mandatory Parameters
+X<|optional argument>
+=head2 Optional and mandatory arguments
 
 Positional parameters are mandatory by default, and can be made optional
 with a default value or a trailing question mark:
@@ -719,7 +729,7 @@ with a default value or a trailing question mark:
     $ = :($base = 10);      # optional parameter, default value 10
     $ = :(Int $x?);         # optional parameter, default is the Int type object
 
-X<|mandatory named argument (Signature)>
+X<|mandatory named argument>
 Named parameters are optional by default, and can be made mandatory with a
 trailing exclamation mark:
 
@@ -733,14 +743,14 @@ notionally) computed anew for each call
     $ = :($goal, $accuracy = $goal / 100);
     $ = :(:$excludes = ['.', '..']);        # a new Array for every call
 
-=head2 Dynamic Variables
+=head2 Dynamic variables
 
 L<Dynamic variables|/language/variables#The_*_Twigil> are allowed in signatures
 although they don't provide special behaviour because argument binding does
 connect two scopes anyway.
 
-X<|destructuring arguments (Signature)>
-=head2 Destructuring Parameters
+X<|destructuring arguments>
+=head2 Destructuring arguments
 
 Parameters can be followed by a sub-signature in parentheses, which will
 destructure the argument given. The destructuring of a list is just its
@@ -787,8 +797,7 @@ name in parentheses.
     foo(42, "answer");
     # OUTPUT: «called with \(42, "answer")␤»
 
-X<|Long Names>
-=head2 Long Names
+=head2 X<Long names>
 
 To exclude certain parameters from being considered in multiple dispatch,
 separate them with a double semi-colon.
@@ -797,7 +806,7 @@ separate them with a double semi-colon.
     f(10, 'answer');
     # OUTPUT: «10, answer, Any␤»
 
-=head2 X<Capture Parameters|parameter,|>
+=head2 X<Capture parameters|parameter,|>
 
 Prefixing a parameter with a vertical bar C<|> makes the parameter a
 L<C<Capture>>, using up all the remaining positional and named
@@ -816,7 +825,7 @@ operator C<|>.
     b(42, "answer");
     # OUTPUT: «Capture␤Int Str␤»
 
-=head2 Parameter Traits and Modifiers
+=head2 Parameter traits and modifiers
 
 By default, parameters are bound to their argument and marked as
 read-only. One can change that with traits on the parameter.