A Book for Nom

[tfpk]

Hi,

I'm a newbie to Nom (and I'm probably only an intermediate Rust programmer), and I have personally found that this project lacks documentation for newcomers. I thought that it would be valuable to have a "book" for Nom, in the vein of the Rust Book or the many other excellent books that projects around the Rust ecosystem have.

Based on my limited experience, I've written about a quarter of a short book. This is a book I think would have helped me, had I had access to it a few weeks ago.

I'm posting it here for a few reasons:

1. Whether it's useful enough to continue working on, and whether the Nom project would be interested in accepting it.
2. If I've put in any significant (or even minor) mistakes that could be corrected.
3. If the order and plan for content is reasonable.

I'm happy to move this to an issue if that's the right place to discuss, though I suppose a useful issue to reference is #1506 .

I'd welcome any and all feedback!

Thanks :)

[tfpk]

Thank you for the feedback! I'll fix those nits up.

Did you have any broader feedback on the structure I'm planning in SUMMARY.md? And if I kept working on this is it something you'd be interested in integrating?

I'm new enough to the project I don't know if there are things I should be explaining!

[Xiretza]

The overall structure looks great for a comprehensive tutorial, which is something that nom kind of lacks right now (there is some tutorial-style documentation in docs/, but it's not as coherent as an mdbook).

if I kept working on this is it something you'd be interested in integrating?

Well, you'll have to ask @Geal about that, I'm not a maintainer, but personally I'd gladly accept it ;)

I'm new enough to the project I don't know if there are things I should be explaining!

I hang out in #geal_nom:gitter.im, and while it's hard to find a most common issue, error handling is definitely something a lot of users struggle with. There are just a lot of levels to the current IResult, and it takes a while to dig through them to understand it.

[tfpk]

@Xiretza + @Geal -- I've updated this PR with the next section of the book.

Particularly curious if there's anything major that needs changing in the order or in topics covered.

I'm also blocked on the last three chapters:

• Re Streaming -- I couldn't find an easy to grok example of how they are used. Is there an up-to-date one? My thinking is that the best "simple" example would be reading in from stdin; and doing something like bracket-matching; but I don't know if that plays to nom's strengths.
• Re bytes + bits -- again, I don't know the area well enough to have a good example; and I don't know what's worth covering.
• Re Exercises, is this worth having? I come from a teaching background, so having exercises is the norm for me, but I'm not sure if it's the done thing in Rust projects. I could also go through and add one or two per chapter?

One other thought -- some of the other documentation in docs/ would fit well in the book (I haven't written an errors chapter, because the errors document that exists is great!) Is it worth moving some/all of the documentation into the book? I've borrowed particularly heavily from the list of parsers/combinators -- I'm not sure if duplicating them was the best idea, so maybe references to them either by link; or as an appendix might be helpful?

Keen to hear your thoughts/feedback!