On Wed, 2005-03-16 at 15:09 -0800, David Storrs wrote:
> C[$x[0] > $y] # hmmm...parser ok with that?
> C[$x[0] > $] # hmmm...error, but what was intended: $y] or $]]?
In the former case, it's fine. See the grammar I sent last night.
In the latter case, you would get balanced-[] matching, and given how
hard it is for PERL to do the right thing, there, I think it's fair to
fall back on "only perl can parse perl", and just do what the eye
suggests is correct. Remember that POD (and thus Kwid) are not intended
to be Perl-specific, just Perl-friendly. You can always:
C{$x[0] > $]}
If you need unbalanced []s
That said, I'd be ok with something like Z[name|text] and Z{name|...}
for doing external grammars, but it'd still have to live inside one of
the balanced operators correctly.
Please also note that as a side-effect of using extract_bracketed in my
grammar,
C[\]]
works. This introduces escaping which may or may not be good. It was not
a conscious decision, just a side-effect. I PREFER:
C{]}
Which also works.
> C<< $x[0] > $y >> # parser's ok (so's the human)
> C<< $x[0] > $ >> # oh, obviously $y was intended
By the same token:
C[ $x[0] > $y ] # Parser's ok
C[ $x[0] > $ ] # Parser's ok... human might care
> > 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.
Agreed.
> I use Wikis, I run one, I recognize their usefulness. I just don't like
> them.
Fair enough. I don't like them either, for many reasons. I like them in
equal measure. It's a bit like sendmail ;-)
> 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?
Yes, yes, yes. I agree. See AJS Kwid. Please.
> Contrast this to POD (I'm not trying for point-to-point equivalence):
>
> 1) All formatting starts with = in the first column.
Add ONE new item to that list: *
> 2) Every POD command must have a blank line above and below it.
Why do you want TWO ways of determining commands? I can see requiring a
blank line above OR below, just for readability, but not both. I'm a POD
lover. I've used POD since the mid-90s and I'm THRILLED with it.
However, there's that nagging problem with having to type:
\n\n=head1 Foo\n\n=head2 Introduction\n\nTopics:\n\n=over 5\n
\n=item *\n\nFoo vs. Bar\n\n=item *\n\nC<\n>\n
AJS Kwid:
\n= Foo\n\n== Introduction\n\nTopics:\n* Foo vs Bar\n* C[\n]\n
> 3) A list of any type starts with =over N and finishes with =back
Again, you're asking for a second way to determine what point 1 already
told you. If this were code, I might buy that, but it's documentation.
We like documentation. We want to encourage documentation and =over
ain't the way to encourage nothing ;-)
If you prefer a requirement for a leading blank line for readability, I
could see that, and we could talk about it. I do see the value in
"=begin list/=end list", but only in cases like this:
=begin list
* a
* b
=end list
=begin list
* Apples
* Grapes
=end list
Where you wish to make it clear that you are ending the first list.
Which do you find more readable:
=over 5
=item C<--help>
Help is given
=item C<--verbose>
Verbosity is given
=item C<--debug>
Debugging is done
=back
vs:
=begin list
*= C[--help]
Help is given
*= C[--verbose]
Verbosity is given
*= C[--debug]
Debugging is done
=end list
Replace *= with + and =begin list with .list and =end list with .list.
for the original Kwid proposal.
> 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.
There's a 1:1 mapping with all of the above except for the <> vs []/{}
and "=head1 heading" vs "= heading", which are simply syntactic
transformations. If you want "=head1", then you can add a pre-processor,
or we could even have a "=begin head1 / =end head1" for the formatting
bondage crowd.
> PS I'm subscribed to the list so feel free to just reply there; I
> don't need a personal copy as well.
Ok, will do. Some people filter mail such that a reply to them CCed is
seen as "personal" (I do this, for example), some don't. Glad to do what
you're comfortable with.
