Conference vaxuum::document_ft

         Ward,
         
         Although I wasn't around when the origional Document command
         line was designed I don't forsee any changes in it for the
         future.   The two paramters DESIGN and DESTINATION are
         actually references into user customizable data files, namely
         DOC$DESIGNS.DAT and DOC$DESTINATIONS.DAT.   Document allows
         users to change everything from the tag defintions, to
         the tex macros, to the font definitions and even allows
         them to make thier own DVI device converter.  It is entirely
         possible that a user site may use document in a fashion
         entirely foreign to the way we expect them to use it.
         
         The Destination data is ALWAYS required when you run
         document.  I see no reason why we should make the user type
         the extra qualifier characters to denote /DESTINATION since
         they will always (except in the case where there is a symbol
         defined) have to do so. We cannot default this information
         since any given installation may choose any keyword they wish
         to refer to any given destination(possibly unsupported by DEC).
         
         The Design data is required when you run either the Tag
         Translator or the Text Formatter.  This too cannot default
         for the same reason as above.  The Document command line
         code does not read the SDML file, therefore doctypes
         specified in the SDML file cannot be found out before
         the Design data file is parsed by the command line code.
         
         Now you could argue that we could supply logical names
         to default these parameters.  Well, in the past Document
         has been overrun with logical names, and slowly we are
         phasing most of them out.   A decision to add logical
         names will take at least a couple meetings.
         
         I see your point of view where you don't want any extra
         command procs laying around when you don't need them.
         But, most of the writers I know use Document with several
         different designs and destinations daily so making these
         parameters into qualifiers would just make them have to
         type more needless characters.
         
         But I will put your suggestion on the list of things to
         discuss and maybe we can compromise and come up with a
         solution.
         
         By the way CMS requires three parameters for several of
         its subcommands.  And many DCL commands and layered products
         require at least two or more paramters.  So three required
         parameters is not unprecidented in DCL.
         
         Chris
         

    Not meaning to one plus the original suggestion, but a mechanism
    similar to LSEDIT's ability to remember the last file edited and
    last line position would be great.  This would also simplify the
    COMPILE command of LSEDIT in that the user can just issue a COMPILE
    command for simple documents as opposed to COMPILE $ DESIGN DESTINATION
    as is currently required.  Lastly using a mechanism similar to the
    one LSEDIT uses, to remember the last FILE, DESIGN, and DESTINATION,
    could be done in such a way as that the user doesn't even know about
    the logical names (which as I recall was part of DOCUMENT logical
    name history problem, too many logicals for the user to have to
    muck with.)
    
    -tl

    While we're on the subject:
    
    It may be true that a given .SDML file can be compiled with more
    that one DESIGN.  However, I have to believe that this is the
    exception, not the rule.  Most SDML are always processed with the
    same DESIGN type.  My memos are processed MEMO, and my specs are
    processed REPORT, and never, ever vice-versa.
    
    I'm more than willing to include a <DOCTYPE> tag in each of my files.
    I'd be much happier if the doctype weren't a required parameter
    on the command line.  If the doctype is omitted from the command
    line, DOCUMENT should read the first line of the file; if there's
    no <DOCTYPE>, then it can issue an error (or default to some particular
    doctype).
    
       Gary

    re .3 
    I totally agree. I always use the same DESIGN with a given file.
    

RE: the <doctype> tag

There were technical reasons for our dropping the use of the <doctype> tag,
but I'm not sure at this point (the system has evolved considerably) how many
of those are still valid. So...we'll add "look into resurrection of the 
<doctype> tag" to the wishlist.

