Conference tnpubs::nacleaf

From:	MTWAIN::CAHALAN      "Jack Cahalan, 223-2528, MLO21-2/T64, Corporate User Publications" 15-NOV-1988 10:25
To:	MACDONALD,CAHALAN     
Subj:	This is more a software review than a course report.  But I assume that is appropriate, since the only reason for the course was to find out if the software would be helpful

           DIGITAL                           INTEROFFICE MEMORANDUM

           TO: Paul MacDonald                DATE: November 15, 1988
                                             FROM: Jack Cahalan
                                             DEPT: CUP
                                             EXT:  2528
                                             LOC:  MLO21-2/T64




Report on the WPS-Plus Course, November 9-10, 1988:


I chose this course because I consider the text editors provided by CUP
the single biggest obstacle to the technical writer's productivity. 
WPS-Plus was the only candidate for an acceptable text processing tool
that I had not yet investigated.  

Unfortunately, WPS-Plus, as currently written, is no more acceptable than our
text editors are.  Perhaps future releases will address WPS-Plus's shortcomings.

Since my reason for taking the course was to find a tool that CUP could
use, what follows is a review of the main disadvantages of WPS-Plus as a
writer's tool, rather than a review of the course itself.

1.  WPS-Plus does not give you windows or buffers.  You cannot edit more
than one document at a time.  

2.  You can only copy whole documents into your current document; you
cannot select sections of a document for copying into your current
document.  You can, however, write a section of your current document to
another (whole) document.

3.  Any acceptable text processor should have true word wrapping at all
times.  WPS-Plus has true word wrapping while you are first entering text, 
but not when you are inserting text.  To force word wrapping after an
insert, you must use additional keystrokes that can leave the cursor at a
very inconvenient place.

4.  Any acceptable text processor should display the current page number,
line number, and cursor position at all times.  The present version of 
WPS-Plus does not do this, although the next version supposedly will.

5.  Continued searches and substitutions require more keystrokes than they 
should.

6.  Any acceptable text processor should give you random access to pages 
and/or lines, specified by number.  WPS-Plus gives you random access to
pages, but random access requires more keystrokes than it should.

DOCUMENT is the single biggest obstacle to our productivity.

To answer your last question first, at least 50 percent of my time goes into 
DOCUMENT-related activities rather than writing-related activities.  

Please excuse me if I go into excruciating detail on some of my complaints.  
Anything less than excruciating detail wouldn't do justice to the kinds of 
problems DOCUMENT causes.

Many of my specific problems might be alleviated if we could use DOCUMENT with a
good WPS system, so it might appear that my complaint is more with our editors 
than with DOCUMENT.  But really it amounts to the same thing.  If DOCUMENT would
be usable only with a good WPS system and we can't use it with such a system,
DOCUMENT isn't usable.  

<x>(DOCUMENT<xs>indexing<xs>difficulties with\begin)
<x>(Indexing<xs>difficulties with under DOCUMENT\begin)
<y>(Difficulties with indexing<xs>See Indexing; DOCUMENT)

For example, indexes are the weakest part of our otherwise helpful
documentation.  Our indexing software prevents us from producing good indexes.
The software is so cumbersome that it discourages the writer from including more
than the minimal number of entries and cross-references. 

The editors I use have no line numbers or automatic pagination; therefore it is 
often difficult to know where you are in a document.  I was recently trying to
improve an existing index by adding /begin and /end qualifiers where helpful.
How do I find out where it would be helpful?   Using FIND?  FIND does not tell
me where I am relative to the last found item: one screen away, 150 lines away?
Sometimes the range for /end is a subsection, sometimes an entire section.
Without page or line numbers, I had to do FINDs that distinguished between
<head1> and <headN>.  That forced me to delete my current FIND string, the
one I needed to locate the next occurrence of the index item. 

<x>(DOCUMENT<xs>indexing<xs>difficulties with\end)
<x>(Indexing<xs>difficulties with under DOCUMENT\end)

A few other random complaints:

