Conference vaxuum::document_ft

    Re first point,
    
    Are you sure your system is running bl07? The error you cite shows
    up when using that command line on bl06.
    
    kh

    I encountered the first problem a lot when BL07 was first installed
    on the TLE cluster.  The cure was to update the CLI tables on certain
    nodes that didn't seem to 'get the message' at installation time.

I would also like to make a couple of comments about DOC$CONVERT:
    
1)  This does not work:   DOC$CONVERT profile /SYMBOLS=my_sym_file.gnc/MAP

    But this does:  DOC$CONVERT profile /MAP/SYMBOLS=my_sym_file.gnc
    
    	Apparently, the parser expects a /SYMBOLS parameter to be the
    	last item on the command line.  In this case it thinks /MAP
    	is part of the symbols filename.  And this "feature" isn't
    	documented.

2)  It appears that the conversion program will only properly convert
    a maximum of 50 <BOOKREF> tags.  On number 51, I get the message:

    		 "Bookref table exceeded"

    and all subsequent <bookref> tags are left unconverted.  That feature
    is also undocumented.  Presumably, there are other internal tables
    that have maximum sizes which aren't mentioned anywhere.
        

Neither of these problems is earth-shattering, but both required me
to rename files and start the process over.  Given that VMS won't allow
me to use this renaming command:

	$ RENAME 3222*.GNC_6 *.GNC

renaming 20 files is a large pain.  Of course, in the release notes it says
to convert large manuals in several parts, but it doesn't say why.  Now I
know why.  In addition, the position-sensitivity of the DOC$CONVERT command
line (mentioned in .0) is both incorrectly documented and undocumented, in
two different cases.  It caused two writers at our site to lose a day and a
half trying to figure out what was going on. 

