Marpa's new web site

[Ron Savage]

Overall, I think Marpa should be presented as mature, modern, and immensely powerful.

The web site should be aimed at beginners, with clear indications as to where experts

can go for more details.

Any examples should be complete, use modern Perl constructs, and have error checking.

I'm not advocating Modern::Perl, just high quality.

Having an example on the front page surprised me at first, but it's grown on me. I

would like to see a few notes - for beginners - pointing out some perhaps unexpected

constructs. See below.

Now, the new web site.

1) The page title and heading

Marpa: The foundation of modern, grammar-based, parsers

o It has 'Marpa' in the title and heading. Think Google-type searching.

o Since 'foundation stone' is almost a tautology, I chose not to use 'stone'.

o 'Foundation' indicates where we think Mapra belongs in any suite of parsing code.

o 'The foundation' is bold and actually quite a strong statement. It suggests superiority in that

other parsers don't measure up as candidates for a foundation.

o 'Modern' indicates - but does not prove - that Marpa is new and different.

o 'Grammar-based' makes clear the claim is not to literally parse everything, but to parse

the vast array of stuff for which a grammar can be devised.

2) The example

o Add a sub-heading, perhaps at h2 level.

Try: Here's a complete parser for simple arithmetic expressions.

o Add:

use strict;

use warnings;

Never encourage beginners to write tacky code. Let other people drop such protections, but don't let

them see us doing it.

o Add Try::Tiny or something. See below.

o EOG => END_OF_GRAMMAR makes it much clearer.

The abbreviation is simply unnecessary. Let others do that. Provide clean, firm, guidelines for

attaining quality.

Likewise for 'Expr', etc.

o || Expr '*' Expr action => do_multiply # Note 1, 2.

Add notes. Here we could say:

Note 1: The '||' indicates alternative ways of constructing an expression.

Note 2: do_multiply is a function Marpa will call automatically when this alternative of the 'Expr'

rule fires.

o my $value_ref = $grammar->parse( \'7 + 42 * 1', 'Calc' ); # Notes 3, 4.

Note 3: Marpa uses a reference here in order to avoid copying what could potentially

be a huge string.

Note 4: A great deal of error checking is built-in to Marpa. Here, if there is no parse,

or if the parse is ambiguous, parse() throws an exception. Hence Try::Tiny.

o printf("$$value_ref\n") => print "$$value_ref\n";

Add ';'. Simplify.

And move this (and => 49) above the subs.

3) The footers Fast, Expressive, Flexible

They are good.

Add something about accepting utf8 in the grammar and in the input stream.

[Flaviu Tamas]

> The web site should be aimed at beginners, with clear indications as
> to where experts can go for more details.

Agreed. So far I've been focusing on design, I haven't added much
content.

> Marpa: The foundation of modern, grammar-based, parsers

Thanks, I've been looking for another tagline. I don't really like the
way that that is phrased though, perhaps something like "Marpa: A
modern parser" would sound better.

>   - Add a sub-heading, perhaps at h2 level.

I'd like to keep as much as possible above the fold on all sorts of
devices, so more explaining than necessary does have a significant
downside.

>   - Add: use strict; use warnings;

I'll do this, although it does push the whitespace tokenization below
the fold on some mobile devices.

>   - EOG => END_OF_GRAMMAR makes it much clearer.

>
> The abbreviation is simply unnecessary. Let others do that. Provide
> clean, firm, guidelines for attaining quality.
>
> Likewise for 'Expr', etc.

Same argument as before: This causes wrapping on some mobile devices,
which would push content below the fold.


>   - || Expr '*' Expr action => do_multiply # Note 1, 2.

>
> Add notes. Here we could say:
>
> Note 1: The '||' indicates alternative ways of constructing an
> expression.

Done.

> Note 2: do_multiply is a function Marpa will call automatically when
> this alternative of the 'Expr' rule fires.

This seems adequately self-explanatory as-is, but I should find
someone who has no idea what this is all about and see if they
understand.

>   - my $value_ref = $grammar->parse( \'7 + 42 * 1', 'Calc' ); #

>   Notes 3, 4.
>
> Note 3: Marpa uses a reference here in order to avoid copying what
> could potentially be a huge string.

This isn't particularly important to usage of the library - Perl is
going to be the bottleneck no matter what. I the interest of staying
concise, I'll omit this

> Note 4: A great deal of error checking is built-in to Marpa. Here,
> if there is no parse, or if the parse is ambiguous, parse() throws
> an exception. Hence Try::Tiny.

