From owner-freebsd-doc  Sun Jul  2 10:13:56 2000
Delivered-To: freebsd-doc@freebsd.org
Received: from astart2.astart.com (astart2.astart.com [206.71.174.194])
	by hub.freebsd.org (Postfix) with ESMTP
	id C567A37BAA6; Sun,  2 Jul 2000 10:13:51 -0700 (PDT)
	(envelope-from papowell@astart.com)
Received: from h4.private (papowell@h4.private [10.0.0.4])
	by astart2.astart.com (8.9.3/8.9.3) with ESMTP id KAA23275;
	Sun, 2 Jul 2000 10:15:38 -0700 (PDT)
Received: (from papowell@localhost)
	by h4.private (8.9.3/8.9.3) id KAA04677;
	Sun, 2 Jul 2000 10:13:31 -0700 (PDT)
Date: Sun, 2 Jul 2000 10:13:31 -0700 (PDT)
From: papowell@astart.com
Message-Id: <200007021713.KAA04677@h4.private>
To: doc@freebsd.org, nik@freebsd.org
Subject: Re: Indexing and glossary
Cc: ceren@magnesium.net, dgl@bsdi.com, jim@cdrom.com,
	murray@bsdi.com, papowell@astart.com, ryan@ryan.net,
	wpaul@freebsd.org
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

Hi, this is in response to Nik's posting about Glossaries.
It is probably WAY out of date with respect to the current discussion,
but I am 300+ 'must read' emails back.

Nik and I talked at length about glossaries.  Here is a suggestion
(probably Nik has made this as well) for Glossary production and
generation.

First,  there is the question of 'who gets to define the glossary
entries?'.

 a) done by the person writing the document
 b) obtained from some 'standard glossary source'
 c) both.

I like c).  It is fairly easy to do as well.  OK.  It is DIFFICULT
to set up but EASY to use.

First,  there must be some sort of reference glossary.  I like the
idea of being brutal and making this simply a file with glossary
entries in it.  This document can either be used as the baseline
for your glossary OR can be used by other documents to extract
glossary entries.

Next,  there is the way to produce the glossary for a document.

We steal^H^H^H^H^H borrow the method used to produce an index -
we generate the document using two passes - one pass to generate
the information for the glossary AND index and then a second
pass to incorporate this information and produce the actual document.

Actually,  you do not need to redo the first pass unless you change
glossary information or index information.  But I digress.

The mechanism to do this is a truly nightmare bit of code in the
DocBook DSSSL stylesheets.  Straight from the keyboard of Stephen
King himself this stuff is, but we can sacrifice some
victim^H^H^H^H^H^H^H^H^H get a volunteer to fix this up to produce
the glossary information as well as the index information.

So we have a mechanism to do the work,  now we have to decide on
policy for using this mechansim.  (I know that this is contrary to
all 'good' design techniques,  but I will quote 'If I have seen
further it is because I have stood on the shoulders of giants,
not trying to make a bloody set of stilts').

First,  how should you organize the document to have a glossary?

I like the 'automagic' method - you put the glossary entries IN
LINE and the Magically appear in the glossary.  The reason for this
is simple:  you can add the entries in the document as you write
them,  so the the context of where the definition is is kept.  (If
you do not like this,  then you can stick them all at the end of
the document - this has the same effect,  only the style will be
different).  OK,  I hear the yells and screams of pain,  so just
calm down...  It was just an idea.

OK,  we put them into a glossary at the end, wrapped up in the
Glossary stuff.

But how do you get 'automatic' glossary inclusions from a standard
set of glossaries?

You can use the GlossEntry thing with no defintion and the magic Perl
script that massages the document to get them.

For example (This is NOT a functional bit of SGML,  but simply
and outline of what it would sorta look like):

<!-- somewhere in the system -->
<!ENTITY % standard_glossary "IGNORE">

<glossary>
  <!ENTITY glossary.sgml SYSTEM "glossary.sgml">

  <!-- this is probably part of the DTD Stylesheet -->
  <![ %standard_glossary [
	  -- magic stuff to pull in all standard glossary --
    <!ENTITY % standard_glossary.sgml SYSTEM "whatever" >
      -- OR --
    <!ENTITY % standard_glossary.sgml PUBLIC "whatever" >
  ]]>

  <! -- the following is done only when you have the 'html-glossary' flag set--
     -- there is probably some magic way to get this effect without the need
     -- for wrapping this into the source level --
  >

  <![ %html-glossary [
    <!-- now we have the local definitions -->
    <glossentry id="filehash"></glossentry>  # causes the 'filehash' entry to be looked up
     # and if not present,  then a 'MISSING DEFINITION' message produced by the
     # PSFH (Perl Script From Hell) that is generating the glossary stuff

    <glossentry id="mydef>
      <glossterm>my definition </glossterm>
      <glossdef>
         Define the stuff from my definition.
      </glossdef>
    </glossentry>
    <!-- now we get the magic stuff that has been ripped out of the database -->
  ]]>

  %genglossary.sgml;
</glossary>


Lets see how this could be used

a)  You would first generate the index and/or glossary:

    perl collateindex.pl -t "Index" -N -o genindex.sgml
    perl collateglossary.pl -N -o glossary.sgml
    jade -V html-index -V nochunks -V html-glossary  \
        -i standard_glossary \       <<-- if you wanted the standard glossary stuff as well
		-t sgml \
        $(CATALOGS) -d /usr/local/share/sgml/docbook/dsssl/docbook-1.54/html/doc \  <<<-- you need this for index...
        book.sgml
	perl collateindex.pl -t "Index" -o genindex.sgml HTML.index
	perl -f /path/to/glossary/file/with/defintions collateglossary.pl \
         -o genglossary.sgml HTML.glossary

b)  You would then use:

    jade  -i output.html -V nochunks -t sgml \
        $(CATALOGS) -d $(DOC).dsl $(DOC).sgml >$(DOC).html
    -tidy -i -m -f /dev/null ${TIDYFLAGS} $@

and the usual variations on this them to get the document produced.

Just some thoughts on this.

Patrick Powell                 Astart Technologies,
papowell@astart.com            9475 Chesapeake Drive, Suite D,
Network and System             San Diego, CA 92123
  Consulting                   858-874-6543 FAX 858-279-8424 
LPRng - Print Spooler (http://www.astart.com)


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message