--Brian

    Re: .2 and remembering parameters...
    
    I've written some COM file code to do just that - please see the
    COM file I posted in this conference some time ago.
    
    BobW

    We may have to do major revisions to the tag translator in order
    to permit the doctype tag to select the doctype.  The doctype
    selects tag definitions, which get loaded before the user's
    source file gets read.  The suggestion says to have two ways
    to work: 
    
      1. load tag definitions based on the doctype from command line,
         then read the source file (and I presume ignore any <doctype>
         tag that might be there ??? give warning if not the same ???)
    
      2. ignore the missing doctype on the command line, read the source 
         file until we find a tag.  (what should we do with text that
         we find in front of this tag???)  Look at the tag.  If it is 
         <doctype>, then see if its argument is a legal doctype and if
         so, do all the same checking that was done by the DOCUMENT
         verb code (possible Fatal error message here) and then load
         the appropriate tag definitions and proceed.  (Are <comment>
         tags acceptable in front of the <doctype> tag???)
    
    I would hate to see that kind of scrambling of existing functionality.
    
    Rather, I would like to see it happening "in front" of DOCUMENT,
    which is what happens when you define your own set of commands,
    or specify your own COM file.
    
    We are talking about a "feature" that is entirely for ease of use
    (to avoid typing a few more characters on the command line).  But
    if we make it a standard part of DOCUMENT, it becomes something
    that each NEW user has to understand and make a decision about
    before they can begin to use the product.  The product is bigger,
    has two ways of doing the same thing, and the learning curve is
    steeper.
    
    bill

    .7>  We may have to do major revisions to the tag translator in order
    .7>  to permit the doctype tag to select the doctype.

    Care should be taken whenever possible to keep arbitrary implementation
    considerations (e.g., when to load tag definitions) from being cast
    into user interface "features".

    I expect that if this <DOCTYPE> discussion had occurred before DOCUMENT
    Phase 2 (implementation) that it would have been relatively easy to
    delay the loading of tag definitions until it was clear which doctype
    to use.

    Changing the current implementation to have <DOCTYPE> be more than a
    <COMMENT> will probably be non-trivial.  But that's what V1.2 and V2.0
    are for -- making the product better.

    .7>  We are talking about a "feature" that is entirely for ease of use
    .7>  (to avoid typing a few more characters on the command line).

    There has been discussion this and other topics about the difficulty of
    changing document types once a document has been written.  While it is
    possible to create documents that properly format with a variety of
    document types, that's a task akin to writing transportable code.

    Real-life example:

    I recently had to runoff a document created by a project member who was
    on vacation.  Because I had a paper copy of an earlier draft which was
    in two column format and because I've been using REPORT.TWOCOL for most
    of my current documents, I simply used REPORT.TWOCOL (because I had to
    specify something) without giving it much thought.

    When I got my LN03 output, it looked fine ... except for the last page.
    Instead of a bibliography, I got one large paragraph of gibberish
    because bibliography tags are not supported by REPORT.TWOCOL.

    I then took a look at the source file.  The first line read:

	<DOCTYPE>(ARTICLE)

    At least that told me what I needed for my second formatting run.

    -- Ward

    Before General became Report, it seemed a lot of sense to have default
    qualifiers such as /DOCTYPE=GENERAL/DESTINATION=LN03. Multiple
    parameters is cumbersome. We get used to it and thank goodness for
    command recall. Changing the parameters to qualifiers would remove
    the positional restrictions, making it easier to build symbols to
    handle frequently typed lines.
    
    Re-activiating <doctype> inside the file seems like a bad idea.
    An ealier note mentioned that processing one file under more than
    one docytpe is the exception; I would differ with that. I've been
    using the same source file to produce three and four styles of output:
    books, cards, help files. Sure it's only one more tag to hop over,
    but trying to produce a help file from a file that contains a specific
    <doctype>(s.r) would confuse the user more than it would simplify
    the process. 
    
    Let's leave the doctype on the command line but let's also make
    it easier for users to deal with frequently used command strings. 

    re: .9 Agreed!
    
    Because certain tags aren't available in some doctypes that it makes
    sense to have them in, is cause to push for making the tags either
    global or supported in more doctypes, not for hard coding doctypes
    into the files.  I disagree that writing documents to be produced
    by multiple doctypes is like writing transportable code.  If that
    really is the case, then I think DOCUMENT has missed a much desired
    goal.
    
    As far as educating the users, having DOCUMENT remember the last
    document, doctype, and destination seems like it can't possibly
    be difficult to learn.  If the user is using LSEDIT (which I would
    hope they are) then it would seem natural to type:

    	$ LSEDIT
    	$ DOCUMENT
    
    
    The alternative of making the doctype and destination qualifiers
    or allowing either qualifiers or positional elements makes it 
    possible to use DCL symbols to set defaults.  Creating a command
    procedure to handle this stuff is possible, although not a trivial
    effort for a non-sophisticated VMS user, especially for one that
    will handle the LSEDIT COMPILE command.
    
    -tl
    
    PS  If you want to communicate to other writers what doctype you
        intended your document to be processed with, why not <COMMENT> it?
	Seems like the idea of having a module header in your document
    	ala XLSE's support of SDML (or is XDOCUMENT, whatever) is a
    	better solution.

    Parameter defaulting would be a boon to some, it's true, but I suggest
    that when it's bad, it's horrid.
    
    LSE is interactive.  It tells you right away what default it took,
    by displaying the filename before it does anything else.  VAX
    DOCUMENT, on the other hand, is basically batch-oriented, and it
    creates and deletes files and prints output without stopping to
    ask for your further direction.  
    
    When the user forgets what the last run was, or somebody else drops
    by to show you how to run something, and VAX DOCUMENT then assumes
    different defaults than you expected, a lot of things can happen:
    
    1)	VAX DOCUMENT can process and print the wrong files, thus wasting
    	time, computer resources and paper.
    
    2)	Upon successful completion of processing VAX DOCUMENT will clean
    	up intermediate files.  This may delete an intermediate file
    	you wanted to save.
    
    3)	You may produce a document in a style similar to that intended,
    	not realize the error, and circulate copies that may be lacking
    	important legal statements or disclaimers that are built into
    	your intended doctype.
    
    4)	You may default to a /print destination when the one you wanted
    	was /noprint, and wind up printing sensitive documents on a
    	public printer.
    
    In short, features that work for the convenience of some users may
    cause serious resource and security problems for others.
    
    --Mark                     

    Most of Mark's comments in .11 sound to me like justification for
    (1) including the <DOCTYPE> tag in documents that rely on specific
    design features and (2) having DOCUMENT do something intelligent with
    that tag.

    -- Ward

    
    This issue has plagued us since Day 1. In fact, in Day 1, <DOCTYPE>
    was the only way to specify the document type/design. I won't go
    into the reasons we changed that, it involved performance improvements
    and wishes for flexibility. (You wouldn't find it hard to believe,
    would you, that as many people asked THEN for the type to be specified
    on the command line as are NOW asking for it in the file.)
    
    I agree that 3 parameters is a bit much; what I dislike is having
    to specify the doctype when only running the device converter. We
    do need to look at ways to make the command more flexible.
    
    patti
    

    A few thoughts:
    
    	1. If you will use a <DOCTYPE> tag, allow it only in the profile.
    	   Changing the <DOCTYPE> tag argument in 100 source files is
           pain. Will you also then require a <DESTINATION> tag in the
           profile also?
    
    	2. What about the /LIST qualifier and .LIS file? As it currently
    	   works, if you *use* the /LIST qualifier you see the doctype
    	   used. the DOCUMENT command also prompts you for the file,
    	   design, and destination if you just enter $ DOC
    
    	3. If you want to make it easy, just define a symbol:
    
    		MY_DOC == "DOCU/NOwhatever file.sdml design device"
    
    	   And then type MY_DOC
    
	Mike    

re:

> < Note 657.14 by VAXUUM::ETZEL "Mike" >
>                  -< Use a Profile or a DCL Symbol Definition >-

>    	1. If you will use a <DOCTYPE> tag, allow it only in the profile.
 
I would prefer to see <DOCTYPE> allowable in BOTH profiles and plaintext
files, with some reasonable order of precedence.  My use for ithad been
to imbed a memo in a functional spec so that obtaining the spec garanteed
that the memo came with it.

BobW