Increase visibility of this project

[pablosichert]

Hey there,

I just ported over a grammar written in Bison/Flex to grmtools – and I was super pleased with how the process went. (Sorry for bombarding you with a lot of small issues, those were just things I noted while implementing.)

Considering how mature this library seems to me, I'm wondering if you deliberatively chose not to advertise it more (-> more maintenance effort)?

I spent a lot of time researching and trying parser generators for Rust, but none of the existing ones ticked all the boxes that I were looking for, until I found this one.

In case you're interested in this project having more visibility (which in my opinion would be useful to a lot of people) I think the Readme could be a bit more elaborate and the repository could be tagged with some topics. Submitting it to relevant aggregators (/r/rust, hackernews, ...) after having a representative landing page would certainly help as well.

Thank you for the huge effort and developing this project in public!

[ltratt]

I'm glad you've found this useful, and thanks for pointing out limitations -- it helps make things better! There's been no particular intent to keep this quiet, nor any intent so far to publicise it. I view the libraries herein as semi-mature, in the sense that I'm still prepared to make breaking API changes (e.g. #125) if it usefully improves things. That said, I've been using these libraries in other projects fairly happily, and I know others have too, which is a decent sign that things are probably ready for a somewhat wider audience. I take your point about the README's brevity, though I hope that the quickstart goes some way to rectifying that. I will beef up the README. We'll probably have a 0.5.0 release at some point this week or so and maybe that will help find these libraries a few more users!

[ptersilie]

I take your point about the README's brevity, though I hope that the quickstart goes some way to rectifying that.

As a quick fix, we could probably just copy over parts of the (or the entire) quickstart guide into the README, which should save some people with particularly short attention spans an extra click.

[ptersilie]

I will have a go at the README then.

[ltratt]

Thanks! As well as doing this, it might be worth checking that the quickstart guide is still 100% accurate and as simple as it could be. It wouldn't surprise me if it could be improved.

[rljacobson]

What I miss in the documentation is some clarity about which features of lex/flex are supported: yytext, yyleng, yymore/yyless, yywrap, REJECT, ECHO, start conditions, character tables, %{ and %} delimiters.... Another thought: ideally, the documentation would be usable to someone who has no experience with lex or yacc, as many in the latest generation of CS majors have never used those tools due to the proliferation of alternative tools and changing priorities in CS education, and I suspect the Rust community has more than its share of such people.

But I'm not complaining. I'm just grateful that you are willing and able to share your code with me! I echo @pablosichert's sentiments. The first time I went searching for a lexer/parser generator solution in Rust, I came to the conclusion that I would have to write my own if I wanted something with the (rather humble) feature set I needed. I didn't find grmtools until later. So far, it is the only library of its kind that I would actually recommend to someone. Thanks!

[pablosichert]

I'd like to suggest some tags that could be put onto the main page of the repository (as an owner, you should be able to see the edit button on the top):

parser generator, lexer, parser, grammar, rust and maybe also lex, yacc / bison, flex

...because I would have really liked back then to find this repo by those search terms.

Edit: Looks like most of those are already in place for the crates, but could also be copied into the GitHub page:

grmtools/cfgrammar/Cargo.toml

Line 11 in 92a15bd

keywords = ["yacc", "grammar"]

grmtools/lrlex/Cargo.toml

Line 10 in 92a15bd

categories = ["parsing"]

grmtools/lrpar/Cargo.toml

Line 12 in 92a15bd

keywords = ["parser", "LR", "yacc", "grammar"]

grmtools/lrtable/Cargo.toml

Line 10 in 92a15bd

categories = ["parsing"]

[ltratt]

What I miss in the documentation is some clarity about which features of lex/flex are supported: yytext, yyleng, yymore/yyless, yywrap, REJECT, ECHO, start conditions, character tables, %{ and %} delimiters.

I take your point on this: I think that I can cover most of this fairly easily.

Another thought: ideally, the documentation would be usable to someone who has no experience with lex or yacc

This is a lot of work :) What I think we can easily do, and building on your first point, is to point people at the exiting yacc docs and then explain the differences more clearly.

I will try and raise a PR on this in the coming days.

[ltratt]

@pablosichert I didn't know about "manage topics" before, and I must admit that I'm not sure how many people find things that way, but it certainly does no harm to add them in -- I've just done so.

[pablosichert]

I assumed that those might be used to create the HTML "keywords" meta tag, so that search engines pick them up.

Just inspected the HTML source and I seem to be wrong.

Maybe it helps anyway, thank you!

[pablosichert]

Another thought: ideally, the documentation would be usable to someone who has no experience with lex or yacc

Might be worth linking to an article of BNF somewhere in the docs, e.g. https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form, and state that it is assumed that the reader is somewhat familiar with it.

[pablosichert]

For my part I'm very happy with the progress that has been made here so far, thank you!

Going to close this one, as there isn't anything actionable left (or should be moved into separate, smaller issues).