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
Brian Ingerson
March 16, 2005 11:24
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
On 16/03/05 13:30 -0500, Aaron Sherman wrote:
> 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]
> vs:
> 	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]

vs Kwid:

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

Did you really read `perlkwid.kwid`? There is simply no mention
of `[=...]` as a markup option, which makes me wonder where you
got it from?

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

Well said!

Cheers, Brian 

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