From owner-freebsd-doc Mon Jun 26 2:10:39 2000 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id AB84037C598; Mon, 26 Jun 2000 02:10:27 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18]) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id IAA88195; Mon, 26 Jun 2000 08:25:29 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id TAA00544; Sun, 25 Jun 2000 19:56:47 GMT (envelope-from nik) Date: Sun, 25 Jun 2000 19:56:47 +0000 From: Nik Clayton To: doc@freebsd.org Cc: dgl@bsdi.com, jim@cdrom.com, papowell@astart.com, wpaul@freebsd.org, ceren@magnesium.net, ryan@ryan.net, murray@bsdi.com Subject: Indexing and glossary Message-ID: <20000625195647.F470@kilt.nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2i Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org There are a couple of things missing from the Handbook as it currently stands. 1. An index This is relatively easy to do. You just go through the document marking up terms to appear in the index as foo, and then let the processing tools do their work. There are some problems with this (documented on the docbook.org website), but they shouldn't be insurmountable. BSDi should be able to provide resources to work on this, in the form of a couple of interns. 2. A glossary Much more interesting. Conceptually, the glossary is not much different from the index. You still have to go through the document marking up terms that should be linked to the glossary (using and respectively). Then you actually have to write the glossary, which consists of the terms and definitions. For maintainability, I suggest we do it like this: 1. Go through the Handbook, marking up with and as necessary. That'll probably be those BSDi interns again. 2. Write a program (probably Perl) to go through the document and construct a skeleton glossary. This glossary will contain all the terms that were referred to in the body of the document, but no definitions. 3. Start a project to collection definitions. The clever bit is what happens two months down the line, when you've added some new documentation which wants some new glossary entries. The Perl script that was written at (2) can re-parse the document to create the new glossary entries. In addition, it should be able to parse the (by now populated) glossary, and insert the new entries straight in to it, ready for someone to add definitions. We then have an effective glossary maintenance tool. It's not FreeBSD specific, so the other documentation efforts should be able to leverage off our work. In fact, we can probably take this a step further -- all the documentation projects are going to need a glossary, and why try and reinvent the wheel each time? Someone (probably us) should start a free glossary project. Each documentation project can submit definitions to it, and can pick and choose definitions from other projects as necessary. Anyone want to pick this idea up and run with it? N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message