[Search for users] [Overall Top Noters] [List of all Conferences] [Download this site]

Conference vaxuum::document_ft

Title:DOCUMENT T1.0
Notice:**New notesfile (DOCUMENT.NOTE) now available (see note 897)**
Moderator:CLOSET::ADLER
Created:Mon Feb 09 1987
Last Modified:Thu Oct 31 1991
Last Successful Update:Fri Jun 06 1997
Number of topics:897
Total number of notes:4397

572.0. "Examples in User's Guide Part 1" by PANAMA::GILLIAM () Mon Jun 29 1987 14:15

The VAX DOCUMENT User's Guide Part 1 contains numerous examples 
where arguments are specified are on the line AFTER the accompanying SDML tag.

For example, the <EXAMPLE> tag is documented as follows:

<EXAMPLE>
(VAXcluster Multifile Summary\mult_file_summary)

<EXAMPLE_ATTRIBUTES>
(wide)
     .
     .
     .

If I code an example as described above, three things will happen.

1. The tag translator will report a "tag not defined" message for any
symbolic references, if present.

2. DOCUMENT appends the arguments to the <EXAMPLE> to the preceding paragraph,
if present.

3. DOCUMENT generates a example number "0:" without a caption.

The only clue the user sees to know that this is going on is the "tag not
defined" message.

I would expect this behavior to occur with tags that contain OPTIONAL 
arguments, for example, <EXAMPLE>, <TABLE>, and <FIGURE>. I suppose the tag 
translator sees a <FIGURE> tag without arguments and the rest is history.

In any case, the documentation should present legal coding. New users (and
experienced users unfamiliar with a particular tag or tag sequence) will
think that arguments need not begin on the same line as the tag (which is
probably permissible for tags with required arguments).

If this has already been mentioned, please ignore this note.

Mason
T.RTitleUserPersonal
Name		DateLines
572.1bug in outputCLOSET::ANKLAMMon Jun 29 1987 14:1813
    
    There was unfortunately a bug in the <TAG> tag on the development
    system when the U.G. was processed. I spotted and fixed the bug,
    but wasn't aware until just recently that that was the version
    we distributed for BL8. 
    
    All tag arguments must follow the tag, on the same line and with
    no intervening spaces.
    
    Sorry for any trouble this caused. 
    
    patti
572.2Why this restriction?BLURB::WHARTONWed Aug 05 1987 10:3116
    I also encountered this problem by following the format of the
    examples in the Document User's Guide.  I think that allowing an
    end of line delimiter between a tag and an argument list would
    improve Document because the practice makes .SDML files more
    readable.  In addition, DSR developers used to recommend this
    practice and customers converting from DSR to Document are therefore
    likely to code files that way.
    
    In my case, putting the end of line between the tag and the argument
    generated an internal error as well as the undefined tag error.
    Any time software generates a message with the words "internal error,"
    you are guaranteed SPRs, regardless of what the documentation says
    in the way of rules.  (Page 2-2 of User Manual Vol. 1)
    
    I'm curious.  What is the technical reason for requiring the
    ( to be the next character after the >?
572.3have to read too far ahead to avoid ambiguityVAXUUM::KOHLBRENNERMon Aug 10 1987 12:1634
    There are some tags that have alternate forms:
    
    form 1:   <tagname>(probably a short argument)
    
    form 2:   <tagname>
                  probably a long argument
              <endtagname>               
    
    When the tag translator reads "<tagname>" it does not want
    to look more than one character ahead to decide which form
    it is dealing with.  (I'm not saying that it CAN'T, I'm saying
    that it does not WANT to -- primarily for efficiency's sake.
    
    Furthermore, if you look at form 2 in the above example, suppose
    the long argument is supposed to be surrounded by parentheses?
    How would the tag translator know whether the parentheses were
    PART OF the argument as opposed to be DELIMITERS of the argument?
    
    Example:
    
            <literal>
            (Here is the text that I want to be taken literally.)
            And I would like this to be taken literally, too.
            <endliteral>
    
    The tag translator won't know what to do with those parentheses
    until it encounters the <endliteral> tag.                
    SO the user would be forced to enter it as:
    
            <literal>
            ((Here is the text that I want to be taken literally.)
            And I would like this to be taken literally, too.)
    
    bill