I'm not too familiar with Perl, but Marpa's regular error handling I
think is adequate for an example. It prints to the terminal, and
that's what most people want.

>   - printf("$$value_ref\n") => print "$$value_ref\n";
>
> Add ';'. Simplify.

My lack of familiarity with Perl shows :). Fixed.

> And move this (and => 49) above the subs.

Done.

> 3) The footers Fast, Expressive, Flexible
>
> They are good.

Thanks!

> Add something about accepting utf8 in the grammar and in the input
> stream.

I'd like to avoid explaining with words, so I've changed the
multiplication sign to Unicode `×` instead.

[Jeffrey Kegler]

  > Marpa: The foundation of modern, grammar-based, parsers  

 

Thanks, I've been looking for another tagline. I don't really like the 
way that that is phrased though, perhaps something like "Marpa: A 
modern parser" would sound better. 

I'd love to see the suggested title become prophetic, but those who have followed parsing have seen many excessive claims, and are now cynical.  I'll leave it it to flaviu to pick the wording he's most comfortable with -- it's a tough call.  If flaviu goes with what sounds right to his ear, that is probably as good a criterion as any.

 Note 1: The '||' indicates alternative ways of constructing an expression. 

Actually, '||' indicates a change of precedence, while '|' indicates two alternatives at the same level of precedence.  "Precedence" is the same concept described in the perlop man page.  It might be best to simply leave this unexplained in the example, if it is not trying to be a tutorial.  Those who know about these things will see what is happening without explanation.  Those who don't will find out when they follow up by reading the introductory tutorials.

-- jeffrey

[Ron Savage]

>   - Add a sub-heading, perhaps at h2 level.

I'd like to keep as much as possible above the fold on all sorts of
devices, so more explaining than necessary does have a significant
downside.

I confess I did not consider that.

[snip]

 

> Note 3: Marpa uses a reference here in order to avoid copying what
> could potentially be a huge string.

This isn't particularly important to usage of the library - Perl is
going to be the bottleneck no matter what. I the interest of staying
concise, I'll omit this

OK.

 

> Add something about accepting utf8 in the grammar and in the input
> stream.

I'd like to avoid explaining with words, so I've changed the
multiplication sign to Unicode `×` instead.

I did not understand this. I don't see a change http://a.pomf.se/uvsmuf.htm (yet).

 

[Ron Savage]

On Tuesday, 23 December 2014 11:45:04 UTC+11, Jeffrey Kegler wrote:

  > Marpa: The foundation of modern, grammar-based, parsers  

 

Thanks, I've been looking for another tagline. I don't really like the 
way that that is phrased though, perhaps something like "Marpa: A 
modern parser" would sound better. 

I'd love to see the suggested title become prophetic, but those who have followed parsing have seen many excessive claims, and are now cynical.  I'll leave it it to flaviu to pick the wording he's most comfortable with -- it's a tough call.  If flaviu goes with what sounds right to his ear, that is probably as good a criterion as any.

My site, I choose. His site, he chooses.

 

 Note 1: The '||' indicates alternative ways of constructing an expression. 

Actually, '||' indicates a change of precedence, while '|' indicates two alternatives at the same level of precedence.  "Precedence" is the same concept described in the perlop man page.  It might be best to simply leave this unexplained in the example, if it is not trying to be a tutorial.  Those who know about these things will see what is happening without explanation.  Those who don't will find out when they follow up by reading the introductory tutorials.

Yes, true. I could argue that my expression is not actually wrong, but of course a clear explanation would take quite a few words.

[Flaviu Tamas]

> I did not understand this. I don't see a change
> http://a.pomf.se/uvsmuf.htm (yet).

That's a preview I uploaded to a static file host, it won't change.
I've temporary created a GitHub Pages at
<http://flaviut.github.io/marpa-site-temp/>, which will update as I
push.

The change essentially means that `1 + 2 × 3` can be parsed instead of
`1 + 2 * 3`

> My site, I choose. His site, he chooses.

I'm hoping that the site will eventually be accepted by the community,
so consensus is very important to me. As a bit of explanation as to
why I didn't take it as-is: I feel that the phrasing is arrogant,
potentially causing a new user to be put-off.

> --
> You received this message because you are subscribed to the Google Groups
> "marpa parser" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to marpa-parser...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Ron Savage]

I was indirectly referring to Jeffrey's comment a few months ago about my Marpa.html, were he indicated he'd let me choose text precisely because it's on my web site.