Add more documentation

[greenfork]

Currently the following documentation is present:

1. README links to the Wikipedia article and the paper on PEG.
2. There is an examples/ directory that shows examples of PEG files and how to compile them.
3. There are source files for JSON and PEG grammars in Pony.

Current problems as I see them:

1. Non-source documentation which is a paper and a Wiki link is descriptive -- it only describes how everything works and what is possible. There's no prescriptive documentation that says clear steps how to achieve the goal of parsing a document.
2. Non-source documentation is only partially usable as the main source of documentation -- it doesn't clearly outline the available grammar and how to compose rules, it contains a lot more of auxiliary information that makes it harder to get the needed parts to complete the task of parsing.
3. Source documentation has no comments -- if you don't understand it, just get better and return later. It is also a question if source is supposed to be documentation. Examples are good at describing the PEG files but doing it the native Pony way has lacking documentation.
4. There are undocumented features which are not part of PEG -- the omission with -, the separator with %.

If I haven't used PEG before, I don't think I would have enough mental capacity to use this library.

Some examples of better documentation for PEG:

• Janet documentation: https://janet-lang.org/docs/peg.html
• Factor documentation: https://docs.factorcode.org/content/article-peg.ebnf.html

It is also the case that both Janet and Factor extend PEG in more ways than the current implementation, so the extensive documentation is more warranted. At the same time it gives a lot more clarity to the user of the library.

What are your thoughts on this?

[SeanTAllen]

@chalcolith any thoughts here?

[chalcolith]

I don't know that we need to provide a complete tutorial on PEG's, but a more fully worked-out example would be nice.