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
use):
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.
--Dks
PS I'm subscribed to the list so feel free to just reply there; I
don't need a personal copy as well.
--
[EMAIL PROTECTED]
