Add none value for Pod::Text encoding option

Pod::Text now supports setting the encoding option to "none" to disable
output encoding. This only makes sense when calling output_string() to
direct the formatted output to a scalar. It is intended for special
cases where the formatted output is held in memory for further
processing and will encoded for output at a later step. Thanks, djerius.

Fixes #38

Author: rra

Changes

@@ -1,6 +1,13 @@
                       Revision history for podlators
 
-v6.0.3 - Not Released
+v6.1.0 - Not Released
+
+- Pod::Text now supports setting the encoding option to "none" to disable
+  output encoding. This only makes sense when calling output_string() to
+  direct the formatted output to a scalar. It is intended for special
+  cases where the formatted output is held in memory for further
+  processing and will encoded for output at a later step. Thanks to
+  djerius for the suggestion. (GitHub #38)
 
 - Fix Pod::Text quoting heuristics for C<> when the contents contains
   newlines. Thanks to van-de-bugger for the report. (GitHub #39)

lib/Pod/Text.pm

@@ -313,14 +313,15 @@ sub output {
                 $$self{ENCODING} = $encoding;
             }
         }
-        if ($encoding) {
+        if ($encoding && $encoding ne 'none') {
             my $check = sub {
                 my ($char) = @_;
                 my $display = '"\x{' . hex($char) . '}"';
                 my $error = "$display does not map to $$self{ENCODING}";
                 $self->whine ($self->line_count(), $error);
                 return Encode::encode ($$self{ENCODING}, chr($char));
             };
+            print("ENCODING IN $encoding\n");
             print { $$self{output_fh} } encode ($encoding, $text, $check);
         } else {
             print { $$self{output_fh} } $text;
@@ -921,25 +922,32 @@ with the POD rendered and the code left intact.
 
 =item encoding
 
-[5.00] Specifies the encoding of the output.  The value must be an encoding
-recognized by the L<Encode> module (see L<Encode::Supported>).  If the output
-contains characters that cannot be represented in this encoding, that is an
-error that will be reported as configured by the C<errors> option.  If error
-handling is other than C<die>, the unrepresentable character will be replaced
-with the Encode substitution character (normally C<?>).
+[6.1.0] Specifies the encoding of the output. The value must be an encoding
+recognized by the L<Encode> module (see L<Encode::Supported>) or the special
+value C<none>. If the output contains characters that cannot be represented in
+this encoding, that is an error that will be reported as configured by the
+C<errors> option. If error handling is other than C<die>, the unrepresentable
+character will be replaced with the Encode substitution character (normally
+C<?>).
 
 If the output file handle has a PerlIO encoding layer set, this parameter will
-be ignored and no encoding will be done by Pod::Man.  It will instead rely on
+be ignored and no encoding will be done by Pod::Man. It will instead rely on
 the encoding layer to make whatever output encoding transformations are
 desired.
 
+As a special case, if the encoding is set to C<none>, no encoding will be done
+and characters will be output in Perl's internal representation. This option
+only makes sense in combination with output_string(). It is intended for
+special cases when the results of formatting are kept in memory and will be
+encoded for output at some later step.
+
 WARNING: The input encoding of the POD source is independent from the output
 encoding, and setting this option does not affect the interpretation of the
-POD input.  Unless your POD source is US-ASCII, its encoding should be
-declared with the C<=encoding> command in the source, as near to the top of
-the file as possible.  If this is not done, Pod::Simple will will attempt to
-guess the encoding and may be successful if it's Latin-1 or UTF-8, but it will
-produce warnings.  See L<perlpod(1)> for more information.
+POD input. Unless your POD source is US-ASCII, its encoding should be declared
+with the C<=encoding> command in the source, as near to the top of the file as
+possible. If this is not done, Pod::Simple will will attempt to guess the
+encoding and may be successful if it's Latin-1 or UTF-8, but it will produce
+warnings. See L<perlpod(1)> for more information.
 
 =item errors
 
@@ -1078,7 +1086,7 @@ to the scalar variable pointed to by REF, rather than C<STDOUT>.  For example:
     $man->parse_file('/some/input/file');
 
 Be aware that the output in that variable will already be encoded (see
-L</Encoding>).
+L</Encoding>) unless the C<encoding> option to Pod::Text is set to C<none>.
 
 =item parse_file(PATH)
 
@@ -1211,6 +1219,8 @@ encoding changes.  The L<Encode> module is now used for all output encoding
 rather than PerlIO layers, which fixes earlier problems with output to
 scalars.
 
+Pod::Text 6.1.0 added support for the C<none> option to C<encoding>.
+
 =head1 CAVEATS
 
 Line wrapping is done only at ASCII spaces and tabs, rather than using a
@@ -1226,8 +1236,8 @@ Pod::Simple.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019, 2022 Russ
-Allbery <[email protected]>
+Copyright 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019, 2022,
+2024-2025 Russ Allbery <[email protected]>
 
 This program is free software; you may redistribute it and/or modify it
 under the same terms as Perl itself.

t/text/no-encoding.t

@@ -0,0 +1,36 @@
+#!/usr/bin/perl
+#
+# Test the "none" encoding option of Pod::Text.
+#
+# This only makes sense in combination with output_string to produce output
+# that's still in Perl's internal encoding.
+#
+# Copyright 2025 Russ Allbery <[email protected]>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+#
+# SPDX-License-Identifier: GPL-1.0-or-later OR Artistic-1.0-Perl
+
+use 5.012;
+use utf8;
+use warnings;
+
+use Encode qw(encode);
+use Test::More tests => 4;
+
+BEGIN {
+    use_ok('Pod::Text');
+}
+
+# Set up Pod::Text to output to a string.
+my $parser = Pod::Text->new(encoding => 'none');
+isa_ok($parser, 'Pod::Text');
+my $output;
+$parser->output_string(\$output);
+
+# Parse a document containing UTF-8.
+my $input = "=encoding utf-8\n\nrésumé\n";
+my $result = eval { $parser->parse_string_document($input) };
+ok($result, 'Parsed document');
+is($output, "    résumé\n\n", 'Produced correct output');