develooper Front page | perl.perl5.porters | Postings from December 2000

Re: =code language ... =back in POD

Thread Previous | Thread Next
December 12, 2000 15:07
Re: =code language ... =back in POD
Message ID:


wow, nice discussion ;) *wears flame-proof undies*

On 12-Dec-00 Jarkko Hietaniemi tried to scribble about:
> On Tue, Dec 12, 2000 at 01:02:09PM -0600, Jarkko Hietaniemi wrote:
>> Nice idea in principle but the real world is kinda complex.

Aehm *cough* is it? I never visit it these days ;)

>> > =code perl
>> Which Perl?  I have several different versions installed.  With which
>> options?  Environment variables? 

Most code-snippets don't assume a specific Perl version (this is for small
examples, remember). And even if they do, use the version the module
requires initself? Oh, user must have installed. But when you install
something that requries 5.6.0, you better have 5.6.0 around to check the

No, sorry, I got it wrong. This is meant for the module/documentation
author to check the doc before letting it in the wild, not the user. 

So, do we need more than the "perl -c" I do right now? Or should the author
take care of this?

>> > =code C
>> >         printf("Hello World\n");
>> If I have a hello.c with those contents it will most certainly not
>> compile... and if compiled, with which compiler?  Compiler options?
>> Etc.

The other things are mostly to flag non-perl-code so that the
perl-syntax-checker can ignore it ;) (I blame C for the non-compilable
example, anyway.) The "shell" "c" are only examples. The perl is the more
important thing here. Wether you flag it as C, or dont flag it, does not
make a difference, since there is only a Perl Syntax checker yet.

>> > =code shell
>> Which shell?  sh? csh? bash? tcsh? zsh? ksh?  Etc.
> Also, no matter what the language, yet another problem quickly becomes
> apparent if you really start doing something like the suggestion (I
> one actually did, ahem...)  The suggested model assumes each of the
> code snippets are both self-contained and correct.  The first
> assumption will trip us if a later snippet requires something from
> previous snippets to compile.  

This is already catered for that all snippeds in one section (=head[0-9]
blah) are compiled together. So


The follow does something:

        Use Foo;

        print Foo::bluh();

as does the following:

        print Foo::bar();


would give to perl -c

        Use Foo;
        print Foo::bluh();
        print Foo::bar();

If it still fails, you could adjust the documentations slightly. For
complicated, more core-near stuff (like demonstrating strict etc), you
could neglet to flag the snippet as code.



        use Foo;
        Foo::blah($errormode,$line,$myoptions);  # sample to call blah


would maybe compile, but never run (or hang, die, etc), doesnt
produce perfect, runnable examples. ;)

> The second assumption: how does one
> demonstrate *illegal* code if the requirement is that each code
> snippet should compile okay? (whatever that means for shells,
> I don't know)

You simple do not flag it as =code, but write it as normal verbatim
paragraph. This is also true for incomplete examples, that don't compile.

Especially BECAUSE this case (to demonstrate illegal code) I thought about
the =code setup. Otherwise the checker would stumble over so many things...

The entire =code is just that we can flag any valid Perl code
snippet/example for the checker to check (as to avoid outdated examples,
examples with typos etc). If you have code that is not self-contained etc,
simple don't flag it. Shell code? Dont flag it! C code? Dont..aeh you get

But don't cry if you insert typos into non-flagged code ;)

Do I make sense at this late time? I guess the POD father has a veto, too.

Thanx for your work!




- --
 "Why do you go so slowly? Do you think this is some kind of game?"     Thief - The Dark Project   Rewriting the HTML as we know it.       Fight for your right to link. 
 PGP key available on or via email.

Version: 2.6.3i
Charset: latin1


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About