Conference vaxuum::document_ft

78.0. "/SYMBOLS qualifier with book builds" by VAXUUM::KOHLBRENNER () Mon Mar 09 1987 11:50

The writers of DOCUMENT's documentation have discovered a bug in
the tag translator and I am posting it here to minimize bruxism.

If you are building a book with a <profile> and following all the
"rules", you will have isolated your <define_symbol> and 
<define_book_name> tags into a separate file and will be specifying 
that file's name in a /SYMBOLS qualifier on the command line.

  $ DOCU/SYMBOLS=mysymbols myprofile doctype dest

That works fine.  The symbols in the /SYMBOLS file get defined and
they can be referenced from anywhere in the book.  The symbols that 
you defined in the /SYMBOLS=mysymbols file have not been saved in 
the CRF file.  You can change them independently of changes in your
book, and the next time around, you will get the latest version of
these special symbols.

When it comes time to do some work on an individual element of the book,
you will be using the /PROFILE qualifier in order to process that
element by itself.  You will also use the /SYMBOLS qualifier to again
include the special symbols, in their latest form.

  $ DOCU/SYM=mysymbols/PRO=myprofile myelement doctype dest

That works fine too.  You get good printed output, references to the
symbols in "mysymbols" get resolved correctly, and you think, "Wow,
this new bookbuilding stuff is great stuff!"  :-)

The tag translator will have saved a new version of the CRF 
file after this element build.  However, the CRF file may MISTAKENLY 
include the symbols from the /SYMBOLS=mysymbols file.  So, you have
a new CRF which has symbols in it that should not be there.

On the NEXT element build, you will normally specify the /SYMBOLS
qualifier again, and the tag translator will start to complain that
the symbols from the /SYMBOLS=mysymbols file are being defined twice!

To compound the problem, the error is not guaranteed to occur, since
there is a chance that the error will be masked by other actions that the
tag translator takes.

   *******************************************
   * This problem is fixed in the FT update. *
   *******************************************

If you are using the /SYMBOLS qualifier in a bookbuild/element build
situation and you have not hit this problem, you are simply lucky.
You should code around it as follows:

1.  Add an <include> tag AFTER the first element's element heading tag.
    Suppose you have a <front_matter> tag as your first element heading
    tag.  Then, add an <include> that names your /SYMBOLS=mysymbols file.

    <FRONT_MATTER>(front_matter_elem)
    <INCLUDE>(mysymbols.gnc)  <comment>( ** THIS IS TEMPORARY ** )

    This tells the tag-translator to read your "mysymbols" file as
    though it were part of the front-matter element.  This will 
    cause the tag translator to save the symbols from "mysymbols"
    in the CRF as if they were defined in the front-matter.

2.  Do a bookbuild in order to get a clean CRF file.  (You can
    specify the /NOTEXT qualifier, since there is no need to go 
    beyond the tag translator.)  DO NOT supply a /SYMBOLS qualifier
    on the bookbuild's command line!

3.  Now you can do element builds on any element.  Again, DO NOT
    supply a /SYMBOLS qualifier on the command line, since the symbols
    from your mysymbols.gnc file are already in the CRF as part of 
    the front matter of your book.

4.  If you have need to change the mysymbols.gnc file to add, delete
    or modify any of its <define_symbol> or <define_book_name> tags,
    then do an element build on the front matter element, in order to
    get an updated CRF.  Then you can proceed with any other element
    builds.

Please regard this as a temporary solution.  Making these symbols part
of your front matter means that every time they change you have to redo
your front matter.  If other book writers are also using these symbols,
they will have to redo their front matters as well.  It works, but it's
a poor substitute for the /SYMBOLS qualifier.

Bill, is there an .EXE or some file that we can copy now to update our
system?

Thanks.

Marty

    No.  I'm almost certain that the development version of the tag
    translator (which will become the field test update) will fail if
    it is just substituted into the currentle released version of the
    field test software.  Gotta wait for the FT update...