Doc fixes

FU.pm

@@ -1046,7 +1046,7 @@ Unless specifically mentioned otherwise, all methods and functions taking or
 returning strings deal with perl Unicode strings, not raw bytes.
 
 
-=head2 Framework Configuration
+=head1 Framework Configuration
 
 =over
 
@@ -1143,7 +1143,7 @@ restart loop.
 =back
 
 
-=head2 Handlers & Routing
+=head1 Handlers & Routing
 
 =over
 
@@ -1211,7 +1211,7 @@ for a certain error code, C<500> is used as fallback.
 =back
 
 
-=head2 The 'fu' Object
+=head1 The 'fu' Object
 
 While the C<FU::> namespace is used for global configuration and utility
 functions, the C<fu> object is intended for methods that deal with request
@@ -1261,7 +1261,7 @@ Convenient short-hand for C<< fu->db->Q(@args) >>.
 
 =back
 
-=head2 Request Information
+=head1 Request Information
 
 =over
 
@@ -1307,6 +1307,16 @@ Parse, validate and return the query parameter identified by C<$name> with the
 given L<FU::Validate> schema. Calls C<< fu->error(400) >> with a useful error
 message if validation fails.
 
+To fetch a query parameter that may have multiple values, use:
+
+  my $arrayref = fu->query(q => {accept_scalar => 1});
+
+  # OR:
+  my $first_value = fu->query(q => {accept_array => 'first'});
+
+  # OR:
+  my $last_value = fu->query(q => {accept_array => 'last'});
+
 =item fu->query($schema)
 
 =item fu->query($name1 => $schema1, $name2 => $schema2, ..)
@@ -1326,16 +1336,6 @@ To fetch all query paramaters as decoded by C<query_decode()>, use:
 
   my $data = fu->query({type=>'any'});
 
-To fetch a query parameter that may have multiple values, use:
-
-  my $arrayref = fu->query(q => {accept_scalar => 1});
-
-  # OR:
-  my $first_value = fu->query(q => {accept_array => 'first'});
-
-  # OR:
-  my $last_value = fu->query(q => {accept_array => 'last'});
-
 =item fu->cookie(...)
 
 Like C<< fu->query() >> but parses the C<Cookie> request header. Beware that,
@@ -1365,7 +1365,7 @@ objects.  Refer to L<FU::MultipartFormData> for more information.
 =back
 
 
-=head2 Generating Responses
+=head1 Response Generation
 
 =over
 
@@ -1509,7 +1509,7 @@ one of the following status codes or an alias:
 
 
 
-=head2 Running the Site
+=head1 Running the Site
 
 When your script is done setting L</"Framework Configuration"> and registering
 L</"Handlers & Routing">, it should call C<FU::run> to actually start serving

FU/Log.pm

@@ -89,7 +89,7 @@ interface either; the entire point of this module is that it only handles
 process-global logging. This module mainly exists for users of the L<FU>
 framework.
 
-=head2 Configuration
+=head1 Configuration
 
 =over
 
@@ -119,7 +119,7 @@ is then used instead. This is to avoid recursion.
 
 =back
 
-=head2 Exportable function
+=head1 Exportable function
 
 =over
 

FU/MultipartFormData.pm

@@ -121,7 +121,7 @@ C<multipart/form-data>, which is typically used to handle file uploads.
 The entire request body is assumed to be in memory as a Perl string, but this
 module makes an attempt to avoid any further copies of data values.
 
-=head2 Parsing
+=head1 Parsing
 
 =over
 
@@ -138,7 +138,7 @@ tried.
 
 =back
 
-=head2 Field Object
+=head1 Field Object
 
 Each field is parsed into a field object that supports the following methods:
 

FU/Pg.pm

@@ -61,7 +61,7 @@ FU::Pg is a client module for PostgreSQL with a convenient high-level API and
 support for flexible and complex type conversions. This module interfaces
 directly with C<libpq>.
 
-=head2 Connection setup
+=head1 Connection setup
 
 =over
 
@@ -173,7 +173,7 @@ attempts to use C<$conn> throw an error.
 
 =back
 
-=head2 Querying
+=head1 Querying
 
 =over
 
@@ -420,7 +420,7 @@ Returns the respective configuration parameters.
 
 
 
-=head2 Transactions
+=head1 Transactions
 
 This module provides a convenient and safe API for I<scoped transactions> and
 I<subtransactions>. A new transaction can be started with C<< $conn->txn >>,
@@ -549,7 +549,7 @@ Just don't try to use transaction objects and manual transaction commands at
 the same time, that won't end well.
 
 
-=head2 Formats and Types
+=head1 Formats and Types
 
 The PostgreSQL wire protocol supports sending bind parameters and receiving
 query results in two different formats: text and binary. While the exact wire
