Skip site navigation (1)Skip section navigation (2)
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>