search

libre-man / unix-opts

Unix-style command line options parser
MIT License
107 stars 13 forks source link

Documentation improvement #4

Closed vindarel closed 7 years ago

vindarel commented 7 years ago

Hello,

That's a very nice lib, thanks and congrats. The readme wasn't very clear to me, I re-ordered a bit the example (to see the code first, not the shell output), improved the headings, added space, added a bit of code for the example. It still says to go and see the example.lisp.

And it's portable, and where it actually takes the command line arguments from.

Btw, did you look at CLON ? A short notice about it would be helpful (did you see it, why did you not use it ?).

mrkkrp commented 7 years ago

Hi, I appreciate that you like the library that you have spent your time improving the readme.

However, I'd like to avoid purely cosmetic changes like turning names of functions into titles. I have a certain style for readme documents of my Common Lisp code, and these changes would make unix-opts look different from other stuff. I understand that this is really ugly nitpicking, though, but I'd like to keep my projects consistent.

I'd also like to keep the descriptions in the readme in sync with doc strings in the lisp code. Also, I use imperative mood in documentation. Even if you remove the imperative mood and add articles (addition of missing articles is good), you should do it in both readme and doc-strings. And then you would need to adjust all doc strings, so we have a consistent style in the documentation (it is consistent right now).

So right now it's a lot of work for me: going through the changes and see what I want to apply and what I do not want to apply. It'd be a lot better if you could preserve the style we have right now, just add articles in both readme and doc strings, and do minimal editing of the actual text, so it's easier for me to review and merge.

mrkkrp commented 7 years ago

I don't remember using CLON, although I have not used Common Lisp for a couple of years now and I forgot a lot of stuff. I code almost exclusively in Haskell these days.

vindarel commented 7 years ago

I totally understand. I removed the purely cosmetic changes and I copied a few ones to the docstrings (adding space). The most important of all though is still in the first commit, where I added explanations and an example on how to actually parse and consult the args, that was missing and necessary to my understanding.

Cool to see that Haskell works so well for you. I saw you article and posted it on reddit https://www.reddit.com/r/Common_Lisp/comments/73vyph/lisp_and_haskell_and_libraries_productivity/ there's some constructing feedback, some as passionate as you were ;) but most of all it was nice to see that a user opened an issue in SBCL based on your code, to add a compiler warning, which was implemented 10 hours later.

mrkkrp commented 7 years ago

Thanks, applied as 1cc62a6141b92f3b34c00065ad154cc0cf8bf816.