Date: Sat, 11 Aug 2007 15:55:25 -0700
From: Randy Dunlap <randy.dunlap@oracle.com>
To: Sam Ravnborg <sam@ravnborg.org>
Cc: Stefan Richter <stefanr@s5r6.in-berlin.de>,
       Andi Kleen <andi@firstfloor.org>,
       =?ISO-8859-1?Q?Hans-J=FCrgen?= Koch <hjk@linutronix.de>,
       Stephen Hemminger <shemminger@linux-foundation.org>,
       linux-kernel@vger.kernel.org
Subject: Re: Documentation files in html format?
Message-Id: <20070811155525.3ff6a8f3.randy.dunlap@oracle.com>
In-Reply-To: <20070810201235.GA4133@uranus.ravnborg.org>
References: <20070809113122.3aa508e4@oldman.hamilton.local>
	<200708091508.20626.hjk@linutronix.de>
	<p73hcn8g25m.fsf@bingen.suse.de>
	<20070810074047.GC31307@uranus.ravnborg.org>
	<46BC6DA9.1050903@s5r6.in-berlin.de>
	<20070810201235.GA4133@uranus.ravnborg.org>
Organization: Oracle Linux Eng.
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2185
Lines: 65

On Fri, 10 Aug 2007 22:12:35 +0200 Sam Ravnborg wrote:

> > 
> > What primary requirements does in-tree Linux kernel documentation have
> > to fulfill in general?
> 
> Skipping the obvious ones such as correct, up-to-date etc.
> o Readable as-is
> o Grepable
> o buildable as structured documents or almost like a single book
> o Easy to replicate structure
> o Maintainable in any decent text-editor (emacs, vim, whatever)
> 
> > I've got a hunch that the most suitable format for Linux kernel
> > documentation, after careful consideration of what we want from it and
> > how we author and maintain it, will turn out to be...
> > 
> > ...plaintext.
> Asciidoc is quite close to plaintext and it looks to me that the
> formatting possibilities are quite good.
> 
> I spend an hour experimenting a little with
> Documentation/kbuild/makefiles.txt.

Hi Sam,

Sorry for the late question (I've been away :).

Was your makefiles.txt conversion done totally by hand?
Could it be automated?

or maybe there is not enough volume to even worry about that.

Yes, evaluating asciidoc has been on my radar (todo list) for
some time now.


> Diff below shows quite a lot of changes but for the most
> this is removal of the indent tab.
> Most likely I could have tweaked asciidoc to accept this
> but wanted to use default config.
> 
> The resulting html page can be seen here:
> http://www.ravnborg.org/kbuild/makefiles.html
> 
> Produced using:
> asciidoc -a toc -a numbered makefiles.txt
> 
> I would say that the asciidoc formatted plaintext text
> are readable despite the simple markup.
> And someone coming later will have no problems to follow
> the original markup.
> 
> Btw. is is not a full conversion, I stopped after a few chapters.
> asciidoc should be able to produce the index automatically
> but I had no luck but then I did not try hard either.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/