Conference vaxuum::document_ft

    Note that "running title" still seems to work.  However, it's not
    in the documentation.

    
    It works in REPORT, ARTICLE, OVERHEADS, and SOFTWARE.SPECIFICATION
    only. Volume 2 of the U.G. should list it under the doctype-specific
    tags. 
    

    How old is your docset?  The <running_title> tag is documented for
    the ARTICLE, GENERAL, and OVERHEADS doctypes in the Field Test version
    of the VAX DOCUMENT Users Guide Part 2 (put out in last December).
    
    The same applies to the month old Field Test Update version of that book
    (now called the User Manual Volume 2), except that BL7 GENERAL doctype
    is called REPORT under BL8--see the release notes for details..
    
    -Randy                            
    

    Problem is that it's not documented in part 1 of the users guide.
     Shouldn't it be?

    No, not really.  In the beginning of both books we set up the following
    distinction between Volume 1 and Volume 2:
    
    Volume 1 describes tags that work in all doctypes (global tags)
    
    Volume 2 describes tags that are doctype-specific and do not
             work in all doctypes.
    
    <RUNNING_TITLE> is now available in several doctypes but until 
    it is available in all of them, it can't  really be said to be "global"
    and so be put into the User Manual Volume 1.
                                              
    Hope that clears things up.
    
    -randy

    Does that distinction really hold? <HEAD1> and <CHAPTER> appear
    in Vol 1 but neither tag is allowed in the LETTER doctype.
    
    --Andrew

    The distinction holds for the majority of the tags but not for all.
    
    General use tags such as <LIST>, <P>, and <TABLE> work in all doctypes
    and so are written up in Vol. 1.
    Very doctype-specific tags such as <MEMO_TO>, <SLIDE>, and 
    <SPECIFICATION_INFO> work only in a single doctype (letter, overheads,
    and milspec, respectively) and so are written up in Vol. 2.
    
    As DOCUMENT has matured and users have asked for more functionality
    (excuse the word), we've gotten tags that work in more than one
    doctype but are not global (<RUNNING_TITLE> is a good example).  
    We've also got global tags such as <CHAPTER> that are not available
    in certain doctypes. In the case of LETTER, we made the assumption 
    that people don't typically write chapter-oriented letters, and so 
    didn't want or need the <CHAPTER> tag.
    
    I guess to answer your question, the distinction holds for the
    beginning to intermediate DOCUMENT user and helps them figure out
    what tags they need to learn first.  The distinction probably gets
    a bit blurry for someone that regularly codes in several doctypes.
    
    -randy

        Perhaps a more straightforward organization of the
        documentation would have all tags in a single sequence,
        alphabetically, in only one volume.  Part of each
        description would identify for which doctypes the subject
        tag was valid.  An appendix could have one list per
        doctype of valid tags for that doctype, without detailed
        documentation of specific tags. 
        
        I realize that this would be a lot of work to change
        -- but I would find the result much easier to use.

    A re-org of the docset will probably have to be made for a future
    release, we've noticed the problem with usability ourselves.
    
    If it's any consolation, there will be an appendix like the one
    you describe in V1.0 of the docset.  The appendix lists
    each tag, what doctypes its available in, and gives a brief one-line
    description of what the tag does.
    
    -randy

    .8 -- Excellent suggestion.
    
    Also, in the current format, I find that it is difficult to know
    what "subsection" of the software doctype tags you are in. It would
    be most helpful to have a running subhead/foot or something that
    tells you that you are in the "command section" template.
    
    Marty

    The following discussion comes from the new (for V.1) 
introductory chapter of the VAX DOCUMENT User Manual, Volume 1. 
Perhaps this description will help clarify a muddy area?  -Barbara


<head2>(Doctype-Independent and Doctype-Specific Tags)

<p>The majority of the SDML tags used for marking your text are valid in
any of the doctypes. These tags are called "doctype-independent" or "global,"
as they                                                                     
work in all doctypes for which they are appropriate. For example, all
doctypes use paragraphs and lists, so <tag>(p) and <tag>(list) are accepted
in all doctypes. 

<p>A few of the tags that are listed as global in this manual have
restricted use, as they are not appropriate in one or more doctypes. 
For example, the doctypes LETTER or OVERHEADS 
do not contain front matter, such as a title page or preface,
so the front matter tags (accepted in most doctypes) 
are restricted in these doctypes. 

<p>Tags that are used specifically in  one doctype only
are called "doctype-specific." 
For example, only a letter contains an address from the person sending
the letter, so the doctype-specific tag <tag>(from_address) can be used
only in  the LETTER doctype. 

<p><reference>(ugp1_tagtable_app) lists all the global and doctype-specific
tags. It also  identifies the doctype to which each 
doctype-specific tag belongs. 

<p>Because it has no restrictions on the use of global tags,
when first experimenting with <reference>(product_name), 
you might want to process your input file using the MANUAL doctype. 
Later you can
experiment with the other doctypes, simply by reprocessing your SDML 
files and
specifying the new doctype on the command line. If the SDML files include tags
that are not recognized in the specified doctype, informational messages
are issued, and you can either fix the errors or go back to using the
MANUAL doctype.

    Re/ .11:
    
    If that's the SDML file for the User Manual, why does it contain
    strings like
    
    	"phrase"
    
    instead of 
    
    	<QUOTE>(phrase)?
    
    Don't you have to use <QUOTE> in order to get left/right quotes?

    Well, I did alittle editing of the file before I put it in NOTES,
    but stopped in the middle and didn't remove the majority of the
    tags. Anyway, that's really off the subject. On the other hand,
    this whole discussion is off the original subject of the NOTE.
    
    <oparen>I knew when I put that partial file in here that someone would
    pick a few nits about it, but just wanted to add my <twocents>.<cparen>

    Barbara, that's why programmers NEVER display their source
    code in a public place...
    
    ;-)