Conference vaxuum::online_bookbuilding

    Ward,
    
    Send me a pointer to memex_developers_guide.sdml. (I assume that's
    a profile, so include pointers to the <element> files, too.) Has
    this book built before for online?
    
    Thanks,
    
    Mary
    
    PS. This note also belongs more in the ONLINE_BOOKBUILDING
    notes conference than it does here (cf. note 2776.*).

    
    Hi Ward,
    
    In 278.4, I get this error by renaming my destination.  Does that ring
    a bell?
    
    David
    

    .2> I get this error by renaming my destination.  Does that ring a
    .2> bell?

    I hoped that it was something as easy as that.  I am using /OUTPUT to
    put the formatted file into a special "listing" directory.  But I just
    tried building without that qualifier and the RUNAWAY bug remained.

    .1> Send me a pointer to memex_developers_guide.sdml.

    Thanks for offering to take a look.  The list is on its way off-line.

    .1> Has this book built before for online?

    The basic book as been evolving thru many months of book building.  I
    just added a few completely new sections, and the failure appeared.

    -- Ward

    Can you tell from the .tex file (line 300) whether it was one of
    your new sections that it bombed on? (Line 300  would be pretty
    close to the beginning of the book in a .tex file.)
    
    Thanks,
    
    Mary

    Ward,
    
    The problem is in the <head1> tag on line 68 of dg_memex_concepts.sdml.
    This is the old backslash-at-the-end-of-a-line problem that is
    documented under 'known problems' in 'Coding Documentation Source
    Files for the DECwindows Bookreader.'
    
    The tag is coded as follows:
    
    <head1>(The Application/<REFERENCE>(memex_package_name) Partnership\
    partnership_head)
    
    That backslash/carriage-return causes problems for online builds
    (this is a bug that is on the wishlist for fixing for DOCUMENT V2,
    since the above is a perfectly reasonable way to code things).
    
    Change the coding to the following and you'll be fine:
    
    <head1>(The Application/<REFERENCE>(memex_package_name) 
    Partnership\partnership_head)
    
    A nit: your 'profile', memex_developers_guide.sdml is actually a
    file of <include>s and not a true profile with <element>s. Had
    you used <element> tags, a .tex file would have been written out
    for each element and it would have been immediately obvious which
    file contained the runaway problem. With the <include>s, one big
    memex_developers_guide.tex file was produced and it was harder to
    isolate the error. As I said, a nit: you may have 700 irrefutable
    reasons for using the <include>s but it made it a bit harder for
    me to find your problem.
    
    Mary

    .5> This is the old backslash-at-the-end-of-a-line problem ...

    The offending line used to be OK ... until I replaced literal text with
    a <REFERENCE>.  Then the symbol name ran off the end of the line, so
    I split the line (forgetting about the old bug).

    Thanks for debugging my pilot error.

    .5> this is a bug that is on the wishlist for fixing for DOCUMENT V2

    While we're talking about wishes, it sure would be nice if Pass "n"
    (where n > 1) errors pointed to the offending source lines.  I realize
    that's not easy, but neither is the user's task of tracking down the
    problems.

    .5> A nit: your 'profile', memex_developers_guide.sdml is actually a
    .5> file of <include>s and not a true profile with <element>s. ... you
    .5> may have 700 irrefutable reasons for using the <include>s

    Actually, it's only 2 or 3, but at this point I don't remember what
    they are.  A long while ago we had problems with our profiles; changing
    them to simple includes corrected the problems.

    -- Ward

    Re .6: line numbers -- DOCUMENT does in fact point to the line number
    and that's how I found the problem: it was on line 300 of the .TEX
    file. (My problem with the profile was that I had to guess at how many
    of the <include>s to actually include to reproduce the error; I
    commented out most of the profile so as not to waste time processing
    the entire book, not to mention copying all the files in the first
    place.)  The tag trans also gives line numbers, but didn't here, this
    problem being a bug not a feature...:-)
    
    I doubt that it's possible for DOCUMENT to say 'the problem is on line
    300 of the .tex file and line 176 of the .sdml file.' What we try to
    do is catch all the user errors in tag translation and report the
    nature of the error and line number in the source file, stopping
    processing if the error is bad enough. In other words, we try to
    prevent users from ever getting TeX error messages. As you can see,
    it doesn't always work. But when it does happen, it generally indicates
    a DOCUMENT problem (as it did here) and you did exactly the right
    thing: you reported it.
    
    Mary

    Mary's right -- pass 1 errors do point to the source line in error.
    I'll bet that 99%+ of all errors get fixed as a result of these
    messages and you/we don't hear about them.

    It's just the tricky errors, and the avoidable DOCUMENT errors, that
    I'd like to be able to deal with better.  Internally, we have a couple
    of conferences to help us.  What do DOCUMENT customers do?

    I personally believe that the most useful feature in a new version of
    DOCUMENT would be to make it bulletproof.  Investing in better error
    recovery is one key aspect of this.

    -- Ward

    Yep, bulletproof software would be useful in *any* version of *any*
    software and I'm sure it's what we all try for. In fact, error
    recovery is not what it should be for the online processing and is
    one of the top wishlist items for DOCUMENT V2.0, when the online tools
    will be put in the hands of the users who, as you note, have fewer
    resources at hand to help bail them out of problems.
    
    Thanks, Ward.
    
    Mary