rra / podlators Goto Github PK

I was checking git master (commit 74b5c54), and noticed that it does not generate any output anymore. On an up-to-date Debian sid system, from a git clone:

$ PERL5LIB=blib/lib blib/script/pod2man $(perldoc -l perl) | man -l -

produces nothing. After reverting b98b04e and 5f98aa6 it seems to work again.

This one line uses \h"..." as an escape code:

.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"

https://metacpan.org/dist/podlators/source/lib/Pod/Man.pm#L1593

It was probably supposed to use \h'...' with single quotes.

Hi, Text in S<...> is not supposed to be wrapped but something Pod::Text::Color does seems to defeat this, at least when used via perldoc.

Please see the bug filed against 'perldoc' which now seems to be caused by Pod::Text::Color

briandfoy/pod-perldoc#55

Thanks.

I have reason to use Pod::Text with strings rather than files or filehandles. Please add a "parse_from_string" function that would work something like

my $pod_input     = "=pod\n\n=head1 Head1\n\n...";
my $rendered_pod = parse_from_string($pod_input);

Describe the bug

Output of parse_string_document method is incorrect when I/O layer is specified in binmode.

To Reproduce

Running this script will display the result of converting a string written in Pod format.
Grinning face emoji is the expected behavior to be displayed, but it is garbled.
If the binmode function call is commented out, the display will be as expected.

use v5.38;
use utf8;
use Pod::Text;

my $doc = <<'EOF';
=encoding utf8

=head1 NAME
    😀Grinning face
EOF

binmode STDOUT, ":utf8";

my $p = Pod::Text->new();
$p->parse_string_document($doc);

Expected behavior

binmode is not commented out and the grinning face emoji is correctly displayed.

Additional context

It behaved as expected up to v4.14.
It is reproduced in the latest sources since v5.00.

I wish to test the availability of --guesswork by trying the argument and checking the exit status but unfortunately pod2text works differently than pod2man:

% pod2man --help > /dev/null
% echo $?
0

% pod2text --help > /dev/null
% echo $?
1

So if I add --guesswork=none, I cannot distinguish the availability of it with pod2text.

Seems like I should better use for the test:

echo "=head1 test" | pod2text --guesswork=none > /dev/null

And that's what I'll do. However, homogenizing exit status (either to 0 or 1) would be great.

printf '=pod\n\n=head1 Hello\n\n=cut\n' | pod2man ; echo $?

This is breaking my:

swim --to=man ...

which is breaking a lot of my stuff that depends on that.

I have reason to use Pod::Text with strings rather than files or filehandles. Please add a "parse_from_string" function that would work something like

# Read POD from string and return to a string
my $pod_string = "=pod\n\n\head1 Head 1\n\n...=cut";
my $pod_output = $parser->parse_from_string($pod_string);

While this can be worked around using temporary files, a more direct string version would be helpful.

Hi!

I recently noticed that in Debian unstable, manual pages generated from pod, are no longer left aligned everywhere. They are at the beginning, but for example once there are options the justification gets set to both. I think this is a regression in combination with groff 1.23.0, but I've not tested the current stuff from Debian unstable with an older groff (only verifyied that bookworm behaves as expected), nor know whether this is a problem in groff (some kind of regression) or in podlators (some misuse or wrong assumption for some macro perhaps).

Just wanted to file this to not forget.

The following POD source results in a different rendering between the roff and text outputs:

=head1 test

=over 4

=item A

Line

=over 4

=item 1

=item 2

=back

=item B

Line

=item C

Line

=back

pod2text result:

    A   Line

        1
        2

    B   Line

    C   Line

pod2man result:

       A   Line

           1.
           2.
       B   Line

       C   Line

Shouldn't a visual space be added before B?

I had to add Z<> to force that visual space in the POD source but I believe it should have been there from the start, like in the text output.

Incidentally, I see that the HTML output with pod2html is also wrong, and even does not honour Z<>...
https://www.eyrie.org/~eagle/software/inn/docs/INN-ovsqlite_client.html
(for instance before tag :response_codes and add_article). Looks like I should also open a bug report for Pod::Html.

With current version in Debian stretch/sid (4.07), and current git master, when doing the following, I get that uninitialized warning, and the empty "filename":

$ echo | pod2man -nTest
Use of uninitialized value in concatenation (.) or string at /usr/bin/pod2man line 73.
pod2man: unable to format

Today I began to synchronize the Perl core distribution with the most recent CPAN release of the podlators distribution.

In the most recent Perl production release, certain podlators test files were customized, i.e., had been modified from the corresponding test files in previous CPAN versions. So part of the "sync-with-cpan" process is to decide which customizations should be retained and which should be removed in favor of the most recent CPAN versions. Other things being equal, we'd prefer not to customize any files in the core.

I did a vimdiff comparison on the core and CPAN versions of t/general/basic.t and noticed what I suspect are commented-out version control markings in that file in https://cpan.metacpan.org/authors/id/R/RR/RRA/podlators-5.00.tar.gz.

 45 # Hard-code configuration for Term::Cap to get predictable results.
 46 #<<<
 47 local $ENV{COLUMNS}  = 80;
 48 local $ENV{TERM}     = 'xterm';
 49 local $ENV{TERMPATH} = File::Spec->catfile('t', 'data', 'termcap');
 50 local $ENV{TERMCAP}  = 'xterm:co=#80:do=^J:md=\\E[1m:us=\\E[4m:me=\\E[m';
 51 #>>>
 52 
 53 # Find the source of the test file.
 54 my $input = File::Spec->catfile('t', 'data', 'basic.pod');
 55 
 56 # Map of translators to the file containing the formatted output to compare
 57 # against.
 58 #<<<
 59 my %output = (
 60     'Pod::Man'              => File::Spec->catfile('t', 'data', 'basic.man'),
 61     'Pod::Text'             => File::Spec->catfile('t', 'data', 'basic.txt'),
 62     'Pod::Text::Color'      => File::Spec->catfile('t', 'data', 'basic.clr'),
 63     'Pod::Text::Overstrike' => File::Spec->catfile('t', 'data', 'basic.ovr'),
 64     'Pod::Text::Termcap'    => File::Spec->catfile('t', 'data', 'basic.cap'),
 65 );
 66 #>>>

Assuming that these are indeed just left-over version control marks, could you remove them and issue a new CPAN release (which I would then synch into Perl 5 blead)?

Thank you very much.
Jim Keenan

I originally filed this ticket with Pod-Simple (#148).

I'm working on a system to produce reproducible builds. When a Perl distribution's build process uses Pod::Man to produce man pages, a comment in the output includes the version numbers of both Pod::Simple and Pod::Man. Even if the contents of the file are otherwise the same, the output is different because of this comment.

For example, when building Mojolicious, the generated output for binaries such as morbo includes:

.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================

I'd like to find a way to suppress either the version numbers in this output or this output entirely. This would let me consolidate output where it's otherwise identical. (If there are differences in the generated output outside of comments because of differences in versions of the Pod stack, that's fine.)

I prefer to set an environment variable or make another configuration in my build environment rather than pass an argument directly to any build command.

I'm happy to discuss this further as it's helpful.