The inconveniences resulting from not having  page or line numbers are not
confined to indexing.  The DOCUMENT error messages tell you what line the error
is on.  To find that line, you have to go to the top of the file, press GOLD
plus a number, and press LINE.  To find the next line, you must either do some
arithmetic or start from the top again.  If correcting the original error has
changed the line count, you have to keep track of the number of lines changed,
even though you have more important things to think about. 

DOCUMENT error messages do not wrap at column 80.  To read them, you must
go through contortions like setting the screen to an illegible 132 or doing 
line-by-line fills.  I could use the EDT SHL command, but then I couldn't 
use windows to display the error messages and the text at the same time.

Baselevel 7 made such improvements as replacing a string like "(odb)" with
"(open_double_brackets)".  On some editors, you can define keys to take care 
of these long strings, but the increased number of long strings increases the 
number of key defintions you have to remember.

You often have to nest long tags.  The resulting argments are often more 
than 80 characters.  Carriage returns allow you to display the whole argument, 
but for some tags, carriage returns are not ignored in printing.  Therefore, 
you have to go back and delete the carriage returns when you finish writing 
the argument.

When you try to build a document, the build stops at a predefined number of
errors.  After you correct those errors, you have to begin the build again to 
find the next set of errors.  Repeated builds just log errors that 
DOCUMENT could have reported the first time.

Conclusion:

Our tools are supposed to help us, not hinder us.  DOCUMENT is much too 
time consuming to be helpful.

Many of my specific problems might be alleviated if we could use DOCUMENT with a
good WPS system, so it might appear that my complaint is more with our editors 
than with DOCUMENT.  But really it amounts to the same thing.  If DOCUMENT would
be usable only with a good WPS system and we can't use it with such a system,
DOCUMENT isn't usable.  

>>> Have you looked at LSEdit?  I can't imagine using VAX Document without the
    Language sensitive editor?


The editors I use have no line numbers or automatic pagination; therefore it is 
often difficult to know where you are in a document.  I was recently trying to
improve an existing index by adding /begin and /end qualifiers where helpful.
How do I find out where it would be helpful?   Using FIND?  FIND does not tell
me where I am relative to the last found item: one screen away, 150 lines away?
Sometimes the range for /end is a subsection, sometimes an entire section.
Without page or line numbers, I had to do FINDs that distinguished between
<head1> and <headN>.  That forced me to delete my current FIND string, the
one I needed to locate the next occurrence of the index item. 

>>> VAX Document is a batch processor therefore you will not be able to get
    pagination until you have processed your source file.


The inconveniences resulting from not having  page or line numbers are not
confined to indexing.  The DOCUMENT error messages tell you what line the error
is on.  To find that line, you have to go to the top of the file, press GOLD
plus a number, and press LINE.  To find the next line, you must either do some
arithmetic or start from the top again.  If correcting the original error has
changed the line count, you have to keep track of the number of lines changed,
even though you have more important things to think about. 

>>> If you use LSE, you are able to debug right from the editor, with your .DIA
    file (the file with the errors in it) in one window and your source in 
    another window.  It's quite handy.  By doing a CTRL G, the editor will take 
    you to your error in the source file.  A CTRL F will get you back to your
    .DIA file (your error reporting file) and place the cursor on the next 
    error.  As common debugging methods, it's best to fix the first error and
    rerun the file.  This is all documented in one of the appendixes in the
    VAX Document User's Manual.  I believe it's the appendix on LSEDIT.


I believe in WYSIWYG systems over batch processors, but sometimes we don't have
the luxury of making that decision.  I would like to see some discussions on
DECwrite... How about Blaise and Eric?  It would be nice to see some comparisons
to Interleaf as we are familiar with it and we would we comparing two WYSIWYG
systems.

Bette Jean

re: .3

I use LSEdit!  I do not consider it even worth mentioning as a word processing 
system.  It's a bigger obstacle to a writer's productivity than DOCUMENT.

The problem with compiling and reviewing errors within LSE is that it doesn't 
catch all the errors the a regular build catches.  So you still have to do 
the regular build afterwards, then awkwardly go to the lines the new errors 
are on.  So this workaround winds up taking more time than just building the 
regular way.

Jack