Conference vaxuum::online_bookbuilding

    Just to try to clarify the definition of 'chunks'.
    
    Chunks are the smallest unit that the Bookreader can access from the
    table of contents or the index. (It knows nothing about the contents
    of chunks, which is why the Bookreader cannot go right to a line in
    a paragraph from an index entry.) Bookreader displays the chunk that
    the TOC or index refers to with the top of the chunk in the top of 
    the text window. If the chunk is bigger than the text window, the
    user may have to use the scroll bar to get to the referenced text.
    
    Right now chunks are denoted by:
    
    - all header tags
    - all formal figures, tables, and examples
    - all template heads (including Description, Overview, Examples, etc.)
    - footnotes, glossary terms, messages
    - miscellaneous: title page elements, copyright page elements, etc.
    
    In TeX terms, a new chunk means a new page break, which is why online
    books have so many more pages in them than the hardcopy books.
    
    Just to round out the definitions, a 'topic' consists of one or more
    chunks displayed contiguously in the text window (if the topic is
    larger than the text window, you have to scroll down). For example, by
    default, <head1> denotes a topic, so it and all its subordinate heads
    (if any) comprise a topic. (<set_online_topic> allows you to  
    adjust the granularity of a topic at the header levels: if the <head1>
    topics are too long and unwieldy, you can make <head2>s or <head3>s
    the topic level for better usability.)
    
    Back to chunks: it is easy to define almost any tagged element of text
    as a chunk, such as <argitem>s, which Kirk requests. (I've given him
    a set of tag defs that do this for his group to test that the tags do
    what they want.) It's possible to make every paragraph a chunk, if this
    is a truly useful thing to do. 
    
    By 'truly useful,' I mean *not* as a workaround for sections that are
    too long, or not broken up by enough heads, to begin with. Text is most
    readable online as short sections with short, clear headers: users will
    not like clicking through window after window in a single topic. (My
    patience runs out at about the 3rd click.) I don't think this means
    distorting text for online presentation: users of hardcopy manuals will
    also lose their patience if a section runs on for page after page.
    Simply making each paragraph of that section a chunk is not likely to
    increase the  usability of that section online.
    
    Also, rather than willy-nilly making template elements chunks as people
    request it, I think we need to take a top-down look at how best to
    present templated information online and how fine the chunk granularity
    should be in general. 
    
    In other words, I think we need to start looking hard at what works
    online rather than simply retrofitting existing hardcopy books and to
    make changes on that basis, not solely on the basis of what will solve
    this afternoon's problem with a book that was written 3 years ago.
    (Which is *not* to say that we aren't going to help solve this
    afternoon's problems.)
    
    Gee, I only meant to define 'chunk' -- I guess the point is that
    'chunk' is an important concept for online documentation and needs to 
    be considered from that viewpoint.
    
    Mary                  
    
    

When it comes to using the index, I think the smaller the chunk,
the better. In a hardcopy manual, one expects the page number in
an index entry to take one to the page where the indexed item is
described -- not to the previous page! As an online reader, I
would expect the same! It would not naturally occur to me that I
might have to scroll thru several online pages to find the
indexed item. 

As it turns out, I've coded items in an Argument section using
<paramitem> and <paramdef> and the online index DOES take me
directly to the item I click on -- it even puts the indexed item
right at the top of my window, which I think is great! (Aside: I 
believe every table row is also considered a chunk -- not just
the whole table. I know the index takes me to lines in the middle
of a table -- not just to the top.) 

As long as the bookreader does not consider every chunk to be a
*topic*, I'm in favor of small chunks. 

I think OLD can be used to tremendous advantage for reference 
manuals. The whole trick is in being able to take the reader
right to what they're looking for while bypassing everything
they're NOT looking for! 

    Yes, <paramitem> is a chunk, but <table_row> is not. Formal tables
    are handled somewhat differently in the popups than text is in the
    text window, which accounts for what you're seeing there.
    
    Mary 

    Do I understand this correctly?  <PARAMITEM> denotes a chunk
    but <ARGITEM> doesn't?  Does it make sense to have one and not
    the other represent a chunk?  I'm not suggesting it doesn't, but
    was surprised that they weren't the same as far as chunkiness
    goes.

    I was just astounded to discover that a figure is not a chunk?
    Can this be true? I have an index entry inside a <figure> tag;
    when I click on the index entry, it takes me to the top of the
    section! I certainly did not expect that! (The figure reference 
    is still a screen away.) I had expected I'd go from the index
    right into the popped-up figure! (When I click on an index hit
    inside a table, it takes me right inside the table to the line
    I want.)

	Re:                       <<< Note 118.0 by SLIMY::SEARLE >>>

>In particular, I aver that argument lists in reference sections are
>typically too big to be handled as a single chunk.  


	this is certainly not the case in the ALL-IN-1 reference
	material. the number of arguments tends to be low, and their
	descriptions tend to be fairly short. i think that, if you
	were to vary the size of a chunk, there would have to be some
	flexiblility.
	
	looking at this from the user's point of view...as i become
	more familiar with a book, i tend to have a better idea of the
	information i want to get out of it, and of where to look for
	the information. perhaps what i want is to be able, as a user, to
	specify the chunk size in the book i'm reading. 
	

	jack

    .4 Yes, paramitems have been chunks for awhile (blush). I seem to
    recall that VMS had a problem similar to yours some time back. I
    haven't been eager to go around and make things chunks willy-nilly.
    In most of the cases I've seen to date these items have been short
    (as Jack Horsfield notes in .6). Now, I'm convinced that they all
    should be chunks and we'll set about doing that for a future online
    tools baselevel.
    
    .5 It's true: if you code a formal figure as follows, the index
    entry will take you to the text that references the formal figure,
    not to the figure itself (the TOC pointer is fine):
    
    <figure>(Figure One\one)
    <x>(Index entry)
    <figure_file>(...)
    <endfigure>
    
    I will look into this, but the following coding will do the right
    thing (and won't affect hardcopy):
    
    <figure>(Figure One\one)
    <figure_file>(...)
    <x>(Index entry)
    <endfigure>
    
    Thanks for finding this.
    
    .6 I'm not sure I understand what you're asking for. Making every
    argitem or paramitem a chunk won't affect the formatting: the list
    will look the same in the text window but, because of the finer
    granularity of the chunks, index entries will be more accurate
    (instead of being taken to the top of the list, you will go to
    the exact item referenced). As for users being able to define
    chunk granularity, maybe version 6 of the Bookreader...? :-)
    
    Mary

>    .6 I'm not sure I understand what you're asking for. Making every
>    argitem or paramitem a chunk won't affect the formatting: the list
>    will look the same in the text window but, because of the finer
>    granularity of the chunks, index entries will be more accurate
>    (instead of being taken to the top of the list, you will go to
>    the exact item referenced). As for users being able to define
>    chunk granularity, maybe version 6 of the Bookreader...? :-)


	actually, i wasn't asking for anything. i just got worried
	by the prospect of every paragraph being a chunk - that's
	the sort of accuracy i can do without.
	
	jack