@@ -752,7 +752,7 @@ I<TODO:> Methods to convert between the various formats.
 I<TODO:> Methods to query type info.
 
 
-=head2 COPY support
+=head1 COPY support
 
 You can use L<COPY
 statements|https://www.postgresql.org/docs/current/sql-copy.html> for efficient
@@ -816,7 +816,7 @@ silently discarded. An explicit C<close()> is recommended to catch errors.
 =back
 
 
-=head2 Errors
+=head1 Errors
 
 All methods can throw an exception on error. When possible, the error message
 is constructed using L<Carp>'s C<confess()>, including a full stack trace.

FU/SQL.pm

@@ -124,7 +124,7 @@ changes, see the main L<FU> module for details.
 
 =head1 DESCRIPTION
 
-=head2 Compiling SQL
+=head1 Compiling SQL
 
 All functions listed under L</"Constructing SQL"> return an object that can be
 passed to other construction functions or compiled into SQL and bind
@@ -165,7 +165,7 @@ for details.
 
 =back
 
-=head2 Constructing SQL
+=head1 Constructing SQL
 
 All of the functions below return an object with a C<compile()> method. All
 functions are exported by default.

FU/Util.pm

@@ -95,10 +95,7 @@ __END__
 
 =head1 NAME
 
-FU::Util - Miscellaneous utility functions that really should have been part of
+FU::Util - Miscellaneous Utility Functions
-a core Perl installation but aren't for some reason because the Perl community
-doesn't believe in the concept of a "batteries included" standard library.
-</rant>
 
 =head1 EXPERIMENTAL
 
@@ -113,7 +110,11 @@ changes, see the main L<FU> module for details.
 
 =head1 DESCRIPTION
 
-=head2 Boolean Stuff
+A bunch of functions that are too small (or I'm too lazy) to split out into
+separate modules. Some of these functions really ought to be part of Perl core.
+
+
+=head1 Boolean Stuff
 
 Perl has had a builtin boolean type since version 5.36 and FU uses that where
 appropriate, but there's still a lot of older code out there using different
@@ -137,7 +138,7 @@ value for C<$val>, due to C<\0> and C<\1> being considered booleans.
 
 =back
 
-=head2 JSON parsing & formatting
+=head1 JSON Parsing & Formatting
 
 This module comes with a custom C-based JSON parser and formatter. These
 functions conform strictly to L<RFC-8259|https://tools.ietf.org/html/rfc8259>,
@@ -281,7 +282,7 @@ functions, L<JSON::PP> and L<Cpanel::JSON::XS> are perfectly fine alternatives.
 L<JSON::SIMD> and L<JSON::Tiny> also look like good and maintained candidates.)
 
 
-=head2 URI-Related Functions
+=head1 URI-Related Functions
 
 While URIs are capable of encoding arbitrary binary data, the functions below
 assume you're only dealing with text. This makes them more robust against weird
@@ -343,7 +344,7 @@ then encoded.
 =back
 
 
-=head2 HTTP Date Formatting
+=head1 HTTP Date Formatting
 
 The HTTP date format is utter garbage, but with the right tools it doesn't
 require I<too> much code to work with.
@@ -368,7 +369,7 @@ This will not happen if your local timezone is UTC.
 =back
 
 
-=head2 Gzip Compression
+=head1 Gzip Compression
 
 Gzip compression can be done with a few different libraries. The canonical one
 is I<zlib>, which is old and not well optimized for modern systems. There's
@@ -408,10 +409,10 @@ This function is B<NOT> safe to use from multiple threads!
 This module does not currently implement decompression. If you need that, or
 streaming, or other functionality not provided here, there's
 L<Compress::Raw::Zlib> and L<Compress::Zlib> in the core Perl distribution and
-L<Gzip::Deflate> on CPAN.
+L<Gzip::Faster>, L<Gzip::Zopfli> and L<Gzip::Libdeflate> on CPAN.
 
 
-=head2 Brotli Compression
+=head1 Brotli Compression
 
 Just a small wrapper around C<libbrotlienc.so>'s one-shot compression
 interface.
@@ -428,7 +429,7 @@ Throws an error if C<libbrotlienc.so> could not be found or loaded.
 =back
 
 
-=head2 File Descriptor Passing
+=head1 File Descriptor Passing
 
 UNIX sockets (see L<IO::Socket::UNIX>) have the fancy property of letting you
 send file descriptors over them, allowing you to pass, for example, a socket

FU/Validate.pm

@@ -419,15 +419,15 @@ parameters within Perl code. In fact, the correct answer to "how do I validate
 function parameters?" is "don't, document your assumptions instead".
 
 
