Hi all, this may sound crazy, but this idea has been floating around in my head for years. I even had a branch somewhere where I started working on this, but I can't seem to find it any more. I am proposing to migrate Documentation/ from plain text to MarkDown[1] and ikiwiki[2]. Let me split my rationale into two parts: 1) Why MarkDown: MarkDown is relatively unobtrusive and will still look neat and compact as plain text. Yet, it easily compiles into various output formats and it imposes a common style on all files. Also, it's a lot easier to read as source than DocBook. 2) Why ikiwiki: ikiwiki can generate static pages from MarkDown (and other) source files which would make it easy to put a well-formatted, hyperlinked, and hierarchical version of the documentation onto any website. It's important to note that ikiwiki does not require generated HTML or anything to be checked into git. Not a single non-documentation file would need to be maintained within Documentation/ . Similar to MarkDown, ikiwiki would impose a certain structure, for example more or less requiring input.mdwn with a short explanation of what input/ contains and links to the various files in it. There's precedent for inline ikiwiki documentation, the most popular example being git-annex[3]. The whole website is maintained within ikiwiki in a subdirectory named doc/ . While this particular instance allows anonymous commits to doc/, allows editing for anyone with an OpenID account and has a comment function, none of this would need to be activated in this case, or at least not the mainline kernel. Obviously, if there's any significant interest in this, commits from a potential world-editable wiki-style Documentation/ could be cherry-picked back into mainline if mechanisms like Signed-off-by etc are heeded. I would appreciate honest (and, if need be, blunt) feedback on this. If there is any interest in this endeavor I can see myself putting in long-term effort and optionally co-maintaining Documentation/, especially the parts concerning MarkDown and ikiwiki integration. -- Richard PS: An effort like this may also help weed out stale documentation. For example Documentation/kernel-docs.txt refers to #kernelnewbies on irc.openprojects.net; OPN has been renamed to freenode years ago and the channel moved to OFTC years ago, as well. [1] https://en.wikipedia.org/wiki/Markdown [2] http://ikiwiki.info/ [3] http://git-annex.branchable.com/ -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
