Front page | perl.perl5.porters |
Postings from December 2000
=code language ... =back in POD
Thread Next
From:
Tels
Date:
December 12, 2000 10:20
Subject:
=code language ... =back in POD
Message ID:
200012121820.NAA267880@www08.hway.net
-----BEGIN PGP SIGNED MESSAGE-----
Helo all,
Simon asked in
http://www.perl.com/pub/2000/12/p5pdigest/THISWEEK-20001203.html
>(Hey, maybe someone would like to try writing a program that automatically
>extracts example code from the documentation and makes sure it compiles?)
- From this http://bloodgate.com/pub/Pod_Checker_Code-0.1.0.zip emerged.
(Thanx Brad and Simon!)
While developing this, it turned out that except probably SYNOPSIS any pod
section can contain anything in a verbatim paragraph, not only code.
It is hard to see wether something is really a faulty example, or no
code at all, so a lot of false positives are turned up. (From 1107 files in
my /usr 668 turned up syntax errors in verbatim paragraphs. Most of them
are no code at all.). My idea was to use something like:
=pod
=code perl
Here is some Perl code: (This paragraph is not verbatim, so it is
ignored by the checker)
print "Hello Perl\n";
=back
And here in C:
=code C
printf("Hello World\n");
=back
Shell code is different, too:
=code shell
echo Helo World
=back
=cut
What do you think of this idea? It might take a lot of work to adapt the
existing documentation, but once this is done, the Pod::Checker::Code
could be used to verify that all the examples are still correct (at least
compilable - runable? Never, not enough setup in most examples..but that
needs not be, anyway). There are a lot of typos in examples, even in
Pod/*.pm.
Without something like =code, the checker turns up too many false
positives, and this becomes pretty fast a nightmare.
Alternatively one could think of:
=language Perl
=back
but =code is shorter, so I prefer it.
Here is what my search turned up:
http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-09/msg01320.html
I think the prior thread discussed a change to Perl (...), but I
propose a change to Pod. (I hope I got that right)
Thanx for your time,
Tels
Regards,
Tels
- --
"Why do you go so slowly? Do you think this is some kind of game?"
http://bloodgate.com/thief/ Thief - The Dark Project
http://bloodgate.com/aifilter Rewriting the HTML as we know it.
http://freedomforlinks.de Fight for your right to link.
PGP key available on http://bloodgate.com/tels.asc or via email.
The email address contained in the From/Reply of this email is NOT
to be displayed on webpages, entered into any mailing lists, given
to other people, used to send me electronic greeting cards without
my written, signed permission. No SPAM nor UCE, either! Thank you!
And PLEASE refrain from forwarding me chain letters, massmailings,
or pyramid schemes.
-----BEGIN PGP SIGNATURE-----
Version: 2.6.3i
Charset: latin1
iQEVAwUBOjZsXHcLPEOTuEwVAQEp5Qf+PXDX2rCZkQzE+KLN3qNaew6Aqod0rDCn
F+p7Ufd7fbXn0S26xKK2qe5FuliIRGft7RI8o9c0cGDNdvGYh23ObEwpRus0P/0g
0Q/4X9aw8wAmlsvibSqwaX9yEHWKvmLWVtCTGo76aUXEbzLcwZyejxDORkb+Mu0+
oC7qidefl+ZGbs+7/zE0KjYhqEMMekhf3gllDq2Co+E8OepVj8M171ONlI/6eBlE
vcCyoz2eStzGzxUTXb49U5kDZjbT704XYTHpSVbgufWOBEgVHkK04++ISSPzKI0v
HWjiVKxi6lSFf0QnpelPpmzZP4+1wtSGnJMHg+hcCCaB0iG2PkNoQQ==
=+pct
-----END PGP SIGNATURE-----
Thread Next
-
=code language ... =back in POD
by Tels