develooper Front page | perl.perl6.language | Postings from March 2005

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

Thread Previous | Thread Next
Aaron Sherman
March 16, 2005 10:30
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
On Wed, 2005-03-16 at 12:25, David Storrs wrote:

> I quite like <> as the bracketing characters.  They are
> visually distinctive, they connect well with their adjacent C/X/L/etc
> without visually merging into it (compare L<foo> with L[foo]), and in
> the circumstance that you want to bracket an unbalanced bracket, you
> just double (triple, whatever) up and add some space:
>      C<<  $x > $y  >>
> Looks pretty clear to me.

You are confusing aesthetics with usability. Yes, the above looks clear,
but then I have to type "C<< " and " >>" just to tell the POD parser
that there might be unbalanced < or > characters in my string. You're
failing to apply Larry's rules of Perl 6. Huffman and the "easy things
easy, while hard things are possible" principles demand that a common
case not require copious extra gunk, and noting could be simpler than:

	C[$x > $y] is about as B[easy] as it gets in [Perl]


	C<< $x > $y >> is about as B<easy> as it gets in L[Perl|perl]

without going full Wikish:

	[=$x > $y] is about as *easy* as it gets in [Perl]

However, saving a couple of keystrokes and cleaning up the above text is
inconsequential compared to the massive savings in terms of taking
advantage of the legions of people who are learning Wiki syntax these
days. Making POD *more* Wiki-like without sacrificing useful features of
POD is invaluable in terms of tech writers and other
non-Perl-programmers writing useful docs in POD!

Aaron Sherman <>
Senior Systems Engineer and Toolsmith
"It's the sound of a satellite saying, 'get me down!'" -Shriekback

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