Conference vaxuum::document_ft

Various tags associate text (or a title) with a symbol name 
(<define_symbol>, <define_book_name>, <chapter>, <table>, etc.)

In all cases, the text CANNOT have imbedded tags in it EXCEPT for the
<reference> tag.  We special-cased the <reference> tag.  Without
the special-casing it would not work either.

The problem is that the text and the symbol are "gathered" during
pass 1 and stuck in the symbol table.  So in the process of gathering
the text of say, the <define_symbol> tag, if we encounter an
imbedded tag, we just replace it with its definition.  Most of the
SDML tags have a null definition in pass 1, or simply do some
validity checking.  That is they do not "output" anything.  For example,
the <p> tag has a null definition in pass 1, since it does all its
work of outputting TeX macros in pass 2.  So the <p> tag gets
removed from the text and replaced with nothing and then the text
gets stored off in the symbol table with the associated symbol.
Thus the imbedded tags "disappear."

(The <reference> tag is special, in that (in pass 1) it tries to look up the
symbol that is being referenced, and if the symbol is not yet
defined it recreates the <reference> tag in the text, expressly for
the case where the text is going to be moved off to the symbol table.)

There are various solutions to this, all expensive in terms of time
to implement and debug, so we cannot do it for version 1.

The interim solution (for Digital-internal users, but not 
for customers)  is to drop back to using the <redefine> tag
to associate a "symbol" with some text that contains imbedded tags.
In this case, the "symbol" will actually be a tagname, with all the
old dangers of choosing a name that is the same as an SDML tag,
failing to get a warning if you redefine the same name twice,  etc.
Instead of using the <reference> tag to reference your "symbol",
you must invoke it as a tag.

So, instead of 

   <define_symbol>(foobar\Some text. <p> Some more text.)
   .
   .
   .   <reference>(foobar)

you must say:

   <redefine>(foobar\Some text.  <p> Some text.)
   .
   .
   .  <foobar>

Furthermore, the <redefine> tag must be at the front of your
SDML file.  It CANNOT be in a file that you bring in with the
/SYMBOLS qualifier, although it will work if you bring it in
with the /INCLUDE qualifier.  If you want to reference it in
each chapter of a book, then you should put it in a file and
/INCLUDE that file each time you run an individual chapter or
put an <include> tag at the front of each such chapter, so that 
when you process the chapters individually, they will each 
have the tag defined.  

(By the way, for those of you who understand the use of the
"quoting" characters (| and &), be assured that they do not
work as a solution to this problem, either.)

One of the wishlist items for version 2 is a better way for
users to define their own tags.  In the meantime, you have
to omit tags from the text that is associated with a symbol
name OR resort to the messy process of defining your "symbol"
as a "tag".

RE < Note 336.1 by VAXUUM::KOHLBRENNER > 

    I have defined a symbol that has an <EMPHASIS> tag in the text,
    and it works fine:

	<DEFINE_SYMBOL>(PostScript\
	    P<EMPHASIS>(ost\smallcaps)S<EMPHASIS>(cript\smallcaps))

    When I use <REFERENCE>(PostScript), it gets translated just fine.
    Doesn't this count as an imbedded tag in the text associated with
    the symbol name?  You said the text cannot have imbedded tags in
    it (except for the <reference> tag).  I guess I don't quite understand
    your reply, Bill...

							-- Nina

    <emphasis> happens to do the same action in pass 1 as in pass 2,
    so you lucked out, Nina.  There is no guarantee that other tags
    will.  We saw that <p> does not.  I wanted to state the rule
    as "Don't do it" rather than, "You can use the following tags, but
    all others will not work."
    
    We don't even have time to compile the list of tags that would
    work, let alone fix the problem...      :-)

    RE .-1
    
    Well, this looks, at least from a pure user point of view, like
    a loss of user functionnality from BL6 to V1 ?
    
    Marc.

    
    Not particularly. We will be recommending for internal users who
    require the function to use the <define> tag as in the past. Customers
    never had the feature, so won't miss it and should be happy when
    we provide a cleaner way of doing it in the future. (I say cleaner
    because using <define> as is requires documenting the | and & that
    are required...we want this to go away from the user's point of
    view.)
    
    patti
    

    Then <define> still works, even though it's not in the documentation?
     Or is it <redefine>?
    
    Personally, I think that customers may feel that the inclusion of
    tags within a <define_symbol> would be required functionality. 
    But then, you people know best.
    
    (Guess I'm just spoiled for the 'loss' of this feature that I used
    so extensively in BL6.

    At the very least, the DOC$CONVERT program should NOT automatically
    convert <define> tags and their associated symbols.
    
    (From one who has now spent several days converting a lot of <define>'s
    that, in the end, would have worked just fine the way they were!)

    
    Sorry about the confusion on this. Yes, I expect it's a feature
    that customers will expect and ask for. We just want to be sure
    that when we give people the ability to define tags we do so in
    a way that we can document easily and support !
    

    Can I safely use <define> for my documents (that is, will <define>
    remain an undocumented, but present, feature of not only the field
    test version, but the first release of the product as well.
    
    I'd sure like the answer to this one to be a "YES"!
    
    Thanks

    
    we will not remove <define>; we need it.
    
    pa

    <DEFINE> will continue to work for you because you are giving
    it only two arguments, the tagname and the tag's definition.
    It still does the same thing with those two arguments that it
    always did.
    
    But <DEFINE> now takes 7 more arguments, so if you make a mistake
    coding your second argument and slip in a backslash such that it
    looks like an argument separator, you will be using a <DEFINE> 
    with three arguments instead of two.  Many SDML tags will give
    you a GTMAXARGS error message when you make such a mistake,
    but <DEFINE> is going to try to use that third argument and
    you may get a very strange error message.
    
    The reason that we don't document <DEFINE> is that we can't do it
    without describing all 9 arguments, and that requires a whole
    book to do (literally!).  We have a writer working on that book
    right now.  He has the description of <DEFINE> done, and is now
    working the MANY chapters of conceptual material that are needed
    to understand what those last seven arguments do.
    
    So, as Patti says, we will not remove it.          bill