Sorry for the delay, I moved into a new apartment for work and fell a
bit behind on email. Catching up...
On 01/24/2013 06:42:52 PM, Richard Hartmann wrote:
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].
Oh please no.
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.
I'm assuming this is some Asciidoc variant?
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.
We already have docbook. And html documentation on the web. And there
are PDFs. And audio and video recordings.
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.
Feel free to go set up yet another wiki. wiki.kernel.org has a bunch.
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've mirrored Documentation to a couple places. If my kernel.org
account ever starts working again (and letting me rsync instead of a
useless git stub) I'd update http://kernel.org/doc/Documentation, which
has HTML navigation things generated from the 00-INDEX files. That
script is attached.
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.
What Documentation really needs is to be re-organized, starting with
moving all the architecture-specific stuff into an "arch" subdirectory
(just like the kernel source does), and then probably similar cleanups
along those lines (making the layout of Documentation mirror the layout
of the source it's documenting).
Switching to a markup format doesn't actually help.
--
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.
Helping weed out stale documentation is great. Moving everything to a
new markup format is really orthogonal to that.
[1] https://en.wikipedia.org/wiki/Markdown
So not the same as http://www.methods.co.nz/asciidoc/ then.
Rob
#!/usr/bin/python
# Convert kernel Documentation/.../00-INDEX to index.html
import os,sys
for dir in os.walk("Documentation"):
if not "00-INDEX" in dir[2]: continue
# Read input
lines = open("%s/00-INDEX" % dir[0]).read()
lines = lines.split("00-INDEX",1)
if len(lines)==1:
print "FAILED %s" % dir[0]
continue
# Open output, write header and <pre> section (if any)
out = open("%s/index.html" % dir[0], "w")
out.write("<html>\n<title>%s</title>\n<body>\n<ul>\n" % dir[0])
if lines[0]: out.write("<pre>%s</pre>\n" % lines[0])
lines = lines[1].split("\n")
lines[0] = "00-INDEX"
close = 0
for idx in range(len(lines)):
if not lines[idx]: continue
if not lines[idx][0].isspace():
if close: out.write('</li>\n')
out.write('<li><a href="%s">%s</a>' % (lines[idx].strip(), lines[idx].strip()))
close = 1
else: out.write(" %s" % lines[idx].strip())
out.write("</li>\n</ul>\n</body>\n</html>\n")
