From owner-freebsd-advocacy Wed Jun 30 21:38:41 1999 Delivered-To: freebsd-advocacy@freebsd.org Received: from obie.softweyr.com (unknown [204.68.178.33]) by hub.freebsd.org (Postfix) with ESMTP id F1DC315518 for ; Wed, 30 Jun 1999 21:38:26 -0700 (PDT) (envelope-from wes@softweyr.com) Received: from softweyr.com (homer.softweyr.com [204.68.178.39]) by obie.softweyr.com (8.8.8/8.8.8) with ESMTP id WAA01161; Wed, 30 Jun 1999 22:38:17 -0600 (MDT) (envelope-from wes@softweyr.com) Message-ID: <377AF0B8.9076225F@softweyr.com> Date: Wed, 30 Jun 1999 22:38:16 -0600 From: Wes Peters Organization: Softweyr LLC X-Mailer: Mozilla 4.5 [en] (X11; U; FreeBSD 3.1-RELEASE i386) X-Accept-Language: en MIME-Version: 1.0 To: Terry Lambert Cc: Jesus Monroy , seth@freebie.dp.ny.frb.org, advocacy@FreeBSD.ORG Subject: Re: [Re: [Re: [Re: [Re: [Re: My FreeBSD Experience ]]]]] References: <199906302330.QAA10390@usr09.primenet.com> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-freebsd-advocacy@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG Terry Lambert wrote: > > Jesus Monroy wrote: > > > Currently, errors in the documentation are constantly > > creeping in because fixes (or changes) are made > > to the base utility set, or the parts they > > use (ie. command-line flags). Errors in the documenation are constantly creeping in because that is just how the world works. You can be a part of the problem, or a part of the solution. To be a part of the solution, feel free to submit re-written man pages, new man pages, or just diffs. > > Where is the root of the problem? I don't know. > > Can this be solved? I don't know. > > Well this problem continue to manifest itself > > at irregular times and without warning? > > Yes, it's a real daemon. > > It's possible to resolve. The engineering technique is called > "literate programming". There was apparently a nice talk about > it at Usenix, with someone building a kernel using the technique > to allow them to publish an example. JavaDoc does a somewhat credible job along these lines as well. Wind River systems, the makers of the VxWorks embedded OS, also uses an internal documentation format so the man pages are maintained in the source files. None of these are as complete as Web, the literate programmin tool, which embeds the code within the documentation, but all are at least steps in the right direction. Encouraging programmers to update the documentation as they update the code is a step in the right direction, too. -- "Where am I, and what am I doing in this handbasket?" Wes Peters Softweyr LLC http://softweyr.com/ wes@softweyr.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-advocacy" in the body of the message