[Haskell-cafe] Parsec community and up-to-date documentation

[Konstantine Rybnikov]

On Mon, Mar 25, 2013 at 1:11 AM, Kim-Ee Yeoh <ky3 at atamo.com> wrote:

On Mon, Mar 25, 2013 at 5:19 AM, Konstantine Rybnikov <k-bx at k-bx.com> wrote:
> > as a beginner had a lot of headache starting from outdated documentation
> in
> > various places, lack of more tutorials, confusion between Text.Parsec and
> > Text.ParseCombinator modules and so on.
>
> You're indeed right.
>
> > While I solved most of my problems via googling / reading stackoverflow /
> > reading source code (of outdated version first, btw, the one I got from
> > Daan's homepage :),  I still had a feeling all the time that I'm doing
> > something wrong and that I can't find place where "party is going on".
>
> If you look at the dates of the papers on Wikipedia [1], the party was
> totally hoppin' in the last decade of the previous century. Not so
> much since. Sigh.
>
> > So I wondered, what can I do to create a community around Parsec, to get
> > issue tracking, pull-requests, up-to-date comprehensive documentation and
> > tutorials etc.? Parsec seems like a perfect candidate for something like
> > this.
>
> While the experience is still fresh in your mind, may I suggest that
> you write a note or two on the most confusing things you encountered
> and how you dealt with them? Making your notes public is a way of
> gathering a community around shared experiences.
>

These things are mostly small ones. The main issue is outdated tutorial [3]
page. From what I can remember now:

1.  my confusion definitely began with export-confusion (explaining about
Parsec3 / Parsec2, Text.Parsec and Text.ParseCombinator modules) in various
places (realworldhaskell book [1], parsec's homepage [2])
2.  also, while [2] looks like a homepage for parsec, it's also quite old
and points to old version of sources, for example.
2.  new parsec3 API (and examples with monad-transformer, parsing of Text)
should be added to [3]. The thing I was looking for (and began implementing
just before I noticed my parsec is too old and new one has what I need) was
also from new API, it was anyToken function. So I was able now to write:

skipWhileNot p =
  do { try (lookAhead p) }
  <|> do { anyToken;
           skipWhileNot p }

combinator that would let me skip pieces of information I can't parse.

3.  add type declarations and explanation into [3]
4.  documentation [3] should be split into multiple pages with better
navigation
5.  not a concrete suggestion, but just adding more examples would be great

I'm sure there were plenty concrete suggestions / small improvements that I
already forgot. I absolutely agree that it's better to write notes when
memories are fresh, that's why I think having issue tracking and ability to
do small pull-requests would really help.

Also, the denizens of the haskell IRC at freenode will gladly converse
> with you about parsec. The same goes for subscribers to this list and
> also haskell-beginners.
>
> [1] http://en.wikipedia.org/wiki/Parser_combinator
>
> -- Kim-Ee
>

It's great that haskell community is such welcome for beginners, thanks.

[1] http://book.realworldhaskell.org/read/using-parsec.html
[2] http://legacy.cs.uu.nl/daan/parsec.html
[3] http://legacy.cs.uu.nl/daan/download/parsec/parsec.html
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20130325/dae130e9/attachment.htm>