Conference vaxuum::online_bookbuilding

    So many people complained about that method of doing glossaries
    (with hotspots) that it has been changed completely for the Jan
    16 baselevel of the tools (that method also does not lend itself
    well to master glossaries). The complaints centered on your
    observation: it's not intuitive.
    
    Anyway, see the new 'Coding Documentation Source Files...'
    document referenced in note 64.1 for information about how
    glossaries (and messages) are now handled.
    
    Thanks,
    
    Mary

    I thought that the use of ranges in the TOC was the new method for
    handling glossaries. The range is what note 78 refers to.
    
    Thanks.
    
    Joyce

    Both the ranges in the TOC and the display of both gterms and gdefs
    (no hotspots) are the new method for handling glossaries. The reason
    for the ranges in the TOC was to make it easier for uses to navigate
    a very long glossary, or master glossary.
    

The use of ranges and displaying the gdefs without using hotspots are an 
improvement. However, it would be nice if users could get to glossary 
definitions directly from the text.

Presently, when users sees a boldface <newterm> in the text, they have to:

	1. Go to the TOC, move the scroll bar to the Glossary section
	2. Find the right range and double-click on it
	3. Go back to the main window and scroll until they find the term
	4. Go back to the TOC, find the place that they were before they went
	   to the glossary (if they can remember), and double-click on it
	5. Scroll within the topic to find the place they were when they stopped
	   to look in the glossary

There are two ways that we could improve glossary access:

	1. Make each <newterm> create its own hotspot; when users click on the
	   <newterm>, a new window appears (to one side, please!) with the 
	   glossary term and definition. The user can close the glossary
	   window, iconify it, or leave it open. The topic he was reading
	   remains open.

	2. Use the glossary the way DECwindows Help does. The glossary would 
	   have to change according to what book the user is reading -- don't
	   know if this is possible. When users come to a <newterm> they want
	   to look up, they choose Glossary from the Help menu, then click on 
	   the additional topic that is the term. As in case #1, the glossary
	   pops up in another window and doesn't interrupt the reading process.

    Agreed -- lots of room for improvement in glossaries. I've been
    thinking along the lines of your first suggested method. It's on
    the wishlist -- it will take a lot of changes: to the source files
    (to make sure every new term has a gloss def), to the tag translator
    and other parts of DOCUMENT.
    
    Thanks,
    
    Mary

I was disappointed to see that the new ONLINE.HANDBOOK doctype eliminates the
glossary ranges in the TOC. I think that this is a giant step backwards, because
now the only way to get to a glossry term that is at the end of the alphabet is 
to go to the glossary and keep hitting Next Topic until you get there. This can 
take a long time, expecially since the software has to draw the whole window 
before it will move on!

I think that the objection to the glossary ranges was that they looked confusing
because of the ellipses:

	adopted child . . .call-out
	chaining . . .delivery environment

It might be better if we kept the ranges and displayed them as follows:

	adopted child . . .
	chaining . . .

The chances are not great that the user is actually looking for the second term
of each pair, and users should be able to figure out the alphabet!

However, I'm really glad that we have ONLINE.HANDBOOK now, because I need
<code_example> arguments in parentheses to come out as monospace, just as they
do when you use <endcode_example>. This doctype saved me from having to mung the
design file. ONLINE.HANDBOOK is less forgiving than ONLINE (or is it the change
in DOCUMENT overall?): it broke over lots of sloppy coding that used to get
through with no errors or problems.

    You *can* get glossary ranges: what people didn't like was *always*
    getting them; they wanted them to be optional. So I added a MASTER
    argument to <SET_ONLINE_TOPIC> (the idea being that you want the
    ranges in large, or master, glossaries or messages manuals). So,
    if you code your file as follows you will get the ranges:
    
    <SET_ONLINE_TOPIC>(MASTER)
    <GLOSSARY>
    <GDEF>(xxx)
    <GTERM>(xxx)
    ...etc.
    
    You can also turn off the ranges with a NOMASTER arg, in case you
    later have a section you don't want the ranges for.
    
    This is documented in the 'Coding Documentation Source Files...'
    document issued with the Mar 20 baselevel and referenced in
    note 64.2.
    
    Mary 

I found another problem with glossary ranges in ONLINE.REFERENCE; it may be 
present in other ONLINE doctypes as well:

When a <GTERM> uses \smallcaps or \small_boldcaps, it appears as a tilde 
in the TOC when it is listed as part of a glossary range. To check for this,
put the first or last glossary <GTERM> in \smallcaps or \small_boldcaps.

If you don't use \small_boldcaps, it won't come out bold in the hardcopy 
version. That's how we would up with \small_boldcaps there. I had to use 
regular font for the Bookreader glossary entries for Boolean operators such as
AND and OR, although we used smallcaps for them throughout the rest of the doc.

    You need to use the <delayed> tag in the <gterm>:
    
    <gterm>(Some text <delayed>(<small_caps>(small text)) text)
    
    This is documented in more detail with examples in Section 1.8,
    Coding Documentation Source Files for the DECwindows Bookreader
    (March 17).
    
    Thanks,
    
    Mary

    Hi,
    
    Is there a way to get the first range to pop up with the Glossary
    title? Right now, if I click on the word GLOSSARY either in the
    TOC or in the text (if it's a hotspot), I get just the word Glossary
    on a screen. I have to click on MORE to get the first range.
    
    It would be more useful if the first range come up with the Glossary
    title, I think, but I'm not sure what the technical difficulties
    are, or if indeed there are any.
    
    Thanks.
    
    Joyce
    

    This has been requested before and is on the list. It won't be in 1.2B
    but I hope for the next round of changes/improvements/fixes. There are
    no huge technical difficulties, just a matter of finding the time to
    make the tag def smarter about the first range.
    
    Thanks,
    
    Mary