Number: 1215

Date: 23-May-84 17':24':18

Submitter: Sannella.PA

Source: masinter.pa

Subject: Rewrite documentation of window system in manual

Lisp Version: 

Description: '
Date': 21 May 84 00':14 PST'
From': masinter.pa'
Subject': [dlevy.pa': Problems with INTERLISP documentation of windows, etc.]'
To': LISPSUPPORT'
cc': Burton'
'
please enter this as an AR (I don''t have AR.FORM loaded). Please note that I solicited this (I asked david to please send it in). Window/graphics, problem type': Documentation, impact': Moderate. Attn (?)'
'
     ----- Begin Forwarded Messages -----'
'
Date': 16 May 84 12':51 PDT'
From': dlevy.pa'
Subject': Problems with INTERLISP documentation of windows, etc.'
To': masinter'
cc': dlevy.pa'
'
As a former user of INTERLISP now learning to use INTERLISP-D, I''d like to register some criticism of the documentation on windows, etc. in the Interlisp Reference Manual (specifically sections 19.3 through 19,12).'
'
Overall, I found these sections very confusing.  After reading them over several times, trying to understand the relationship between bitmaps, display streams, and windows (and getting nowhere, I might add) I finally asked a knowledgable LISP hacker for help.  He kindly explained that HE didn''t understand all the intricacies himself, but you really didn''t need the detailed understanding the manual was trying to provide, since there were some fairly simple subsets of operations that one typically used.'
'
The manual sets you afloat in a sea of details (everything you might need to know and more) without giving any real guidance.  One might respond to this by saying':  Well, the manual isn''t a tutorial, it''s a source of reference -- but this would miss the point.  Even a reference manual should be CLEAR about the distinctions it makes, and the discussion of display streams and windows is hardly that.  (We''re told, for example, that a window is almost a kind of display stream, but it isn''t really.  What does that mean?  And how is the poor user to get a coherent and consistent picture of the relationship between the two kinds of objects?  One answer is simply to tell the user':  Look, if you really want to use windows, don''t worry about display streams.  This, more or less, is the advice I was given by the LISP hacker.)'
'
     ----- End Forwarded Messages -----'


Workaround: 

Test Case: 

Edit-By: 

Edit-Date: 

Attn: Burton, Sannella

Assigned To: 

In/By: 

Disposition: 

System: Windows and Graphics

Subsystem: Window System

Machine: 

Disk: 

Microcode Version: 

Memory Size: 

File Server: 

Server Software Version: 

Difficulty: Moderate

Frequency: Everytime

Impact: Moderate

Priority: Perhaps

Status: Open

Problem Type: Documentation

Source Files: