Announcing md-readme

You can find quite a few Emacs libraries on github these days. I only have one very small project there, wpmail, which I haven’t written about yet because I want to finish the Markdown support first… anyway: something I find really neat on github is the automatic display of the README file in the repository’s root directory, if it exists. Only, as we all know, writing READMEs is tedious and we’d rather spend our time programming. But wait: in the Emacs world, we’re actually writing a README for each project: the library headers. Their content and structure are rather clearly defined, and it’s expected for all Emacs libraries. So I had the idea of generating a nice, Markdown-formatted README.md for github from these headers.

I just pushed the first version of md-readme that does just that. The README that you see on the github page is auto-generated from md-readme.el, with lists, code-block and everything.

The conversion to Markdown is of course pretty simple, but even so it’s pretty cool to see how little code I had to write. Emacs provides everything out of the box. (with-temp-file "README.md" (do-it)) is just elegant.

Now, seeing that we have code that generates a nice README from our Lisp file, it’s natural to have it run automatically so we always have an up-to-date README. Here I was struggling for a while. I had lots of ideas, but none seemed to work out. My current solution is setting a per-directory local variable for each of your ELisp projects that triggers the conversion via an after-save-hook. Code is in the README. The problem with adding the after-save-hook to all modes is that it’s evaluated all the time, for each save. Kinda annoying, even if it’s just a single condition.

Does anyone have a better idea? Do it outside Emacs in a git pre-commit hook?

But even with the current solution it works, and that’s the important part. Please try it, and enjoy your new READMEs.

About these ads

Tags: , , , , ,

8 Responses to “Announcing md-readme”

  1. Edward O'Connor Says:

    Hey, that’s cool. I might start using this for some projects.

    Also, I’ve added your blog’s posts tagged Emacs to Planet Emacsen. Let me know if that’s ok!

  2. Jonas Bernoulli Says:

    Good idea, I might also use it.

    However when I looked at the README.md generated for md-readme itself I noticed that you did not follow the header conventions. Please read http://www.gnu.org/software/emacs/elisp/html_node/Library-Headers.html.

    I would like to suggest that mdr-generate should (optionally, but by default) check if the library follows the header conventions before generating the README.md. Quite a lot of authors do not follow them. By adding this check to your library – provided that it becomes popular on github – will cause at least the libraries on github to follow the conventions.

    You could use lm-verify defined in lisp-mnt.el for this purpose.

    Another thing you could do would be generating the list of dependencies automatically. My library elx.el (which hasn’t gotten much love lately) could be used for that.

  3. thomas11 Says:

    Hi, thanks for the feedback!

    @Edward: thanks for adding me to the planet, that’s awesome. I only have two Emacs posts so far, though… but I have a couple more in the pipeline.

    @Jonas
    Your suggestions about checking the header and generating the list of dependencies are great. I’ll look into implementing them.

    I didn’t know about lm-verify, that’s pretty useful. I ran it on md-readme and corrected two errors: added some keywords known to finder and added the EOF marker. However, if you’re looking at README.md, there’s one big difference to the header that I do during the conversion; I replace the GPL disclaimer by one sentence that links to the GPL web page. I felt that should be enough when the file is displayed on the internet anyway. Now that others may start using md-readme, I can make it optional, of course.

    BTW, about lm-verify: when I want to set the optional argument non-fsf-ok to t, how could I do that interactively? For now I wrote “(lm-verify nil nil nil t)” into my buffer and evaluated it, which is very cumbersome. I could write my own helper function, I guess.

  4. tarsius Says:

    Reminder to self: Never type a long message in the input field of a browser :-( Lesson learned this time?

  5. tarsius Says:

    > Your suggestions about checking the header and generating the list of dependencies are great. I’ll look into implementing them.

    Libraries http://github.com/tarsius/elx/blob/master/elx.el and http://www.emacswiki.org/emacs/lib-requires.el can be used to extract the list of dependencies. See the header of the former for why it is better. :-)

    Sorry, for mentioning this again if I misunderstood you and by “implementing” you meant “make use of these libraries in my library”.

    > I didn’t know about lm-verify, that’s pretty useful. I ran it on md-readme and corrected two errors: added some keywords known to finder and added the EOF marker.

    I did not even spot that. In the times of dvcs this hopefully will become obsolete, but until many libraries are still “hosted” on the emacswiki this convention actually is very important. But in some way it’s also the most ridiculus of them all, and people should start moving their libraries to github, launchpad, bitbucket etc.

    And you do not mention that your library is *not* part of Emacs.

    > However, if you’re looking at README.md, there’s one big difference to the header that I do during the conversion; I replace the GPL disclaimer by one sentence that links to the GPL web page. I felt that should be enough when the file is displayed on the internet anyway. Now that others may start using md-readme, I can make it optional, of course.

    Yes a noticed and I liked it. Again elx.el can be used to detect even more licenses.

    When I tried it while using elide-header it did not seam to work correctly. Did not check that any furtur and don’t know if elx.el handles it correctly, though I expect it would. If not that shouldn’t be to hard to fix.

    > BTW, about lm-verify: when I want to set the optional argument non-fsf-ok to t, how could I do that interactively?

    You can’t:

    > (interactive (list nil nil t))

    Oh dear!

    > For now I wrote “(lm-verify nil nil nil t)” into my buffer and evaluated it, which is very cumbersome. I could write my own helper function, I guess.

    (defvar my-verify ()
    (interactive)
    (lm-verify nil nil nil t))

    About the information you put in the README:

    I think it should be possible not to output the (all or some) header variables (Author, URL…) to the README. Especially when used on github Author and URL seam to be redundant.

    Speaking of URL. I would suggest using Homepage AND Repository instead (though I don’t do that myself). If one doesn’t create a homepage in addition to the webinterface to the repo on github the to values would be identical, so I guess Repository could be ommitted in that case. URL seams a bit ambitious: is it the homepage or repository url. But I am nitpicking again :-)

  6. tarsius Says:

    Just noticed that elx.el has quite some dependencies (including cl) so if you would like to use it and this is a problem I would consider doing something about it.

  7. tarsius Says:

    err Repository would of course NOT be equal to Homepage:

    Homepage: http://github.com/thomas11/md-readme
    Repository: git://github.com/thomas11/md-readme.git

  8. thomas11 Says:

    Hi Jonas, thanks again for your hints and suggestions. I’ll go on a trip today, so it’ll be a while until I can have a look at them, but I certainly will.

    BTW I realized that I hadn’t put my email on the About page. It’s now there, so feel free to write if you prefer that.

Comments are closed.


Follow

Get every new post delivered to your Inbox.

%d bloggers like this: