| Barbara,
Although you are correct in stating that the restriction is documented,
I'm not sure that's the issue here. I think it is disconcerting
to users to find that a file that processed before, doesn't process
anymore. (I know, I know... that was a file and this is a bookbuild,
but to a user DOCUMENT is DOCUMENT.)
I can understand the restriction for avoiding text and text-producing
tags outside elements, but why are DEFINE_SYMBOL tags flagged as
out of context? They are *not* specific to the element necessarily
and do not produce any text? I guess my point is: can DEFINE_SYMBOL
tags be handled like COMMENT tags and allowed at the beginning of
element files?
--Andrew
|
| This is a reply to 51.2, regarding placement of <define_symbol>
tags.
<DEFINE_SYMBOL> defines a symbol which goes in the symbol table.
When you process the element by itself (not in a bookbuild and without
the /PROFILE qualifier), the symbol table gets thrown away at the end
of the DOCUMENT execution.
But when you process the element through a bookbuild, the symbol table
gets saved in a CRF file. This allows you to process each element of
the book independently, using the /PROFILE qualifier, and yet keep
the symbol table up to date at all times. In order to properly update
the symbol table during each individual element build, we start by
throwing out all the symbols in the table that came from that element
the last time around. Then, during pass 1 over the element's files,
we add to the symbol table all the symbols that are currently
"in" the element. (This may mean throwing away N symbols and
then putting them right back in again, unchanged, but it insures that
if you remove a symbol, then it is truly gone, and if you add a symbol or
modify a symbol's value, then the new value is now correct in the table.)
How do we know which symbols came from which element of the book?
Well, each element-heading tag (<chapter>, <appendix>, etc) MUST have
a symbol. Call that the "element symbol." The element symbols get
numbered during a bookbuild (this "element number" is different from the chapter
number which you see in your printed output.) Every symbol that is
declared within an element gets the same element number as its element symbol.
For example, chapter 5 of your book may get element number 9 assigned to it
(and chpater 6 will get element number 10). Every symbol from a
<figure>, <example>, <table>, <headn>, etc, tag in
chapter 5 will also have element number 9 assigned to it.
The element number is part of every symbol's entry in the symbol table
and so it gets saved in the CRF at the end of a bookbuild.
(You don't ever get to see these element numbers, since they are never
printed out on anything. They are only for bookkeeping, heh heh.)
Later, when we start an element build (with /PROFILE qualifier) we load the
CRF into memory and then go looking for an element-heading tag so we can get
its symbol and look it up in the symbol table. Once we find it in the
table, we have its element number, and then we can make a search throu�h
the table and throw out every symbol with that element number.
So what happens with a <DEFINE_SYMBOL> that is "ahead" of the <chapter>
tag that starts the element? Until we hit the <chapter> tag, we don't
have its symbol and we can't tell what element this is going to be.
The <DEFINE_SYMBOL> tag's symbol is already in the table (from the last
time this element was processed), so it looks like this is a duplicate
definition of the symbol.
So, for bookbuilds and element builds, the <DEFINE_SYMBOL> tags have
to be in the /SYMBOLS file, or "after" an element-heading tag.
*********
The problem of having a file that processes cleanly by itself and fails
as part of a bookbuild or element build is not nice.
I think the "cure" is to make it do the same thing in both cases,
and in this situation, it ought to fail in both cases. That is, a
<define_symbol> tag ought to be in a /SYMBOLS file or it ought to be
"within" an element, this is, following a <chapter>, <appendix>, etc.
But what about someone who is just writing a long memo? He doesn't
want to spell out "Digital Equipment Corporation" so he puts
<define_symbol>(dec\Digital Equipment Corporation) at the top of the
GNC fi|e and then puts <reference>(dec) at each place where he
needs the text string "Digital Equipment Corporation." It works now.
If we adopted the "cure" of the preceding paragraph, he would have
to put the <define_symbol> tag in a /SYMBOLS file, but that is not
very friendly.
We are trying to make it easy for the memo writer as well do the
whole job for the builder of books.
The cost is born in the annoyance caused to bookbuilders who write
a chapter BEFORE they put it in the book. The annoyance is not that
they have to make a simple editing change, but the fact that it
worked fine for the preceding month and now it does not work!
If the chapter is put into the book when it is empty, and then
always processed as an element of the book (supplying the /PROFILE
qualifier for every DOCUMENT execution), the error message appears
on the first use of the <DEFINE_SYMBOL> tag "outside" an element.
The decision can then be made to move the <define_symbol> tag to
the /SYMBOLS file or tuck it "inside" the book element.
|
| Well, I'm not trying to argue semantics, I'm just trying to say
that this feature is not an <include> tag problem. Also, keep
in mind that we are documenting the new version for *external* users
only, so they won't know the difference between the old and the
new functionality...but, anyhow, I went ahead and made a note in
the description of the <include> tag, to make sure users don't
place book element tags after <include> tags. Anything that can
make it clearer, right?
Re: Note 51.2, I don't know. I'll forward your question to the
expert on the case, Bill K. -Barbara
|