Conference vaxuum::document_ft

    Do others want to see this in some other format?
    
    It's on the wishlist.

    I think this is a good idea. But I don;t think it should be part
    of the output. Shouldn't this information go in the listing file?
    (Or did I misunderstand the original note...)
    
    --Andrew

    Another vote to generate readable CRF output.  [I like the table
    style shown in the base note.]

    Writers can use this output to check cross references.  This is
    especially useful when one writer is taking over the source files
    from another writer and is unfamiliar with symbol names and what
    structures the names apply to.

    Yes, this would be a real boon.
    

    Mason convinced me six months ago that it was a good idea,
    so it is at the top of the wishlist.  I'm interested in
    comments like where it goes (back of output/listing file/
    another output file,etc) and what people want to see in it
    (as in .0, or other?) and how you see it being used.
    
    For example, SOMEONE will want it sorted on the symbol, someone
    will want tables that don't have symbols included, others will
    want those items left out.  SOMEONE will want to reorder the
    columns.
    
    If we are to be true blue DECcies, we'll want to provide all of
    those options and more.  So maybe we should write a separate 
    utility that gives you a fancy command line with a dozen qualifiers
    for controlling everything.  That way, everyone gets it "their way"
    and we don't take processing time to produce it on every run for
    some poor writer who could care less.
    
    WOuld someone like to spec such a utility?

    Why don't you just organize it however you want, then we'll feel
    free to complain if we don't like what you've done....  :-)
    
    	-hkc

    Gee, I didn't think that getting a spec out of you ahead of time
    was going to restrict anyone from complaining!  Have you ever
    known that to work like that?
    
    Getting a spec out of you ahead of time just makes me feel smug
    when you DO complain!   ;-)       -  bill
    

    One of the requirements on PDS is to provide traceability between
    source code and documentation.  We would like to see this done by
    having DOCUMENT produce SCA information for the user's symbol
    definitions.  (SCA is, among other things, a successor to CREF.)
    
    I believe that DOCUMENT can also best satisfy the request in .0 by producing
    SCA information.  This will provide the ability to produce reports
    such as have been suggested (at least in the SCA V2 time frame,
    when we expect to have better reporting facilties).  Furthermore,
    it will have the added benefit of interactive cross-reference browsing
    in LSE.  For example, you could point at a symbol reference in one
    file, and have LSE take you to the line where the symbol is defined
    in another file.
    
       Gary

    We have been talking to the PDS people and will talk more once
    we get version 1 out the door.  The CRF will probably evolve or
    get converted into SCA.
    
    As I understand it, the goal is to be able to write requirements,
    specifications and design documents (in SDML) and to imbed symbols
    in them that identify important entities, and to be able to look
    at and report on this process by tying the entities in one place
    together with entities in the other place, so a design element
    can be tied to specification element(s) and those to requirement(s).
    
    Then, as actual coding begins, the design document can begin to
    have Pascal, or ADA, or C, or whatever coding added to it and the
    compilers are smart enough to overlook the SDML as comments and to
    compile the programming language, still feeding the same SCA data
    base, so that eventually, the code can be tied back to all that
    has come before it.
    
    bill
    

    A .CRF file dump would be very handy.  Another vote!
    
    Somewhat on the same subject, how about making missing references
    a less severe error than "warning".  I'm doing a chapter now that
    is a general overview of the rest of the book, and it refers to
    *everything*.  When I try to run it through DOCUMENT, I get more
    than 30 warnings and the tag processor stops.
    
    (Yes, I know, I can create "dummy" files with just the section names
    in them, and do a book build to create the .CRF file, then build
    the chapter I'm interested in using /something-or-other to specify
    the name of the .CRF file, and all that, but it would be a heck
    of a lot easier if you just made missing <REFERENCE> symbols totally
    ignorable.)
    

    re: .2
    A dump as the final page of output regardless of destination 
    device would be preferable to printing the file or book on one device
    and then printing a listing file on a line printer. It think it would save
    time.

    I would accept /CREF=cref-file-spec as a qualifier to the DOCUMENT
    command, in the same vein as linker MAPs and compiler LISTings.
    
    I vote for the feature too.
    
    thanks...Jack

    I don't think we would ever make an unresolved <reference> go
    by without at least a Warning level error.  The first person that
    sent a book to the printer with "<reference>(foobar)" in it
    would scream so loud Ken Olsen would hear it.
    
    There is probably someone out there who would like that particular
    message raised to Error severity level, under the argument that
    "no one wants to look at the printed output if it has unresolved
    references in it."

    As to the "automaticness" (wow!) of the dump... the CRF listing
    should be an option, however it is implemented. I certainly don't
    want all the extra paper every time I print a test file.
    
    Joe

    Another vote in favor of the CRF listing, and I second the notion
    of making the "listing" feature responsive to a command-line qualifier
    in the manner of a compiler.

    
      RE: .9
    
    Excellent!  Would you mind providing a pointer to SCA (what does
    it stand for/ where is documentation) and the PDS people?  We could
    use this kind of stuff.
    In fact, I have a project going (in lisp) in which the doc strings
    are structured so I can generate help and reference manual stuff
    from them.  This seems to fit right in, and may make my own garbage
    obsolete.
    
      RE: .5
    
    How 'bout an expert system?
    
    Dan Theriault, Knowledge Engineer :-)
    Artificial Intelligence Applications Group

    Re: .16:
    
    SCA stands for Source Code Analyzer.  Susan Snow and I are the writers
    for LSE/SCA/PDS.  By way of brief introduction to SCA, there is
    a template for LSE and SCA located at:
    

    CLT::SYS$UTILROOT:[PUBLIC.DOC_STRATEGY.TEMPLATES]LANG_VMS_TOOLS_LSESCA.GNC
    
    This template is meant for insertion as an appendix to language
    manuals, but should satisfy your curiosity.  Note that tags are
    for BL6 of DOCUMENT; it you desire the template with BL7 tags, send
    mail to me.
    
    The lead developers for these products are all on the TLE cluster.
    Mark Arsenault and Dave Moore - SCA
    Tina Cleaveland - PDS

    
      RE: .17
    
    Thanks, Neil!  I'll read it immediately.
    
    Dan