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

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

Thread Previous | Thread Next
From:
Tels
Date:
December 12, 2000 15:07
Subject:
Re: =code language ... =back in POD
Message ID:
200012122307.SAA333339@www08.hway.net
-----BEGIN PGP SIGNED MESSAGE-----

Moin,

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
documentation...ugh.

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

=head1 EXAMPLES

The follow does something:

        Use Foo;

        print Foo::bluh();

as does the following:

        print Foo::bar();

=cut

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.

Also:

=head1 EXAMPLES

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

=cut

would maybe compile, but never run (or hang, die, etc), so..it 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
it;)

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.
;o)

Thanx for your work!

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.


-----BEGIN PGP SIGNATURE-----
Version: 2.6.3i
Charset: latin1

iQEVAwUBOjawFXcLPEOTuEwVAQGV0Af/RoQsTJyexMpCLsJ0Ji2NqBFbSy4t5lHx
dMDZw7dCKhe2Cb10ZWXzfMWr/RPyRORU+J2iYvcsr2vXEtFQ20OS9YOE9SoU/5Vx
/lu0lubHFrE9bTBayVesFGSZLD0FdvBJnUFT+5ihPMBPsX75YKatSIj+RJpu5YQo
BiAzqrs662w+96D5wc+xw/hqR1lfJp4vLISqQ5OAIcI2Fg0pJJNKKuzMU7tAdCgg
GJ/XmbjObaNq5dcGeJtssQC0PYGUiOgsGCX77NXQDYpCKGFH1DrARKUvcfjWw7+O
dBApV4/8ZQEfsZlQfkaMDsiHwBagQXgIbTwbQbOGBtholsrrWC3vnw==
=BXjL
-----END PGP SIGNATURE-----

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About