[P] Internacinalización en POD ?

[Ernesto Hernandez-Novich]

On Wed, 12 Sep 2001, José Luis Rey wrote:
> Estoy haciendo dos módulos en Perl y tengo el siguiente problema con la
> documentación en POD: como la documentación es en español, las secciones
> NAME, SYNOPSIS, etc. deberían llamarse NOMBRE, SINOPSIS, etc. sin
> embargo mi versión de perl (5.005_03), _exige_ que el POD contenga al
> menos NAME, SYNOPSIS y DESCRIPTION o se niega a generar la documentación
> cuando el usuario la instala.  Otro problema que veo en mi futuro es que
> el man queda en 8859-1 (el que yo uso) y creo que tampoco hay forma de
> que alguien que no use ese charset lo vea :-(
> 
> Será que existe alguna alternativa de internacionalizar el POD ?, tal
> vez en Perl 5.6 ?

No hay ninguna sección en POD que se llame "NAME", "SYNOPSIS", etc. Esos
son nombres de secciones asociadas a man, pero no a pod :-)

En POD uno simplemente usa

=head1 lo-que-quieras-poner-aqui

ocurre que para hacer POD similar a man, se acostumbra poner NAME,
SYNOPSIS, etc. en las diferentes secciones. Entonces, es perfectamente
válido escribir

#!/usr/bin/perl

=head1 NOMBRE

Nombre del módulo

=head1 SINOPSIS

  $x = mimodulo->blah('foo','bar');
  $y = mimodulo->bleh('baz','qux');

=head1 DESCRIPCION

  Lo que sea que hace el módulo

=cut

42;

Y al salvarlo en un archivo modulo.pl o modulo.pm, es perfectamente
válido y funcional escribir

perldoc modulo.pl

y se obtiene lo que uno espera. (Probado en 5.6.0 y 5.6.1)

Ahora, una cosa diferentes es pasar del POD a man, pues implica convertir
de POD a nroff. Tomé el modulo.pl antes construido y le ejecuté
directamente

pod2man modulo.pl > modulo.1
man ./modulo.1

y apareció la página de manual tranquilamente. Si protestó por el acento
de la 'ó' y _no_ la mostró en 5.6.0 en Slackware 7.1 sin locales, pero al
utilizar 5.6.1 en Debian Woody con locales salió perfectamente. Fuí osado
al colocar la 'ó' literalmente, puesto que en POD hay sentencias de
escape similares a las á de HTML con el propósito de definir
entidades internacionales.

Así que yo diría que hay alguna restricción en la conversión pod2man de
tu proceso de instalación; hay una opción --lax de pod2man para que no
exija secciones especiales, quizás eso es lo que estás buscando. En
cuanto al juego de caracteres, yo diría que depende del i18n del sistema
y como afecta a man.
-- 
Ernesto Hernández-Novich - Running Linux 2.2.19 i686 - Unix: Live free or die!
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS d+(-) s+: a C+++$ UBLAVHIOSC++++$ P++++$ L+++$ E- W+ N++ ?o ?K w--- O- M- V
PS+ PE Y+ PGP>++ t+ 5 X+ R* tv+ b++ DI+++$ D++ G>++ e++ h+ r+ y++
-----END GEEK CODE BLOCK-----

------------------------------------------------------------------------
Enviar e-mail a <majordomo at pm.org> colocando en el cuerpo:
"UNSUBSCRIBE caracas-pm-list" para desuscribirse.
"INFO caracas-pm-list" para conocer las reglas de etiqueta.
------------------------------------------------------------------------