[doc] PerlIO::encoding, error in documentation, FB_PERLQQ et.al.

[wolfdiem]

The documentation of PerlIO::encoding in https://perldoc.perl.org/perl,
v5.34.0 contains an error in the Synopsis section.

The value FB_PERLQQ is not allowed for fallback, as it contains the
'LEAVE_SRC' bit. In addition the 'STOP_AT_PARTIAL' bit is missing,
which is mandatory for use in $PerlIO::encoding::fallback.
Unfortunately this is not contained in any FB_xxx CHECK value, thus
the bits have to be given explicitly.

Thus a valid combination of mask bits should be used, e.g.
'STOP_AT_PARTIAL | PERLQQ'. This also requires to either export
':fallback_all' in "use Encode", or to write the mask bits with
'Encode::...'.

If I understand github #18496 correctly, then the changes there
will enforce a correction of this error internally. But that would
be for v5.34 only, and still the documentation should give correct
values and should be applicable to older versions also.

BTW, if the documentation is changed anyhow, "UTF-8" in the text
further down should be changed to "UTF8", as Perl's internal strings
are loose, not strict. This would make the documentation at bit more
consistent.

As an additional thought: It could be useful to export (or at least
allow the export) of 'ONLY_PRAGMA_WARNINGS' from Encode. This bit is
anyhow included in the default setting of $PerlIO::encoding::fallback,
but it is not available for setting of the variable by the user.

[jkeenan]

The documentation of PerlIO::encoding in https://perldoc.perl.org/perl,
v5.34.0 contains an error in the Synopsis section.

Is there someone familiar with PerlIO::Encoding who could review this critique of the documentation?

[Grinnz]

@Leont is probably the only person familiar with this module and associated flags

[Leont]

The value FB_PERLQQ is not allowed for fallback, as it contains the
'LEAVE_SRC' bit. In addition the 'STOP_AT_PARTIAL' bit is missing,
which is mandatory for use in $PerlIO::encoding::fallback.
Unfortunately this is not contained in any FB_xxx CHECK value, thus
the bits have to be given explicitly.

You're correct, this is wrong.

BTW, if the documentation is changed anyhow, "UTF-8" in the text
further down should be changed to "UTF8", as Perl's internal strings
are loose, not strict. This would make the documentation at bit more
consistent.

IMHO it shouldn't mention either. As far as Perl code is concerned, internal encoding shouldn't matter.

[jkeenan]

The value FB_PERLQQ is not allowed for fallback, as it contains the
'LEAVE_SRC' bit. In addition the 'STOP_AT_PARTIAL' bit is missing,
which is mandatory for use in $PerlIO::encoding::fallback.
Unfortunately this is not contained in any FB_xxx CHECK value, thus
the bits have to be given explicitly.

You're correct, this is wrong.

BTW, if the documentation is changed anyhow, "UTF-8" in the text
further down should be changed to "UTF8", as Perl's internal strings
are loose, not strict. This would make the documentation at bit more
consistent.

IMHO it shouldn't mention either. As far as Perl code is concerned, internal encoding shouldn't matter.

Could someone propose a documentation patch that would address the issues raised in this ticket?

[khwilliamson]

@pali, do you have an idea about this?

[pali]

@khwilliamson Yes, documentation needs improvements.

[khwilliamson]

@pali, I was hoping since you are more familiar with the operation of this than I am, that you could propose some wording; which I could polish if necessary, me being a native English speaker

[Leont]

I have since fixed the code so that it automatically filters out the LEAVE_SRC, but for backwards compatibility it's still a good idea to change this in the documentation.