Changes anchors and de-capitalizes headers #2223 #1303

Author: JJ

doc/Language/functions.pod6

@@ -20,7 +20,7 @@ types of arguments, and the return value.
 
 Introspection on subroutines is provided via L<C<Routine>|/type/Routine>.
 
-=head1 Defining/Creating/Using Functions
+=head1 Defining/Creating/Using functions
 
 =head2 X<Subroutines|declarator,sub>
 
@@ -100,7 +100,7 @@ Or even
     say { $^a ** 2 + $^b ** 2 }(3, 4)            # OUTPUT: «25␤»
 
 
-=head2 X«Blocks and Lambdas|syntax,->»
+=head2 X«Blocks and lambdas|syntax,->»
 
 Whenever you see something like C«{ $_ + 42 }»,
 C«-> $a, $b { $a ** $b }», or C«{ $^text.indent($:spaces) }», that's
@@ -128,7 +128,7 @@ sub formatB<(Str $s)> { ... }
 Details about the syntax and use of signatures can be found in the
 L<documentation on the C<Signature> class|Signature>.
 
-=head3 Automatic Signatures
+=head3 Automatic signatures
 
 X<|@_>X<|%_>
 If no signature is provided but either of the two automatic variables C<@_> or
@@ -202,7 +202,7 @@ values.
     put b.perl;
     # OUTPUT: «\("a", "b", "c")␤»
 
-=head2 Return Type Constraints
+=head2 Return type constraints
 
 Perl 6 has many ways to specify a function's return type:
 
@@ -427,13 +427,13 @@ at /tmp/hDM1N2OAOo:1
 Anonymous sub cannot be declared C<only>. C<only sub {}'> will throw an error of
 type, surprisingly, C<X::Anon::Multi>.
 
-=head1 Conventions and Idioms
+=head1 Conventions and idioms
 
 While the dispatch system described above provides a lot of flexibility,
 there are some conventions that most internal functions, and those in
 many modules, will follow.
 
-=head2 Slurpy Conventions
+=head2 Slurpy conventions
 
 Perhaps the most important one of these conventions is the way slurpy list
 arguments are handled.  Most of the time, functions will not automatically
@@ -490,7 +490,7 @@ grab($b);        # OUTPUT: «grab 1␤grab 2␤»
 my \c = (1, 2);  # Sigilless variables always bind, even with '='
 grab(c);         # OUTPUT: «grab 1␤grab 2␤»
 
-=head1 Functions are First-Class Objects
+=head1 Functions are first-class objects
 
 Functions and other code objects can be passed around as values, just like any
 other object.
@@ -519,7 +519,7 @@ which applies a function to each input element:
     my @squared = map &square,  1..5;
     say join ', ', @squared;        # OUTPUT: «1, 4, 9, 16, 25␤»
 
-=head2 Z<>Infix Form
+=head2 Z<>Infix form
 
 To call a subroutine with 2 arguments like an infix operator, use a subroutine
 reference surrounded by C<[> and C<]>.
@@ -528,6 +528,7 @@ reference surrounded by C<[> and C<]>.
     say 21 [&plus] 21;
     # OUTPUT: «42␤»
 
+X<|closures>
 =head2 Closures
 
 All code objects in Perl 6 are I<closures>, which means they can reference
@@ -542,12 +543,12 @@ lexical variables from an outer scope.
     $generated(); # OUTPUT: «42␤»
 
 Here, C<$y> is a lexical variable inside C<generate-sub>, and the inner
-subroutine that is returned uses it. By the time that the inner sub is called,
+subroutine that is returned uses it. By the time that inner sub is called,
 C<generate-sub> has already exited. Yet the inner sub can still use C<$y>,
 because it I<closed> over the variable.
 
-Another closure example is the use of L<map|/type/List#routine_map>
-to multiply a list of numbers:
+Another closure example is the use of L<map|/type/List#routine_map> to multiply
+a list of numbers:
 
     my $multiply-by = 5;
     say join ', ', map { $_ * $multiply-by }, 1..5;     # OUTPUT: «5, 10, 15, 20, 25␤»
@@ -614,7 +615,7 @@ pragma C<use soft;> to prevent inlining to allow wrapping at runtime.
 
 =comment Important ones: candidates, wrap, unwrap, assuming, arity, count
 
-=head1 Defining Operators
+=head1 Defining operators
 
 Operators are just subroutines with funny names. The funny names are composed
 of the category name (C<infix>, C<prefix>, C<postfix>, C<circumfix>,
@@ -964,9 +965,8 @@ multi a(Int $x) {
 say (a 10); # OUTPUT: «36288002␤»
 =end code
 
-=head2 sub nextcallee
-
 X<|dispatch,nextcallee>
+=head2 sub nextcallee
 
 Redispatch may be required to call a block that is not the current scope what
 provides C<nextsame> and friends with the problem to referring to the wrong
@@ -997,9 +997,9 @@ executed in parallel, after some timeout, and then returns. We can't use
 C<nextsame> here, because it'd be trying to C<nextsame> the Promise's block
 instead of our original routine.
 
-=head2 wrapped routines
-
 X<|dispatch,wrapped routines>
+=head2 Wrapped routines
+
 
 Besides those are mentioned above, re-dispatch is helpful in more situations.
 One is for dispatching to wrapped routines:
@@ -1020,7 +1020,7 @@ say square-root(4);     # OUTPUT: «2␤»
 say square-root(-4);    # OUTPUT: «0+2i␤»
 =end code
 
-=head2 routines of parent class
+=head2 Routines of parent class
 
 Another use case is to re-dispatch to methods from parent classes.
 
@@ -1035,7 +1035,7 @@ class LoggedVersion is Version {
 say LoggedVersion.new('1.0.2');
 =end code
 
-=head1 Coercion Types
+=head1 Coercion types
 
 Coercion types force a specific type for routine arguments while allowing
 the routine itself to accept a wider input. When invoked, the arguments are
@@ -1112,16 +1112,15 @@ for (2,4) X (1,2) -> ($a,$b) {
 In this case, we are coercing an C<Int> to a C<Bool>, which is then printed (put
 into a string context) in the C<for> loop that calls the function.
 
-=head1 sub MAIN
-
 X<|MAIN>X<|command line arguments>
+=head1 sub MAIN
 
-The sub with the special name C<MAIN> is executed after all relevant phasers. Its signature is the means by which command line arguments can be
-parsed. Multi methods are supported and a usage method is automatically
-generated and displayed if no command line arguments are provided. All command
-line arguments are also available in
-L<C<@*ARGS>|/language/variables#Dynamic_variables>, which can be mutated before
-being processed by C<MAIN>.
+The sub with the special name C<MAIN> is executed after all relevant phasers.
+Its signature is the means by which command line arguments can be parsed. Multi
+methods are supported and a usage method is automatically generated and
+displayed if no command line arguments are provided. All command line arguments
+are also available in L<C<@*ARGS>|/language/variables#Dynamic_variables>, which
+can be mutated before being processed by C<MAIN>.
 
 Unlike other ordinary functions, any return value provided by C<MAIN> will be
 ignored by the invoker, even if explicitly set by means of a C<return> statement
@@ -1213,7 +1212,7 @@ unit sub MAIN( Int :$length = 24,
 Note that this is only appropriate if you do not need a C<proto> or C<multi> definition.
 
 X<|USAGE>X<|$*USAGE>
-=head1 sub USAGE
+=head1 sub C<USAGE>
 
 If no multi candidate of C<MAIN> is found for the given command line
 parameters, the sub C<USAGE> is called. If no such method is found,