-=head2 Validation API
+=head1 Validation API
 
 To validate some input, you first need a schema. A schema can be compiled as
 follows:
 
   my $validator = FU::Validate->compile($schema, $validations);
 
-C<$schema> is the schema that describes the data to be validated (see L</SCHEMA
+C<$schema> is the schema that describes the data to be validated (see L</Schema
-DEFINITION> below) and C<$validations> is an optional hashref containing
+Definition> below) and C<$validations> is an optional hashref containing
 L<custom validations|/Custom validations> that C<$schema> can refer to.  An
 error is thrown if the C<$validations> or C<$schema> are invalid.
 
@@ -443,10 +443,10 @@ An error is thrown if the input does not validate. The error object is a
 C<FU::Validate::err>-blessed hashref containing at least one key:
 I<validation>, which indicates the name of the validation that failed.
 Additional keys with more detailed information may be present, depending on the
-validation. These are documented in L</SCHEMA DEFINITION> below.
+validation. These are documented in L</Schema Definition> below.
 
 
-=head1 SCHEMA DEFINITION
+=head1 Schema Definition
 
 A schema is an arrayref or hashref, where each key is the name of a built-in
 option or of a validation to be performed and the values are the arguments to
@@ -473,7 +473,7 @@ Or to use the same validation multiple times:
 
   [ regex => qr/^a/, regex => qr/z$/ ]
 
-=head2 Built-in options
+=head1 Built-in options
 
 =over
 
@@ -730,7 +730,7 @@ reporting.
 
 =back
 
-=head2 Standard validations
+=head1 Standard validations
 
 Standard validations are provided by the module. It is possible to override,
 re-implement and supplement these with custom validations. Internally, these
@@ -855,7 +855,7 @@ given the year and month.
 =back
 
 
-=head2 Custom validations
+=head1 Custom validations
 
 Custom validations can be passed to C<compile()> as the C<$validations> hashref
 argument.  A custom validation is, in simple terms, either a schema or a
@@ -885,7 +885,7 @@ schema that contains the I<func> built-in option to do the actual validation.
   my $schema = { prefix => 'Hello, ' };
   my $result = FU::Validate->compile($schema, $validations)->validate('Hello, World!');
 
-=head3 Custom validations and built-in options
+=head2 Custom validations and built-in options
 
 Custom validations can also set built-in options, but the semantics differ a
 little depending on the option. First, be aware that many of the built-in
@@ -909,13 +909,13 @@ error:
 
 The I<func> option is validated separately for each custom validation.
 
-Multiple I<keys> and I<elems> validations are merged into a single validation.
+Multiple I<keys>, I<values> and I<elems> validations are merged into a single
-So if you have multiple custom validations that set the I<elems> option, a
+validation.  So if you have multiple custom validations that set the I<elems>
-single combined schema is created that validates all array elements. The same
+option, a single combined schema is created that validates all array elements.
-applies to I<keys>: if the same key is listed in multiple custom validations,
+The same applies to I<keys>: if the same key is listed in multiple custom
-then the key must conform to all schemas. With respect to the I<unknown>
+validations, then the key must conform to all schemas. With respect to the
-option, a key that is mentioned in any of the I<keys> options is considered
+I<unknown> option, a key that is mentioned in any of the I<keys> options is
-"known".
+considered "known".
 
 All other built-in options follow inheritance semantics: These options can be
 set in a custom validation, and they are inherited by the top-level schema.  If
@@ -924,7 +924,7 @@ inherited. The top-level schema can always override options set by custom
 validations.
 
 
-=head3 Global custom validations
+=head2 Global custom validations
 
 Instead of passing a C<$validations> argument every time you call C<compile()>,
 you can also add custom validations to the global list of built-in validations:

FU/XMLWriter.pm

@@ -138,7 +138,7 @@ other XML writing modules on CPAN that I tried, but whether this approach is
 faster than typical templating solutions... I've no idea. Check out
 L<FU::Benchmarks> for some benchmarks.
 
-=head2 Top-level functions
+=head1 Top-level functions
 
 These functions all return a byte string with (UTF-8) encoded XML.
 
@@ -170,7 +170,7 @@ passed to the C<tag_()> call for the top-level C<< <html> >> element.
 
 =back
 
-=head2 Output functions
+=head1 Output functions
 
 =over
 
@@ -252,7 +252,7 @@ provided it defaults to C<undef>.
 
 =back
 
-=head2 Utility function
+=head1 Utility function
 
 =over
 
@@ -263,7 +263,7 @@ and C<"> are replaced with their XML entity.
 
 =back
 
-=head2 Import options
+=head1 Import options
 
 All of the functions mentioned in this document can be imported individually.
 There are also two import groups: