Make security warnings in the Safe and Opcode modules more direct.

The current "no warranty" text warning against the use of Safe or
Opcode for "security purposes" is somewhat ambiguous. These modules
are not effective sandboxing mechanisms for evaluating untrusted
perl code and should not be used in that manner.

Safe and Opcode are, at best, hardening measures that could be used
in combination with operating system level sandboxing of the perl
interpreter.

Document the security team's processes and practices

Add a new perlsecpolicy POD file with detailed descriptions
of the security team's vulnerability remediation workflow and
the criteria used to distinguish security issues from other
types of bugs.

This also switches the team's public contact address to
perl-security@perl.org, and updates the security contact
information shown in github's issue interface.

perlapi: Consolidate sv_dec-ish entries

Use macro instead of its expansion

We already have a macro that expands to what this code does; it's
clearer to use it.

perlapi: Consolidate sv_set[inu]v-ish entries

perlapi: Fix poor wording in MUTABLE_PTR

Missing update

I need this to auto-happen :)

Comment for L_R_TZSET now correctly added to config_h.SH

regen podguts after mg_vtable.pl changes

Caused in eb0444cb23a8ec47ef18d5aa33ec88aa5e71b7e8

perlop: put the stringy bitwise ops in precedence table

perldesc: replace circumfix with postfix dereference

...and what an odd one, this!

perldsc: eliminate unnecessary call to keys()

A hash in scalar context now evalutes to its key count, meaning that
(%h1 <=> %h2) is equivalent to, but shorter than, (keys %h1 <=> keys
%h2).  I have dropped calls to keys() in this code to make it clearer.

(This commit may be controversial, as in some places scalar(@arr) is
being used with the suggestion that it provides values.)

perldsc: slightly tweak examples for clarity

perldsc: remove suggestion of more docs coming someday

perldsc: remove the reference to using -w

perldsc: in general, prefer postfix to circumfix dereference

In all (or almost all) cases, postfix dereferencing is simpler to read
and write.  This makes it the better choice for teaching new Perl
programmers.

I have left in reference to circumfix deref, but mostly to acknowledge
that it exists, not to suggest its use.

perlretut: make example code pass under strict

language docs: replace one pointless use of circumfix deref

language docs: prefer postfix deref in numerous places

regen/mg_vtable.pl: Fix perlapidoc display

This wasn't generating the right thing

perlapi: Clarify croak_no_modify()

perlapi: Consolidate some nocontext fcns with their main fcn

mg.c: Use SvTRUE instead of sv_true

The former is preferred.  This was the only sv_true() use in the core.

Clarify branch prediction in SvTRUE

embed.fnc: Mark pad_setsv as core-only

You are supposed to access this functionality through PAD_SETSV

perlapi: Clarify SV Handling

perlapi: Display PERL_VERSION_xy better

Now that we have the tools to show these as a whole list, do so

Document mini_mktime

Document INT16_C, etc

Change docs display for PERL_UNUSED_foo

These should have a semicolon after each in their usage

Document PERL_UNUSED_DECL

Document cPERLscope

README.os2: Fix pod link typo

Remove redundant documentation

Now that we can get automatic links in perlapi, remove the redundant
stripped-down documentation that goes there in favor of the better
documentation in perlcall.

embed.fnc: Add text to comment

Document vload_module

Note that some dump constant flags are not public

One of these is no longer used; the others have synonyms that are
public.  None are used in cpan

embed.fnc: Mark several regex helpers as Core only

These are for internal regex use.

Document several warner() fcns

autodoc: Avoid a loop iteration

Initializing everything with the first elements values allows us to not
look at that element again.  Previously, only somethings were so
initialized.

autodoc: Properly take into account pTHX

Before this patch, it wasn't considering the thread context when
deciding whether two forms of similar functions had the same signature
or not; hence not displaying things when it should have.

mg.h: White-space only

Document whichsig and kin

autodoc: Correctly display some function signatures

The code wasn't properly showing signatures when the function was a
subsidiary one in an entry containing multiple functions, and the
function's signature was specified in embed.fnc

porting/known_pod_issues.dat: Note vsprintf() exists

Document sv_vcatpvfn

Consolidate it with sv_vcatpvfn_flags

autodoc: Fix for win32.

This platform has config.h located in a different place

Thanks to Christian Walde for testing this

embed.fnc: Note pregcomp/pregexec are now documented

This silences a warning from autodoc.pl.

Spotted by James Keenan

Document MUTABLE_PTR, MUTABLE_AV, ...

Document PL_hexdigit

sv.c: Change flags param on two fcns from I32 to U32

This is so the parameter types for sv_2pv_flags and sv_pvn_force_flags
are indistinguishable from similar functions, and can be passed as a
function pointer in a future commit.

It doesn't generally make sense to have a flags variable signed anyway.

Remove regexec_flags from public API

This should only be called as part of a regex engine, and hence is not
an API function.

perlapi: Add some links, wrap C<...>

perlreapi: Wrap a function name in C<>

perlapi: Don't show a return type for __ASSERT_

Change formal parameter name of gv_fetchpv*

This is a flags parameter, not a particular single flag

Note for Devel::PPPort HvNAME_get, HvNAMELEN_get

perlcall: Add some C<>

perlapi: Don't display usage for PL_errgv

perlapi: capitalize 'op'

perlapi: deprecate pack_cat() (a mathoms func)

Change formal parameter name of gv_autload4

The name was completely irrelevant to what it is

Document IN_PERL_(RUN|COMPILE)TIME

perlapi: XS_EXTERNAL is preferred over plain XS

perlapi: XS, XS_EXTERNAL do take a parameter

Improve docs for PERL_foo_MAX/MIN

This puts these in the new sections of perlapi, and makes them display
better.

Fixup docs for LIKELY/UNLIKELY

Fix docs for STMT_START,END,BRACE_GROUPS

perlguts: Rmv unneeded meta apidoc line

These instructions to apidoc are actually not relevant, because the pod
they were trying to control is verbatim, hence not looked at.

perlreguts: Note pregcomp/regexec are documented here

perlguts: Fix grammar

perlguts: Note that UVXf is mentioned

This particular format had been omitted

UTF8fARG,UTF8f are documented in perlguts

perlguts: Note that various SAVEfoo macros are documented

perlguts: Note existence of SAVEI8, I16, BOOL

embed.fnc: 'ref' is not an API function

In fact is only accessible to 3 .c files, all in core.

perlapi: Improve display of isFOO

The character classification macro variants are now presented as a list

Fix bytes_from_utf8_loc() pod

I didn't mean to apply 8505db87404436956f86e54885cacd73840801c0 just
yet, but having done so, there is a change required in a link

perlapi: Consolidate some references to perlguts

perlapi: Turn some references to mg_[gs]et into links

perlapi: Display toFOO better

The character case change macro variants are now displayed all
together

Make bytes_from_utf8_loc() internal

And add it to perlintern, and fix grammar in its pod

regen/warnings.pl: Move some hidden pod

This is a long list of warning categories which doesn't print, but
exists to indicate to downstream tools, such as Devel::PPPort that these
categories exist and are documented.  Move them to the end of the file
so as to make the meat of things flow better.

Document packWARN.?

regen/warnings.pl: Collapse closely related pod

Having separate entries for ckWARN ... ckWARN4 just clutters things
up.  Instead fairly recent extensions to our API generation mechanism
allows these to be variants in a single entry.

perlapi: Consolidate PERL_MAGIC_foo entries

Merge branch 'autodoc update' into blead

This series of commits updates autodoc to generate a more complete and
improved perlapi/perlintern

A major change is the ability to group multiple items in one entry.  We
have many cases where there are slightly different takes on essentially
the same functionality, such as handling magic or not.  All can be
grouped in the same entry, and only their differences noted.  This make
is easier to add new pod when adding a new variant, and it means a more
concise .pod file, with the user not having to jump from entry A that is
listed as similar to entry B, which in turn may even currently say it is
similar to entry C.

The elements in config.h are now included in perlapi, most in new
sections.

I posted an example of these changes in p5p and got zero comments, so am
pushing as it is now.  It is easy to add new sections and to move items
to different ones than they currently are in.

This commit series doesn't actually do any consolidation of entries;
merely enables the ability to do so.  Patches for doing this will come
over time, and hopefully by multiple members of the community.

autodoc: Update comments to reflect new behavior

autodoc.pl: Regularize perlintern handling

autodoc.pl: Add missing semi-colon

Update embed.fnc to document autodoc changes

autodoc: Add section name checking

In the past a section could just spring into existence.  This adds a
check that it is one of the known ones, so typos won't create a screwed
up perlapi.  If a new section is needed, just add it to the list of
valid ones.

autodoc: Display list of sections near top

This would enable someone to more quickly organize their search

Reorganize perlapi

This uses a new organization of sections that I came up with.  I asked
for comments on p5p, but there were none.

Change some =head1 to apidoc_section lines

apidoc_section is slightly favored over head1, as it is known only to
autodoc, and can't be confused with real pod.

autodoc: Don't output empty section

But warn when one encountered.

autodoc: Revise display of apidoc elements

This heavily refactors the code that outputs each api element.
Indentation is cut to 1 space, as anything more doesn't matter much
visually, or at all in html displays, and this gives more geography on a
line.

More importantly, multiple items sharing the same pod within the same
element are displayed prettier.

xxx 1 indent f display

autodoc: Add config.h to what is documented

config.h is now parsed, and the results intermixed into perlapi.

autodoc: Add section footers in this file

Previously, there were no section footers

This commit doesn't actually add any of these; just accepts and handles
any future ones.

autodo: Enclose elements with C<...>

This make all-caps ones look better