Conference vaxuum::document_ft

    Your three gripes are well taken.  Gripe number three is fixed for
    V1.0 . Contents file and index files contain all the information
    for the book, not just the update info.  Points one and two will
    have to go on the post v1.0 discussion list.
    
    David Parmenter
    

Hi Gavin,

I can address your third DOCUMENT problem.

      HOW TO CREATE A TABLE OF CONTENTS AND INDEX FOR AN UPDATE

When you create an update, a complete index and table of contents
must be created manually.  DOCUMENT creates only a partial 
update index and table of contents. As you have seen, it only generates 
the index and table of contents for the material that is specific to the update.

You must do the following to create a complete index and table of contents
for your update:


1.  Comment out ALL of your <update>(revision), <update_range> and 
    <endupdate_range> tags.  Process the whole book through DOCUMENT. 

2.  Save the the following two files:

    xxxxlist_contents.tex (the complete table of contents for the 
                           original book)
    
    xxxxlist.inx ( the complete index for the original book)

    To prevent confusion later on, you might want to rename these 
    files and/or put them in their own subdirectory.  
    
    For example, I called them allcontents.tex and allindex.inx.

3. Uncomment all of your <update>(revision), <update_range> and 
   <endupdate_range> tags.  

4. Process the book through DOCUMENT again.  

5. When the book finishes DOCUMENTing, you should have two new files -
   xxxxlist_contents.tex and xxxxlist.inx.

6. To create the table of contents, you must edit the original toc
   file to include the new updated entries.  According to my example, 
   edit allcontents.tex.

   To make the comparison between the two files easier, print out a 
   copy of xxxxlist_contents.

   Compare the entries in the new toc file (xxxxlist_contents.tex) with 
   the entries in the old toc file (allcontents.tex). You can cut and 
   paste your new toc entries into the file that contains the original 
   toc entries.  For example, if you've added a new section, you'll 
   want to add its entry from the new toc file to the old toc file. 

   When you complete the comparison, you'll have a new complete
   table of contents in allcontents.tex.  Now you ask, "What do            
   I do with the .tex file???"  Simple.  You run it through DOCUMENT
   using the following command.

   $ DOCUMENT/NOTAG allcontents.tex doctype device-type

7.  To create the index, you can use a TPU procedure created by
    Mary VAXUUM::Utt that will merge your old .inx (allindex.inx)
    file with the new one (xxxxlist.inx).  You can send mail 
    to her to get a copy of the procedure if she has it on-line, 
    or I'd be happy to send you a copy of it through inter-office mail.

    Once you merge the two index files, you'll get a file called
    upd_allindex.inx.  Run this file through DOCUMENT using the
    following command.

    $ MAKEINDEX upd_allindex.inx  

     This creates upd_allindex_index.tex  Run this file through
     DOCUMENT using the following command:
   
    $ DOCUMENT/NOTAG upd_allindex.index.tex doctype device-type

If you have any problems or questions, contact me.  I've recently completed
this procedure for one of my books.    

-Jean
 223-5002

    It seems to me that your procedure is far more complex than just
    surrounding everything with update ranges!
    
    Thanks for the input anyway... 
    
    Gavin

    
    All that will not be necessary in V1.0. As David mentioned, we have
    modified TeX to write all entries to the table of contents and index
    when an update is in effect, and not just the entries related to
    updated pages.
    
    Re: having to specify <update_range> in order to get marks: Not
    TRUE! You do need <REVISION>, and this should be specified in
    (preferrably, this is not required) a file that you /INCLUDE on
    the command line. If you have used <revision> and <mark>, but not
    <update_range>, you should get the revision bars. Did you try this?
    Or did you stumble on something in the documentation we should know
    about????
    
    patti
    

    The confusion about requiring the update_range tags comes from the
    discussion of <revision> on page 13-177 where the argument "UPDATE"
    is mentioned as being required for an update. I was not alone in
    wondering when is an update not an update - i.e., what is the real
    purpose behind this argument to <revision>? (We assumed that all
    revisions were updates... 'cos they certainly aint new docs!)
    
    Could this be clarified, please?
    
    Gavin

    
    I will see that it is clarified. Sorry for the confusion. The problem
    stems (as do many things in DOCUMENT, some for the better, some
    not) from the distinction in technical publishing between an 'update'
    to an existing manual and a 'revision'. A 'revision' occurs when
    a complete document is reformatted and printed, with (or without)
    change bars. An 'update' occurs when only selected pages are reprinted,
    and printed in such a way that the neew pages can be placed in the
    current version of the document to replace the previous pages with
    the same numbers.
    
    (such things at IBM used to be called 'Technical Newsletters' !!)
    
    -patti
    

    In .4 of this note you mentioned that V1.0 fixes the index and TOC
    update_range problem.  Does it also fix the <REFERENCE> tag problem?

    I processed a file yesterday (BL7) using the <REVISION>(Update),
    <UPDATE_RANGE>, and <ENDUPDATE_RANGE> tags to process and print a
    chapter page that had been revised.  The page contained two <REFERENCE>
    tags pointing to a table and a figure.  Here's what I got.

        <REFERENCE>(tCON_Indi) describes the function of each
        control and indicator in Figure 4-1.

    The figure referenced was within the update range and processed 
    correctly.  The table referenced was OUTSIDE the update range and did
    not process correctly.

    /Wes

    It is hard to believe that the resolution of the <reference>
    tag has anything to do with update ranges.  Was the symbol
    that was unresolved declared in another chapter?  If so, did you supply
    the /PROFILE qualifier, so that the XREF file could be read?
    
    bill
    

    No, the table whose symbol is referenced is within the same chapter
    file.

    Here's the situation:

    1. The <UPDATE_RANGE>(1\2) tag specifies pages 1 and 2.

    2. The full page figure whose symbol is reference on page 1, and which
       processes correctly, is on page 2.  It is followed immediately by the
       <ENDUPDATE_RANGE> tag.

    3. The table whose symbol was referenced on page 1 is on page 3,
       outside of the update range.  It does not process correctly, as
       stated in my earlier reply (.8).

    So you can see that the table (on page 3) that was referenced on page 1
    was within the file processed, but outside the update range and did not
    get process correctly.  This sure looks like a bug to me!

    /Wes

    
    re 8-10, I have been investigating off line. I could not reproduce
    it here, and Wes can't reproduce it either. 
    
    As Bill suggests, it really is of the 'can't happen' nature. The
    tag translator processes *everything* when an update is going on,
    not just the text in the update range tags.