🚀 go-pugleaf

In a recent misc.writing article, Thomas Beagle wrote (quoting me): 

>>We use SGML and our document structure includes index elements.
>>You can put them in as you go. ("Oh, I'm writing about error messages. That
>>should go into the index. BANG! There it is.")
>
>But when indexing as you go, how do you ensure that the index will be
>internally consistent?

Two ways:

  1. First, we have an informal standard for how we think index entries
     should be made. Essentially, it says "Index as much as possible, with
     as many headings as possible". (This is oversimplified, of course,
     but the idea is to give the user as many entries into the material
     as possible.)

     That means if I'm writing about the "Validate Document" command, I'll
     put in index tags for: Validate Document command, Special Menu commands
     (with a sub entry of Validate Document), SGML Parser (because that's
     what Validate really is), Error-checking (because that's what Validate
     does).

  2. Then in the first-printing edit stage, we standardize the entries. 
     This seems to come down to standardizing capitalization, mostly.

     It is very easy to find any entries that need to be changed, because
     the entries are (SGML jargon alert!) attributes to the index element
     and because (product plug alert!) the software has a powerful find
     function that lets me say "Find me the index element with the ENTRY
     attribute set to `Error-checking'".

>>I've worked in shops where the indexing was done by hand at the end of the
>>process. This is much, much better. Much better. 
>
>I can't help thinking that indexing by hand should be banned under the
>Geneva Convention. :-)

No argument here. I think it also contravenes the constitutional ban on
cruel and unusual punishment if you happen to be in the US. :-)

Marcy

-- 

Marcy Thompson		
  SoftQuad (West)			
    marcy@sqwest.wimsey.bc.ca (preferred) or marcy@sq.com