[Bioperl-l] "POD errors" not detected by podchecker
Brian Osborne
b_i_osborne@hotmail.com
Thu, 14 Feb 2002 18:42:29 -0500
This is a multi-part message in MIME format.
------=_NextPart_000_003D_01C1B587.5AD97E20
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
Colleagues,
I've noticed a couple of mistakes that podchecker doesn't find. The =
first one looks something like this :
This method returns a L<Bio::SeqIO::Bizou> object
Which makes sense literally but will be translated into something like :
This method returns a the Bio::SeqIO::Bizou manpage object
by pod2html. So you have to write it like :
This method returns a Bio::SeqIO::Bizou object, see =
L<Bio::SeqIO::Bizou> for details.
Or the equivalent. From perlpod :
Translators will mostly add wording around a L<> link, so that L<foo(1)> =
becomes "the foo(1) manpage", for example (see pod2man for details). =
Thus, you shouldn't write things like the L<foo> manpage, if you want =
the translated document to read sensibly.
The second error is adding tags to any tab- or space-indented text. So =
strings like :
Do B<not> use Bio::SeqIO::Bizou
will not be reformatted to bold as desired, they'll appear as is, =
because they're indented. From perlpod :
A verbatim paragraph, distinguished by being indented (that is, it =
starts with space or tab). It should be reproduced exactly,=20
Assuming the text is not part of a command paragraph, meaning a =
paragraph preceded by a "=3D" command.
Thanks once again,
Brian O.
------=_NextPart_000_003D_01C1B587.5AD97E20
Content-Type: text/html;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=3DContent-Type content=3D"text/html; =
charset=3Diso-8859-1">
<META content=3D"MSHTML 6.00.2600.0" name=3DGENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY bgColor=3D#ffffff>
<DIV><FONT face=3DArial size=3D2>Colleagues,</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>I've noticed a couple of mistakes that =
podchecker=20
doesn't find. The first one looks something like this :</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2> This method returns a=20
L<Bio::SeqIO::Bizou> object</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Which makes sense literally but will be =
translated=20
into something like :</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>
<DIV><FONT face=3DArial size=3D2> This method returns a the =
Bio::SeqIO::Bizou=20
manpage object</FONT></DIV></FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>by pod2html. So you have to write it =
like=20
:</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>
<DIV><FONT face=3DArial size=3D2> This method returns a =
Bio::SeqIO::Bizou=20
object, see L<Bio::SeqIO::Bizou> for =
details.</FONT></DIV></FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Or the equivalent. From perlpod =
:</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV>Translators will mostly add wording around a L<> link, so =
that=20
<CODE>L<foo(1)></CODE> becomes "the <I>foo</I>(1) manpage", for =
example=20
(see <B>pod2man</B> for details). Thus, you shouldn't write things like=20
<CODE>the L<foo> manpage</CODE>, if you want the translated =
document to=20
read sensibly.</DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>The second error is adding tags to any =
tab- or=20
space-indented text. So strings like :</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2> Do =
B<not> use Bio::SeqIO::Bizou</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>will not be reformatted to bold as =
desired, they'll=20
appear as is, because they're indented. From perlpod :</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV>A verbatim paragraph, distinguished by being indented (that is, it =
starts=20
with space or tab). It should be reproduced exactly, </DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Assuming the text is not part of a =
command=20
paragraph, meaning a paragraph preceded by a "=3D" command.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Thanks once again,</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2>Brian O.</FONT></DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV>
<DIV><FONT face=3DArial size=3D2></FONT> </DIV></BODY></HTML>
------=_NextPart_000_003D_01C1B587.5AD97E20--