search

KenKundert / nestedtext

Human readable and writable data interchange format
https://nestedtext.org
MIT License
362 stars 13 forks source link

Language spec changelog? #20

Closed LewisGaul closed 3 years ago

LewisGaul commented 3 years ago

Hi! I came across this project the other day and it seems great, I agree with the motivations and design decisions on the whole. I decided to have a go at implementing a NestedText parser in Zig - zig-nestedtext (as suggested in https://github.com/KenKundert/nestedtext#contributing!).

I'd like to link to a fixed language specification version that I'm implementing (1.3.0?), but the docs only seem to have 'latest' (e.g. no docs at https://nestedtext.org/en/1.3.0/). This should be easy to set up with RTD.

It would also be good to have a changelog (in the docs and the repo root).

KenKundert commented 3 years ago

I have added v1.3 to RTD. I also added v1.2, v1.1, and v1.0, but they are hidden. I have added a pointer to zig-nestedtext to the README. Let me know if you would like me to change it. The changelog is currently in the manual under Installation. Let me think about how I might go about making it more prominent.

Welcome to the NestedText family. I hope your implementation does well for you.

LewisGaul commented 3 years ago

Thanks! Adding my project to the README may have been a bit premature given I haven't even started the implementation yet, but I guess you can always remove it later!

Ah yes I didn't think to look under Installation. As for how to make it more discoverable... It feels like the language spec and the Python implementation are somewhat coupled at the moment, and it would be nice to separate them out a bit more IMO.

I would suggest perhaps grouping the docs as follows:

If the language were to become more mainstream it would probably be good to have these two parts entirely separate, but that doesn't feel necessary right now.

KenKundert commented 3 years ago

Good suggestions. Let me work on this. I'll comment out the pointer to zig-nestedtext for now. Let me know when it is ready.

KenKundert commented 3 years ago

I have reorganized the documentation. You can see it on here. Please let me know what you think.

LewisGaul commented 3 years ago

Nice work, I think it's an improvement.

There are still some places where the lack of separation of the python implementation and the language spec is apparent and seems a little strange, e.g. https://nestedtext.org/en/latest/changelog.html#v1-3-2021-01-02 - no changes in a version bump?

However, what I said before still holds, so not necessarily any need to worry about this for now.

If the language were to become more mainstream it would probably be good to have these two parts entirely separate, but that doesn't feel necessary right now.

Thinking in the context of this issue and my initial suggestion, now when I look at the language changes I deduce the following:

If the above is accurate, then I'd say this issue can be closed as fixed :) I'm intending to get back to my Zig NestedText parser at some point, possibly this weekend, and I'll let you know (via new issues) if I have any further comments.

KenKundert commented 3 years ago

Yes, I see it. It is weird that the version number on the language updates when there is no change, but at this point not too problematic. I like having the language changelog separated from the implementation changelog, it shows the stability of the language. Thank you for your suggestions.