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

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

Thread Previous | Thread Next
December 14, 2000 04:48
Re: =code language ... =back in POD
Message ID:


On 13-Dec-00 Nicholas Clark tried to scribble about:
> On Wed, Dec 13, 2000 at 03:15:43PM +0000, Simon Cozens wrote:
>> On Wed, Dec 13, 2000 at 11:10:27AM +0000, Nicholas Clark wrote:
>> > But I don't think it's safe to use =back as the end:
>> Why use anything? The code section ends at the beginning of the next
>> non-verbatim paragraph.
> Could be a lot of typing if you've got several verbatim paragraphs
> interspersed with bits of code with the same options.

What about my proposed:

=begin code perl

Some examples:

        Use Foo qw/blah/;
        print blah();

end more:

        print blah(8);


Would be the easiest way to extend pod without breaking it.

Also, options/requires/uses should be, if neccessary, given in the example.
I vote for (currently) no options after code. Anything your example needs
should be in there, or otherwise the checker will find it ok, but User
might not make sense from it.

Here is what could go into perlpod.pod (will make patch if we agree on it):

        Some format names that formatters currently are known
        to accept include "roff", "man", "latex", "tex",
        "text", and "html" and "code". (Some formatters will treat
        some of these as synonyms.)

        "code" stands for source code, that can be checked by a syntax
        checker. After "code" follows the optional language the source is
        in, the default is "Perl". Other formatters than the checkers could
        treat "=begin code" and "=end" as it was not there. Or they could
        syntax color the code, or do something else with it (like making the
        code standing on a different background).

        Each "code" section can contain only verbatim and ordinary text
        paragraphs. Only the verbatim paragraphs are checked, and
        the entire section between "=begin" and "=end" will be
        compiled/checked in one go. The section should be selfcontained,
        e.g. anything it needs to successfully compile should be included.

        Some checkers (e.g. the L<Pod::Checker::Code|Perl syntax checker>)
        will assume certain switches, options and compiler versions. You
        can override them either in the source (via use, require etc) or by
        giving them as options to the checker when checking your own
        modules documentation.

        Here are some examples:

        =begin code

        This is some silly example:

                use strict;
                my $x = 5;

        Andhere come more code:

                my $y = 3 + $x;

        Note that the second snipped does not repeat the use strict nor the
        my $x.


        The checker would give the following to the compiler:

                use strict;
                my $x = 5;
                my $y = 3 + $x;        

I will add options to the checker so that you can specify the modules,
libraries and version for the check. I think that the checker also could
remove " ... " from the examples, since that seems fairly common.

I will also supply a doc patch for bleed that fixes the most worst
errors RealSoonNow[tm].

Thanx for your time,





- --
 "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