=code language ... =back in POD

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