On Wed, Jan 11, 2012 at 4:01 PM, Anurag Priyam <[email protected]> wrote: > gears.color docs: replace literal '<' and '>' with respective HTML entities
I remember, I had sent a similar patch earlier too. It was to fix markup for awful.menu's documentation. Such patches are indicative of a larger problem, in my opinion. Awesome's API documentation is full of broken or bad or missing markup and English and content. I feel my patches are merely addressing the symptoms. Using [Markdown][1] as a documentation format can alleviate a lot of the problems: 1. HTML in both: code and diff, looks super ugly. Unrendered documentation (in the source files) is virtually unreadable; see `lib/awful/tooltip.lua.in` for example. Hell, even the final output is hardly legible. 2. The set of HTML tags that luadoc supports right out of the box is limited. 3. Since HTML is relatively more painful to write, the developers don't have an incentive to write good documentation. I don't mind contributing _proper_ documentation. But fixing broken markup is hardly gratifying. Sometimes a better tool can make a lot of difference. Markdown, on the other hand, is way simpler, prettier, and readable. For complex use cases you can embed HTML within. I am not sure how exactly to proceed, but here is the general idea: 1. Implement a [Doclet][2] to convert Markdown in the documentation to HTML * uncertain of the implementation apart from what has already been done in `luadoc/src/luadoc/doclet/html.lua` * probably leverage [lua-discount][3] to make the job easy * not sure if such a module should go to luadoc, or remain a part of awesome's source tree * figure out how to integrate into awesome's build system 2. See if luadoc supports custom templates * choose, or write (this will be painful; I suck at design) one for Awesome, to be used at https://awesome.naquadah.org/doc/api/ 3. We can think of other goodies once this much has been done and merged Notes: I definitely can't work on this before 21st of Jan. Probably not till Jan end actually. But, if anyone finds this particularly interesting, and have time, please, by all means, go ahead with it. I will join hands as soon as I can find time. Of course, this doesn't do much to improve the English. And I am not sure if we can actually do something about it unless more people with native English proficiency step up to improve the docs. Other advantages: improved docs could mean more users, which in turn could mean more contributors, ... P.S: This email is written in Markdown :) [1]: http://daringfireball.net/projects/markdown/ [2]: http://keplerproject.github.com/luadoc/architecture.html [3]: http://asbradbury.org/projects/lua-discount/ -- Anurag Priyam -- To unsubscribe, send mail to [email protected].
