From owner-freebsd-hackers Sat Nov 7 13:42:59 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id NAA13223 for freebsd-hackers-outgoing; Sat, 7 Nov 1998 13:42:59 -0800 (PST) (envelope-from owner-freebsd-hackers@FreeBSD.ORG) Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id NAA13180; Sat, 7 Nov 1998 13:42:53 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.8.8/8.8.8) id VAA11901; Sat, 7 Nov 1998 21:39:33 GMT (envelope-from nik) Message-ID: <19981107213933.43220@nothing-going-on.org> Date: Sat, 7 Nov 1998 21:39:33 +0000 From: Nik Clayton To: "Jordan K. Hubbard" , Chad David , hackers@FreeBSD.ORG, doc@FreeBSD.ORG Subject: Documentation (was Re: freebsd-hackers-digest V4 #299) Reply-To: doc@FreeBSD.ORG References: <3644A494.C40D3C8F@acns.ab.ca> <12568.910468750@time.cdrom.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.89.1i In-Reply-To: <12568.910468750@time.cdrom.com>; from Jordan K. Hubbard on Sat, Nov 07, 1998 at 11:59:10AM -0800 Organization: Nik at home, where there's nothing going on Sender: owner-freebsd-hackers@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG [ x-posted to hackers, where it started, and doc, where it should continue. Reply-to set to doc] On Sat, Nov 07, 1998 at 11:59:10AM -0800, Jordan K. Hubbard wrote: > Yes, well, technical docs of this nature are definitely a job which > requires that someone actively keep it up to date or it becomes > rapidly worthless. I know nothing about it, but what are people's thoughts on using some sort of 'literate' programming system (is that the right term?) in FreeBSD. After a day spent playing with TeX, the Web2c system is obviously the nearest example. Or maybe there's a C equivalent to JavaDoc? As I say, I know nothing about these things, I'm just throwing it out as a discussion point. > Nik Clayton has just taken over as the new > Documentation Project Manager (yea Nik!) and perhaps this is something > he'd be willing to give you some bootstrapping assistance with. Certainly. Ask and ye shall receive and all that. The -doc mailing list is the general place to ask these sorts of questions (as Jordan has indicated). Take a look at for my half-completed draft of a primer for contributors to the FreeBSD documentation effort. I'm trying to get a critical mass of documents together so that the learning curve is sufficiently shallow for most people that they can just get stuck in documenting, rather than spending time fighting with the toolchain. > His > early docs on coming to grips with SGML are already quite good and I > imagine that the Docbook DTD could be used (or enhanced) to do > programmer's API documentation just as well as the Handbook. Absolutely. DocBook is designed for exactly that sort of technical documentation. In fact, Someone on -doc recently made the suggestion that we shift the manual pages from *roff format to DocBook. That's possibly a touch too controversial at the moment, but might not be beyond the bounds of possiblity for the medium term future. In fact, it might be worth doing that within the Doc. Project, treating them as another translation (similar to the Japanese translation) of the manual pages? See the (short) thread in -doc starting with a message from Christine McKinty, , subject is "FreeBSD manpages in SGML?", messageID is <199811061532.QAA26783@odin.France.Sun.COM>. > > depressing to joyfully congratulate myself for getting my first LKM > > device driver to work, only to read five minutes later in Jordan's 3.0 > > announcement that LKM was dead. > > Sorry about that.. . Is it at least some consolation that what it's > getting replaced with is a whole lot better? :) It's also still useful. There are a lot of 2.2.x systems out there for which it will be useful. And it can be added to a growing corpus of sample documentation to point people to and say "Steal ideas from this." :-) > > Point me at what needs to be documented. I am only one person, but > > /usr/src/sys :-) And pick a part of that, particularly if you're already familiar with it. Better still, work out who's responsible for it (say, syscons, maintained by Soren) and work with them. Ideally, you don't want them making large changes without first working with you to make sure it stays documented. This is one of my concerns with the Handbook at the moment. For example, the section on how FreeBSD boots is getting more and more out of date as -current progresses, and I don't know if anyone's stuck their hand up to document it. N -- C.R.F. Consulting -- we're run to make me richer. . . To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message