My point is that DOC$CONVERT is not well documented and it may be easier
for folks to convert their files when the conversion programmers are
in the next office, but it's a lot harder when you're a continent away.
Maybe there's no solution to this, but hopefully this note will save
others some headaches.

	-Helen Custer
	 DECwest Engineering
	 Seattle, WA

    Now I can't find in the Release Notes *where* it says to convert large
    manuals in several parts.  Perhaps I read that elsewhere. The Release
    Notes should mention this strategy, however, because large manuals have
    a tendency to produce a lot of conversion errors. 
    
    My first attempt at converting in "batches" failed because I used a
    <COMMENT>...<ENDCOMMENT> pair in the profile to "comment out" those
    elements that were to be converted in the second batch. However,
    DOC$CONVERT appears to ignore <COMMENT> tags in the profile. I guess
    that if you're converting a manual in sections, that you must delete
    the elements you do not want to convert from the profile. 
    
    	-hkc

    I take something else back:
    
    $ DOC$CONVERT profile /MAP/SYMBOLS=my_sym_file.gnc
    
    does work in the sense that no error messages are produced when the
    command is entered.  However, neither is a MAP file. And, in fact,
    the symbols file that you specify is not read and symbols you use
    throughout your document are not converted.
    
    What actually does work (yes, my manual *finally* processed 
    properly.....I think) is this:
    
    $ DOC$CONVERT profile /SYMBOLS=my_sym_file.gnc
    
    By trial and error, I discovered that you may not use the /MAP
    qualifier if you use the /SYMBOLS qualifier, because then neither
    are recognized.
    
    Now tell me, is this any way to write a DCL command?  Should normal
    VMS users be able to figure out all these qualifications on their
    own?  If that command can't be written more robustly, then the
    documentation certainly should be.  
    
    I'm happy with the result of this painful conversion and I think you've
    done an excellent job of writing a difficult piece of software.  The
    command line, however, is an exception and leaves *much* to be desired. 

    
    	-hkc

    I am having the same trouble as .0(2) and .3(2). Both have caused
    me to lose at least several hours worth of time (I kept reading
    and rereading the release notes, but to no avail). I'm glad to
    hear it's not me (or my files!).
    
    I also seem to be having trouble getting include files that are
    coded symbolically in my PROfile (<INCLUDES_FILE>(symbolic_name\
    actual_file_name.GNC). I have done what the release notes say
    about making a master .DLG file and executed @master_file.DLG,
    but I am still getting a list of all my include files (in the
    100s) at the end of the PRO.GNC_6LIS file in the form
    
    	BDATE1ignored -- doesn't have a GNC extension
    
    Finally, it took a while (and a bit of consultation with
    another experienced converter) for me to realize that using
    MAKESDF in the past requires a fair amount of file renaming
    before conversion (because the converter doesn't understand
    .LDF or .GDF files, and I include these in various forms
    without renaming them to .GNC files). Just in case anyone
    else has had this problem (it is documented, but only in the
    general sense that anything that is not a .GNC file is ignored).
    
    It would help an enormous amount if some supplementary release
    notes concerning workarounds to these problems could be posted
    here (I would help, but don't know what the workaround for the
    .DLG business is).
    
    Thanks, Barbara

    
    I will check on some of the basic problems with the converter, but
    can clarify one point right off. DOC$CONVERT doesn't have the same
    qualifiers as DOCUMENT. In fact, DOC$CONVERT only has one 'qualifier',
    /SYMBOLS. It's not a true DCL command, nor written as one. 
    
    patti
    

    You're right, Patti (as usual).  The /MAP qualifier problem resulted
    from my own misunderstanding regarding the DOC$CONVERT command.  Still,
    a little better command line error checking or more detailed
    documentation  would be extremely useful. We've struggled with this
    command for several days and experienced a lot of frustration with it. 
    
    Thanks.
    
    	-hkc
    

    p.s.  When I said "qualification," I didn't mean to say "qualifier."
    I meant that the command line works, but only with qualification
    (the qualifier is position-sensitive).

    Patti, I checked the .DLG business again this morning. The problem
    is with the T1.0 release notes, not the converter. It turns out that
    when you do what it says in Section 3.3.3, you do indeed get a
    master .DLG file, but each of the separate .DLGs that are 
    concatenated in that file ends with an EXIT statement. So
    only the first logical name in the master file is defined
    when the file is executed (execution stops when the first EXIT
    statement is reached).
    
    The answer is either to execute each separate .DLG file before
    running the converter, or take all the EXIT statements out of
    the concatenated file before executing it. Sorry I didn't think
    to check this yesterday. I could have sent in a more coherent
    note!
    
    I'm going to try the conversion again...think it will work
    just fine now (except for the limit on the booknames, which
    does have a workaround...change all your own bookname <DEFINE>
    tags to <DEFINE_BOOK_NAME> (sp?) using a global substitution
    instead of having the converter do it).   
    
    Barbara

    Re: .9
    
    In my files, I did hand-convert all bookname <DEFINE>s to
    <DEFINE_BOOK_NAME> tags, allowing the converter to then convert all
    remaining <DEFINE>s to <DEFINE_SYMBOL> tags.  The error I got wasn't
    that I defined too many book names (the allowed number of
    <DEFINE_BOOK_NAME> tags you can have appears to be very high), but that
    I had too many <BOOKREF> tags in my text. Each <BOOKREF> adds another
    entry to the table, and that table has only 50 slots. 
    
    The only workaround I found for this problem is to break the profile
    up into "batches", processing only a few chapters at a time.
    
    
    	-hkc

    Hi,
    
    I wrote the converter and apologize for the oversensitive
    nature of its "command line".  I agree that it should do a 
    better job of checking and will fix it up.
    
    re: <bookref> tags  
    
    I intended that the limit of 50 be for UNIQUE symbols for
    booknames.  Maybe there is a bug there - I'll look at it.
    
    re: documentation
    
    You make a very good point about documenting the limits.  There
    are other limits, which we should document.
    
    re: renaming files
    
    Renaming a bunch of files is painful.  Could you move your
    file to a directory before conversion and then 
    	
    	Rename *.gnc_6 *.gnc
    
    I was thinking about adding a /start_over qualifier but hoped
    it wouldn't be needed.  I sympathize with your problem and am
    sorry that the <bookref> limit caused you such trouble.
    
    re: comments
    
    The converter converts things in comments.  We thought about this
    and decided that it would be dangerous to leave any unconverted
    files or parts of files lying around.
    
    	Helen
    

    Thanks very much for the replies. In case it helps, this
    is the behavior I am getting from the converter in a
    fairly average-sized book, about 400 pages, with
    many references (I am converting using the PROfile method):
    
    	1. It translates my symbol file, showing that there are
           31 book name or string symbol definitions (appendix
    	   references, etc.) total.
    
    	2. It then processes the rest of my files, counting
    	   each <BOOKREF> tag it finds...even if it runs into
    	   duplicates. The 51st and all succeeding <BOOKREF> 
    	   tags get the error "Bookref table exceeded, etc.".
    
    	3. When it gets to the 'Resolving Definitions' part of
           the conversion, it gives me an error when it gets
    	   to the symbol file: "?Subscript out of range on line
    	   347 -- <DEFINE_SYMBOL>(vaxelnug\VAXELN Ada User's
    	   Manual". 
    
    	   This last message is quite odd because my symbol file
    	   does not have 347 lines (I think the line counter must be
    	   counting all the lines in the preceding file, the PROfile,
    	   because I know the PROfile has several hundred lines).
    
    	   It's also odd because the out-of-range symbol is the
    	   3rd symbol (happens to be a book name) in the 
           symbol definitions file.
    
    	4. When the converter is all done, it lists the recognized
    	   symbols, which include all 31 listed above, but the
    	   converted symbol file turns out to contains only 2 definitions
    	   (the first 2 in my symbol definitions file).
    
    Again, I think I can repair this myself by redoing the symbol
    definitions file by hand or by processing things in pieces, but 
    I thought I would send it along in case it helps with the "bug".
    
    Barbara