This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

RE: IndexTerm: why not See+ ?


We consider using (most of) the content model of DocBook's 
IndexTerm in another DTD (for legal documents). I also 
searched for a suitable content model in other 'standard' 
DTDs, but indexing seems to be pretty lame in other DTDs.

Your explanation is BTW in perfect harmony with 'Read Me 
First!', Sun Technical Publications, chapter 9 'Indexing'.

I'm trying to figure out whether to add an attribute to 
let authors/mark-up'ers (what are they called?) indicate 
the preferred formatting of the resulting index entry for 
each IndexTerm, e.g., ordinary with page number, with a 
section number, with the contents of a title element, or 
whatever. I might just add a 'Format' attribute similar 
this one:

Format  ( Default
        | Page 
        | Section 
        | Title 
        | Whatever )  Default  -- Preferred format of index entry --

or maybe make it CDATA so that I don't have to release a new 
DTD when the need for more formats arise, 

or maybe invent Yet Another Link Description Language,

or maybe just rely on context and processing to figure out 
how to present the reference.

Experiences? Suggestions? Comments?

Kind regards
Peter Ring

-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com]
Sent: Thursday, September 30, 1999 4:32 PM
To: docbook@lists.oasis-open.org
Subject: Re: DOCBOOK: IndexTerm: why not See+ ?

/ Peter Ring <PRI@cddk.dk> was heard to say:
| The IndexTerm element looks like this:
| 
| <!ELEMENT IndexTerm - O (Primary, ((Secondary, ((Tertiary,
| (See|SeeAlso+)?)
| 		| See | SeeAlso+)?) | See | SeeAlso+)?) %ubiq.exclusion;>
| 
| Why the repetition of 'SeeAlso' but no repetion of 'See'?

The intended semantic for 'See' is that the reader should be directed
to another term. For example

  ...
  DocBook SGML, see SGML, DocBook
  ...
  SGML
    DocBook, 3,5,7,9
  ...

In other words, the purpose of See is to indicate that the
desired information is indexed differently than the reader expected.

It wouldn't make sense to point the reader to more than one place with
See.

Now, it might make perfect sense to have a number of SeeAlso's under
the "correct" index entry:

  ...
  DocBook SGML, see SGML, DocBook
  ...
  SGML
    DocBook, 3,5,7,9
    See Also, XML, DocBook
  ...

Does that clarify the semantic?

| With most processing, you'll anyway be able to get more than one 'See'
| for each entry, just by putting in another IndexTerm element similar
to
| the first except for the content of a 'See' element.

It would also be reasonable for the processing application to signal an
error in this case.

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | My problems start when the smarter
http://www.oasis-open.org/docbook/ | bears and the dumber visitors
Member, DocBook Editorial Board    | intersect.--Steve Thompson,
                                   | wildlife biologist at Yosemite
                                   | National Park


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]