Front page | perl.perl5.porters |
Postings from August 2001
Re: perlpod rewrite, draft 1
Thread Previous
|
Thread Next
From:
Philip Newton
Date:
August 12, 2001 09:27
Subject:
Re: perlpod rewrite, draft 1
Message ID:
perl.perl5.porters-41824@nntp.perl.org
On 10 Aug 01, at 4:28, Sean M. Burke wrote:
> =item *
>
> And perhaps most importantly, keep the items consistent: either use
> "=item *" for all of them, to produce bullets; or use "=item 1.",
> "=item 2.", etc., to produce numbered lists; or use "=item foo",
> "=item bar", etc. -- namely, things that look nothing like bullets or
> numbers.
And don't use something mixed like "=item 1. Foo", "=item 2. Bar", as
some translaters mangle such things horribly and beyond recognition. Or
something else I've seen: "Arguments to this subroutine: / =item 1 /
name / =item 2 / value / =item 3, 4, 5, ... / optional parameters",
which I've seen rendered as "* . name / * . value / * , 4, 5, ...
optional parameters" -- that is, the "1" "2" "3" disappeared into the
void.
> If you start with bullets or numbers, stick with them, as many
> formatters use the first "=item" type to decide how to format the
> list.
Yes!
> A more readable, and perhaps more "plain" way is to use an alternate
> set of delimiters that doesn't require a ">" to be escaped. As of
> perl5.5.660, doubled angle brackets ("<<" and ">>") may be used I<if
> and only if there is whitespace immediately following the opening
> delimiter and immediately preceding the closing delimiter!> For
> example, the following will do the trick:
>
> C<< $a <=> $b >>
>
> In fact, you can use as many repeated angle-brackets as you like so
> long as you have the same number of them in the opening and closing
> delimiters, and make sure that whitespace immediately follows the last
> '<' of the opening delimiter, and immediately precedes the first '>'
> of the closing delimiter. So the following will also work:
>
> C<<< $a <=> $b >>>
> C<<<< $a <=> $b >>>>
Perhaps mention why this was added? It's not so that people can play
around with "obfuscated Pod", but for things such as
C<<< open FOO, ">>filename.txt" or die "Can't open: $!" >>>
or
C<<< $status = $? >> 8 >>>
or the like.
Cheers,
Philip
--
Philip Newton <Philip.Newton@gmx.net>
Thread Previous
|
Thread Next