Hi,
sorry for the slow reply, but I'm a little busy these days (no, I haven't
forgotten the patches you sent).
On 11.01.2012 14:30, Anurag Priyam wrote:
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:
[advertisement skipped :-P]
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
This last step can be skipped. I'd volunteer for integrating this with cmake
(and all other parts which dont have to be done immediately and are annoying).
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/
JD, do you want to make a webpage?
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.
I might have time from march 1st for two weeks (then I'll be offline for a
while)...
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.
I don't know any.
Other advantages: improved docs could mean more users, which in turn
could mean more contributors, ...
P.S: This email is written in Markdown :)
I noticed due to the footnote syntax. :-)
[1]: http://daringfireball.net/projects/markdown/
[2]: http://keplerproject.github.com/luadoc/architecture.html
[3]: http://asbradbury.org/projects/lua-discount/
I certainly wouldn't miss luadoc syntax. I wouldn't miss luadoc either. I once
managed to break luadoc and then had to figure out from the lua error which
documentation bit was wrong. Urgh.
Besides that, I have to admit that I don't test the luadoc documentation (= I
don't have luadoc installed and thus wouldn't notice if it errors out).
However, I have some questions:
How do you intend to use markdown from lua? Is there a lua-markdown library
which is even less common than luadoc?
Also, why markdown? It is nice for e.g. writing webpages, but for documentation
it misses stuff like @param. So if everyone comes up with his own syntaxes for
function arguments, return values, etc then this might come out messy.
Cheers,
Uli
--
To unsubscribe, send mail to [email protected].
