From owner-freebsd-questions Mon Mar 12 17:29:32 2001 Delivered-To: freebsd-questions@freebsd.org Received: from guru.mired.org (okc-65-26-235-186.mmcable.com [65.26.235.186]) by hub.freebsd.org (Postfix) with SMTP id 7783A37B718 for ; Mon, 12 Mar 2001 17:29:26 -0800 (PST) (envelope-from mwm@mired.org) Received: (qmail 53530 invoked by uid 100); 13 Mar 2001 01:29:25 -0000 From: Mike Meyer MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <15021.30709.531367.27409@guru.mired.org> Date: Mon, 12 Mar 2001 19:29:25 -0600 To: David Johnson Cc: Doug Young , freebsd-questions@FreeBSD.ORG Subject: Re: documentation issues generally In-Reply-To: <3AAD733E.CA29C3F9@acuson.com> References: <046701c0ab3c$c4a66300$847e03cb@apana.org.au> <15021.23142.119090.401764@guru.mired.org> <00f501c0ab57$0cf59760$0200a8c0@apana.org.au> <15021.29109.287302.175380@guru.mired.org> <3AAD733E.CA29C3F9@acuson.com> X-Mailer: VM 6.89 under 21.1 (patch 14) "Cuyahoga Valley" XEmacs Lucid X-face: "5Mnwy%?j>IIV\)A=):rjWL~NB2aH[}Yq8Z=u~vJ`"(,&SiLvbbz2W`;h9L,Yg`+vb1>RG% *h+%X^n0EZd>TM8_IB;a8F?(Fb"lw'IgCoyM.[Lg#r\ Sender: owner-freebsd-questions@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG David Johnson types: > Mike Meyer wrote: > > In other words, you never even bothered trying. I've never read the > > docs list. I don't want to read about writing docs, I want to provide > > better docs to help people use FreeBSD, and cut down on the questions > > on -questions. I believe I've succeeded in doing that. > If that list is anything at all like the kde-doc list, I don't blame > Doug at all. DocBook is great and pretty easy to learn. But the people > who are really *into* DocBook have lost all sense of priority. They're > more into DocBook than into Documentation. That's actually the normal path for things to take. Those who are good at that kind of thing are drawn to it. As I pointed out later in that message, *it doesn't matter*. Those people are good at tweaking the tools, and making them turn out lots of different formats. Let them, and just ignore the list. It takes exactly two things to contribute usefully to the FreeBSD documentation project: 1) Track the docs sources. If you're properly tracking BSD otherwise, that means cutting the DOCSUPFILE line from /etc/defaults/make.conf, copying it to /etc/make.conf and uncommenting it. The next time you do "make update", you'll get the latest doc sources. 2) Install the docproj metaport. That's a huge port, and installs some stuff you may never need - but it installs everything you do need. When you want to change or add something, find the document where it's going to go in /usr/doc, and save a copy of the source. Edit the original, cribbing from the document you're editing as needed. The stuff it just like HTML, except it has a different set of tags and entities; anyone who can write a reasonable HTML page can do all this. When you're done, save it and type "make lint" in that directory. Now comes the hard part if you write HTML like most people - you have to find and fix the errors it lists. I've found that if you don't want to fix the errors, the committer generally will, but will ask you to fix them in the future. As Kris points out, if you don't write it marked up, they'll even mark it up for you - though it'll take longer, and they might grumble. But taking an existing text and reusing the markup is so easy, I don't see much point in not marking it up. http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message