Enhance documentation

[dmajda]

Right now, the documentation is just a couple of markdown files with simple examples and quick overviews. We should add more documents:

• tutorial/quick-start.md — walk the user through the basic use of PEG.js in Node.js and a browser
• tutorial/walkthrough.md — a more detailed version of Tutorial/Quick Start that shows the capabilities of PEG.js on a gradually improved example grammar/parser
• api/pegjs.md — complete API reference of PEG.js
• api/parser.md — complete API for the generated parsers
• spec/current.md — specification for the grammar used in the current release
• spec/draft.md — a onging specification for the future versions of the grammar
• spec/ast/pegjs-$v.md — a AST that represents the PEG.js grammar for $v

The API references, AST docs and specs should be detailed enough so that anybody would be able to reimplement PEG.js just using these documents.

[jameskeane]

Also, the README should document how to configure whitespace.

[dmajda]

@jameskeane: What do you mean by "configure whitespace"?

[zkhalapyan]

Hi @dmajda,

I am not sure if @jameskeane is referring to the same issue, but from my point of view the following code:

var parser = PEG.buildParser("start = name:([a-v, 0-9, _])+ ");
console.log(parser.parse(" abc "));

Should either fail or avoid white spaces. Instead, a character array is returned with included white spaces as such [' ', 'a', 'b', 'c', ' '].

[dignifiedquire]

I would suggest to use an api generator like jsdoc or jsduck for creating the api. I'd be happy to help setting something up.

[dmajda]

@zkhalapyan The [...] construct works like in regexps and I think it should stay that way.

@dignifiedquire I have yet to see a documentation system for JavaScript that does not suck (simple syntax, well-designed default template, does not force any coding style — especially in OO, allows inclusion of other documents like READMEs, allows using Markdown or other reasonable markup format,...). Basically I'd like to see YARD for JavaScript. (Yes, I know, it's hard to do such a tool. Harder than for Ruby.)

My current idea about the documentation format therefore is bunch of Markdown files & a script to make a simple website from them.

Anyway, I'd like to look at documentation in the 0.9 cycle, after solving more important problems with PEG.js itself in 0.8. It's not my focus now.

[dignifiedquire]

@dmajda Maybe then a github page? Looks nice and is very simple to setup. I can provide a pull request for that if you'd like.
Another idea I had is maybe porting the documentation from the readme to the wiki just for the time now. Also it would be easier for people to add small contributions like spelling corrections.

[zkhalapyan]

I agree with @dignifiedquire - github wiki pages would be very convenient for writing docs.

[futagoza]

Updated the OP to reflect my current direction for this issue.

[StoneCypher]

Realistically, the documentation should be moved to extracted documentation at this point. All of the existing docs can be imported without problems if the right tool is chosen

I will happily get that done in a few weeks if the codebase is put into a position to accept PRs, and if a maintainer is willing to merge and release

[StoneCypher]

Github wikis are easy looking, but they won't be kept up to date any more than any other page is.

Extracted documentation, which is in the codebase, will be, and then having it put up in production is a trivial use of github pages

I can have a proof of concept done in an hour