kolmodin
Improve README.md
The README.md file has been converted to Markdown and been slightly extended.
Here are some further changes I'd like to see:
Not sure if it's still portable to Hugs. We claim it is, but I doubt it.
The section about "Using binary". I think this section is not too helpful. It could be more structured of the alternatives and with links to the relevant haddocks.
Deriving binary instance section. This is outdated and missleading. We can now generate instances with GHCs generics. A small example of how to do so, or link to the haddocks, would be better suiting.
Yes, I thought about all of this while updating the README file, but I preferred to proceed step-by-step.
About the portability to Hugs, personally, I stopped using it a long time ago, and I think many of us have done the same. IMHO, I don't think we should care too much about it.
In the "Building binary" section, I think we should promote the use of cabal install rather than runhaskell.
About the "Using binary" section, what do you think it should include? Maybe something in the lines of the example in the Data.Binary module? The subjects that should be covered in the README are:
- What is this for?
- How does it work?
- Where do I find further information?
Perhaps I'm missing something important. The list of contributors may stay there.
Furthermore, I agree that the "Deriving binary instances" is outdated (--fglasgow-exts?). Anyway, since I am not used to derive things, I can't contribute in this point.
We should either test the support of hugs, or just remove the claim that we support it.
Most people should already have binary installed, but given that they found the repo maybe they want to upgrade. cabal install should definitely be favored over runhaskell.
I don't like the current version of the "Using binary" section as it starts by pointing to a module and says write an instance to Binary. We can say it uses an instance Binary (maybe even show the signatures), but that you can use it as well without the instances, or even just with the Builder.
--fglasgow-exts was a flag that enabled a bunch of extensions. It was later replaced with several individual extensions.
Regarding deriving instances, lets just mention that the library supports it, and that it uses the GHC generics. More details are in the haddocks.