"waterlan via RT" <bug-podlators@rt.cpan.org> writes:
Show quoted text> It would be my preference that Pod:Simple was less aggressive about
> latin1.
I'll reassign the bug.
Show quoted text> If you now are going to change the pod2man documentation and start
> demanding an =encoding command for latin1, then in my opinion you are
> breaking backward compatibility.
Well, I understand how you feel, but this is not something under my
control unless I intend to diverge behavior from all other POD processing
modules in Perl. All Pod::Simple clients work the same. All that my
change to the documentation achieves is that the documentation will now be
accurate about how the guessing mechanism works instead of wrong.
Show quoted text> I know -u, but I use it only for non-Latin1 scripts.
pod2man will butcher non-ASCII Latin-1 scripts if you process them without
-u. This has been the case for basically forever, back to when Tom
Christiansen was maintaining it. The output without -u is basically wrong
for nroff (although compatible with very old *roff implementations). It
makes an attempt at producing correct results for groff, but to a first
approximation no one uses groff any more.
My intent in the future is to change pod2man to start producing UTF-8 by
default, since this is what most modern man implementations now expect,
and continuing to butcher people's names in man pages feels rude. I
suspect most (possibly all) modern *roff implementations will cope with
UTF-8 input now, or at least won't produce any worse output than the
current output.
Show quoted text> I want to stay as much as possible compatible with old perl versions.
> One reason is that my program is also compiled on Windows and even DOS.
> There the perl versions are many versions behind, mostly at 5.8 (MSYS,
> DJGPP).
If you want the documentation to build in those environments, I would use
E<>. That's what I did with all of my own POD documentation of that
vintage.
Show quoted text> By using Latin1 encoding for the latin1 scripts, and no =encoding
> command, I'm compatible with old perl versions. For non-Latin1 scripts I
> include the pod2man produced man pages in the source package. Now with
> the new perl 5.18 coming this seems also my best option for Latin-1
> scripts to avoid trouble.
I do this myself, and I think it's a good idea. I understand the desire
to build everything in the distribution from source, but newer versions of
pod2man produce considerably better output, which means that you'll be
doing your users a favor by including versions built with newer versions
of Perl.
Show quoted text> I'm wondering how many other packages, besides perl itself, are using
> POD for documentation. It feels like I'm the only one.
Tons. Most of my bug reports are from people who are using POD for things
other than Perl, and all of my own packages, in whatever programming
language, are documented with POD.
Show quoted text> At least for non-English languages. I don't see many people translate
> there manuals.
That's true. Translating a full manual is a ton of work. I only know of
a few projects that have put in the effort, and it's a never-ending task
to try to keep the non-English manuals up-to-date.
--
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 0gFzD gD,
00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{
rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print
