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
David Storrs
March 16, 2005 15:09
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
On Wed, Mar 16, 2005 at 01:30:04PM -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. 

No, I am relating simplicity and consistency to usability.  If it
costs two extra keystrokes, I'm cool with that.

> and noting could be simpler than:
> 	C[$x > $y] is about as B[easy] as it gets in [Perl]

C[$x[0] > $y]  #  hmmm...parser ok with that?
C[$x[0] >  $]  #  hmmm...error, but what was intended: $y] or $]]?

C<< $x[0] > $y >>  # parser's ok (so's the human)
C<< $x[0] > $  >>  # oh, obviously $y was intended

> However, saving a couple of keystrokes and cleaning up the above text is
> inconsequential compared to 

"...the power of the Force."  Sorry, had to say it.

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

Here's the real crux of your argument, and the real crux of my problem
with this approach.  I don't like Wiki syntax; to me, it seems
arbitrary and non-unified.  I use Wikis, I run one, I recognize their
usefulness.  I just don't like them.  

Here are some of the formatting rules for TWiki (the Wiki version I

1) Elements of a bulleted list must match /^ {3}\* /
2) Elements of a numbered list must match /^ {3}1 /
3) Headings must match /^----*\++/.  Number of +s determines level
4) *bold* 
5) /italic/
6) =fixed font=
7) <verbatim> put text to be rendered as-is here </verbatim>

What is the organizing priciple?  What similarities do they have?
Quick, what level heading is this: +++++ ?  And this is just the
beginning...I didn't even get into the weird cases like ==bold fixed
font== and __bold italic__, which have no perceptible relation to
their component pieces (I would have expected */bold italics/*).  Yes,
it's powerful and it can do useful things, but as soon as I stray from
the most basic stuff I find myself going back to the docs to look up
how it's done.

Contrast this to POD (I'm not trying for point-to-point equivalence):

1) All formatting starts with = in the first column.  
2) Every POD command must have a blank line above and below it.
3) A list of any type starts with =over N and finishes with =back
4) List items are denoted with =item X where X is either * (bullets), 
	an int (numbered), or word/phrase.  Use only one type per list.
5) Headings are denoted by =head1, =head2, etc
6) Formatting effects are done with X<text> where X is one of:
        B (bold), C (code), I (italics).  You may also use 
	X<< text >> or X<<< text >>> if you have < or > in your text.
7) Text that is indented will be rendered as-is in fixed width font.

Aside from links, that's pretty much the entire perlpodtut boiled down
into 7 bullets; a little experimentation to get the hang of it and it
all holds together nicely, easy to remember.  

I freely admit that the link syntax in POD is difficult to manage and
not as powerful as it could be.  


PS  I'm subscribed to the list so feel free to just reply there; I
don't need a personal copy as well.


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