perlapi: Add docs for some case-changing macros; clarify others

The case changing macros are now almost all documented.  The exception
is toUPPER_LC, which may change in 5.19

In addition the functions in utf8.c that these macros call now refer to
them instead of having their own documentation.  People should really be
using the macros instead of calling the functions directly.  I'm not
deprecating the functions because I can't foresee the need to change
them, so code that uses them should continue to be ok.
perlclib.pod: Fix too long verbatim lines
perlclib.pod: Update character class macro descriptions

Much has changed since this pod was last updated.
pp.c: Nit in comment
handy.h: Add some macro definitions

These macros fill in all the missing case changing operations.  They
were omitted before because they are identical in their input domains to
other operations.  But by adding them here, that detail no longer need be
known by the callers.  toFOLD_LC is not documented, as is subject to
change
Use new case changing macros

The previous commit added macros to do some case changing.  This
commit uses them in the core, where appropriate.
Add tests for case-change macros API
embed.fnc: Slight clarification in comments
autodoc.pl: Add note for deprecated functions

This causes each deprecated function to have a prominent note to that
effect in its API documentation.
autodoc.pl: Don't list undocumented deprecated fcns in API

autodoc creates a list of all the undocumented functions that are part
of the API.  It omits ones that are experimental and whose API may
change; and now it omits ones that are deprecated (and whose API is
planned to change to be non-existent)
op.c: Don't fold constant fc() in locale

We do compile time folding of calls to ops with constant parameters.
This should be skipped if the op's result depends on locale, and it is
being called from within the scope of 'use locale', as the result is not
known until runtime.  fc() was folding anyway.

There is no test, as this only shows up when run in a locale that it
makes a difference in, and there is no guarantee that such a locale
would occur on any computer, and it is a real pain to go searching
through the computer's available locales for such a one for just this
error.
perl #117865] [PATCH] Eliminate useless variable and sizeof(char)

bufsiz is always just set from bsiz (via a useless multiplication by
sizeof(char), which is by definition 1), so instead of trying to keep
them in sync, just get rid of bufsiz use bsiz directly# Please enter the commit message for your changes. Lines starting
pp.c: Eliminate custom macro and use Copy() instead

I think it's clearer to use Copy.  When I wrote this custom macro, we
didn't have the infrastructure to generate a UTF-8 encoded string at
compile time.
regcomp.c: Clarify comment
perllocale: Update to mention fc(), \F
regcomp.c: Reorder two 'if's so shorter branches are first

This makes it easier to understand what is going on
regcomp.c: White-space only

The previous commit allows us to outdent a largish block, reflowing
things to fit into the extra available width, and saving a few vertical
pixels.
regcomp.c: Remove always-true test

In this code, j is guaranteed to be above 255, so no need to test for
that.
perlapi: Move 'experimental' warning to front of entries

In a long multi-paragraph entry, the fact that the described function is
considered experimental may be lost, as it comes at the end.  This just
moves it to the front.
t/re/fold_grind.t: White space only

Commit 3345a47950127cf99a197eba4dce9c91f7bc9139 created a new
block; but didn't indent it.  This commit does.