Date: Sun, 25 Jun 2000 19:56:47 +0000 From: Nik Clayton <nik@freebsd.org> 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>
next in thread | raw e-mail | index | archive | help
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 <indexterm>foo</indexterm>, 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 <firstterm> and <glossterm> 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 <firstterm> and
<glossterm> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000625195647.F470>