warsaw@cme.nist.gov (Barry A. Warsaw) (06/23/89)
I have just started using SunPHIGS, Sun's version of PHIGS, but the
documentation is very poor. They only include a "Beginner's Guide" which
has a brief overview of the PHIGS system, and a set of manual pages which
is great if you know what function you want to use but are unsure of the
syntax.
What they *don't* include is a guide for taking a novice through the
general concepts of how to get things done with PHIGS. For example, I
want an explanation of how to use name sets to get invisibility of
elements. I had to wade through the manpages for a week to get some vague
idea of how to do this.
Are there any good books on PHIGS out there? I've called one local
computer book store, but they've never heard of PHIGS. I'd appreciate any
titles, authors and publishers of books that you think are good. Please
email to me directly and I will post a summary. Thanks.
-Barry
P.S. Is there a PHIGS mailing list or newsgroup? I couldn't find the
newsgroup and the address I had for a PHIGS+ mailing list was quite
old and didn't seem to work.
NAME: Barry A. Warsaw USMAIL: National Institute of Standards
TELE: (301) 975-3460 and Technology (formerly NBS)
UUCP: {...}!uunet!cme-durer!warsaw Rm. B-124, Bldg. 220
ARPA: warsaw@cme.nist.gov Gaithersburg, MD 20899herzog@dogwalk.Sun.COM (Brian Herzog, Sun Microsystems, GPD) (06/23/89)
In article <WARSAW.89Jun22152002@rtg.cme.nist.gov> warsaw@cme.nist.gov (Barry A. Warsaw) writes: > >I have just started using SunPHIGS, Sun's version of PHIGS, but the >documentation is very poor. They only include a "Beginner's Guide" which >has a brief overview of the PHIGS system, and a set of manual pages which >is great if you know what function you want to use but are unsure of the >syntax. > >What they *don't* include is a guide for taking a novice through the >general concepts of how to get things done with PHIGS. For example, I >want an explanation of how to use name sets to get invisibility of >elements. I had to wade through the manpages for a week to get some vague >idea of how to do this. > >Are there any good books on PHIGS out there? I've called one local >computer book store, but they've never heard of PHIGS. I'd appreciate any >titles, authors and publishers of books that you think are good. Please >email to me directly and I will post a summary. Thanks. > >-Barry > >P.S. Is there a PHIGS mailing list or newsgroup? I couldn't find the >newsgroup and the address I had for a PHIGS+ mailing list was quite >old and didn't seem to work. > >NAME: Barry A. Warsaw USMAIL: National Institute of Standards >TELE: (301) 975-3460 and Technology (formerly NBS) >UUCP: {...}!uunet!cme-durer!warsaw Rm. B-124, Bldg. 220 >ARPA: warsaw@cme.nist.gov Gaithersburg, MD 20899
herzog@dogwalk.Sun.COM (Brian Herzog, Sun Microsystems, GPD) (06/23/89)
(sorry for the previous posting, which ate my response...) In article <WARSAW.89Jun22152002@rtg.cme.nist.gov> warsaw@cme.nist.gov (Barry A. Warsaw) writes: > >I have just started using SunPHIGS, Sun's version of PHIGS, but the >documentation is very poor. They only include a "Beginner's Guide" which >has a brief overview of the PHIGS system, and a set of manual pages which >is great if you know what function you want to use but are unsure of the >syntax. > Although I am not a member of the SunPHIGS team, I feel compelled to respond. The "Beginner's Guide" you mention (actually called "Getting Started with SunPHIGS"), which you imply is a token skimpy document, is, in fact 171 pages long, and includes extensive tutorial information on SunPHIGS and PHIGS in general, as well as a large amount of sample code. This document is often recommended (along with "Understanding PHIGS" by Template) in this newsgroup, by non-Sun employees, as among the best PHIGS introductory material available. >What they *don't* include is a guide for taking a novice through the >general concepts of how to get things done with PHIGS. For example, I >want an explanation of how to use name sets to get invisibility of >elements. I had to wade through the manpages for a week to get some vague >idea of how to do this. > It seems to me you want something (documentation customized to your level of expertise) for nothing. This is an extermely competitive market, and getting more so. You may not like the current industry "standards" of documentation, but the SunPHIGS documentation is as good or better than everything else out there in the PHIGS marketplace. Try reading the actual PHIGS standard sometime! Additional tutorial information would cost a great deal of money to produce, the cost of which would get passed on to the purchasers of the software. The people who don't need or want that text would then complain about the high cost of the software. When the day comes that the market demands that further tutorial text be included, Sun and Template and Apollo (et al) will have to deal with that; in the meantime, if you want further training, follow the current accepted marketplace practice and take a class. >NAME: Barry A. Warsaw USMAIL: National Institute of Standards >TELE: (301) 975-3460 and Technology (formerly NBS) >UUCP: {...}!uunet!cme-durer!warsaw Rm. B-124, Bldg. 220 >ARPA: warsaw@cme.nist.gov Gaithersburg, MD 20899 Brian Herzog herzog@sun.com Disclaimer: The above opinions are my own and do not necessarily represent those of Sun Microsystems, Inc.
warsaw@cme.nist.gov (Barry A. Warsaw) (06/27/89)
I feel that I need to respond to Brian's followup to my original
posting on the SunPHIGS documentation. I don't want to get into a
flame war here, as it is inappropriate for this newsgroup. I just
want to publicly clarify my original posting. Any future responses
should probably be carried on off the net.
I also want to take this opportunity to thank everyone who has
responded with helpful suggestions, references and offers of help.
I'll try to collate the information and post a summary for your
information.
Here is my response to Brian's reply. You can skip the rest of this
message if you aren't interested. One warning, though if you
continue. This is a high temperature zone. :-)
-Barry
======================================================================
Barry> I have just started using SunPHIGS, Sun's version of PHIGS, but
Barry> the documentation is very poor. They only include a "Beginner's
Barry> Guide" which has a brief overview of the PHIGS system, and a set
Barry> of manual pages which is great if you know what function you want
Barry> to use but are unsure of the syntax.
Brian> Although I am not a member of the SunPHIGS team, I feel compelled to
Brian> respond. The "Beginner's Guide" you mention (actually called "Getting
Brian> Started with SunPHIGS"), which you imply is a token skimpy document, is,
Brian> in fact 171 pages long, and includes extensive tutorial information on
Brian> SunPHIGS and PHIGS in general, as well as a large amount of sample code.
Brian> This document is often recommended (along with "Understanding PHIGS"
Brian> by Template) in this newsgroup, by non-Sun employees, as among the best
Brian> PHIGS introductory material available.
I'm sorry that my comments were taken to imply that the Getting
Started manual was a "skimpy" or "token" document. It is not.
However, your statement is a little bit misleading. Of the 171 pages
in this document, pages 61 - 164 are listings of the programs included
in the examples and tutorials directories that come with the
distribution. Now, why would I need these pages? Well, some reasons
would be (1) to save me the trouble of printing them out myself, (2)
to impart extra wisdom on the code by providing informative comments
outside the body of the code, (3) to provide listings to those who
don't buy the whole distribution, or (4) to provide listings for those
people who don't have a printer or reasonable editing environment for
viewing these programs. Reasons 1, 3 and 4 are noble certainly, but
reason 2 would be the most useful for the user of this PHIGS
implementation. This opportunity was not seized though; with each
listing there is only a one or 2 line introductory phrase, such as:
figscanval.f
Demonstrates the *Valuator* window using a *Sun Canvas* workstation.
One can learn a lot from looking at sample code that works, but it
would have been more helpful if some more detailed insight was
provided with the code. Of course there are comments in the code but
we certainly could have benefitted from a more detailed analysis.
Excluding the 100+ pages of listings this leaves about 70 pages for
the coverage of all other PHIGS concepts, some of which are
incomplete, for example Visibility and Name Sets. On pg 21, Section
2.7. Creating Structures, there is a discriptions of the types of
structure elements which can be used to build a structure. The sixth
bullet says:
"*Name Sets* - control visibility, highlighting and detectability of
groups of primites"
Now that I know visibility can be controlled, where do I go to learn
more about the concepts of visibility control and name sets? There is
no further mention of either visibility or name sets in this guide (no
global index either, which would have been an easy [?] addition).
This is a clear ommision IMHO. If this is an example of some of "the
best PHIGS introductory material available", then it is more a comment
on the (lack of) availability of complete PHIGS documentation, than it
is on the superior quality of this particular guide. Again, I'm not
trying to imply that the guide is completely useless, but it is
clearly incomplete and inadequate.
Sure, all the information is available in the manpages, but the layout
of the manpages is based on an alphabetic ordering of the PHIGS
function names. Try weeding your way through the name set related
functions for one day and you'll see where my frustration comes from.
You've got references all through the manpages so you'll do a *lot* of
page flipping. You've got to guess at where the name set related
functions are, since looking up "Name Sets" in the index leads no
where (there aren't even any listings under "N" in the index!).
Fortunately the page called "Add Names to Set" is the first manpage
after the intro page so luck is on your side. Now try to find all the
other concepts and functions that Name Sets relate to. See what I
mean?
Barry> What they *don't* include is a guide for taking a novice through the
Barry> general concepts of how to get things done with PHIGS. For example, I
Barry> want an explanation of how to use name sets to get invisibility of
Barry> elements. I had to wade through the manpages for a week to get some vague
Barry> idea of how to do this.
Brian> It seems to me you want something (documentation customized to your level
Brian> of expertise) for nothing. This is an extermely competitive market, and
Brian> getting more so. You may not like the current industry "standards" of
Brian> documentation, but the SunPHIGS documentation is as good or better than
Brian> everything else out there in the PHIGS marketplace. Try reading the actual
Brian> PHIGS standard sometime!
What I want is something more for the $2000+ that I was charged for
SunPHIGS 1.0! I don't think it is unjustified to want a good product
for my money. You're right when you say this is a competitive market,
but inexpensive price alone will not win customers. Superior product
(software *and* documentation, service too) for the money will drive
the market. Sun better learn this.
And I don't buy this "current industry standard of documentation"
stuff because I am comparing the SunPHIGS documentation against
something like the SunView documentation, which comes *as part of the
general SunOS distribution* (ie, bundled software, vs SunPHIGS
unbundled distribution) and contains exactly the type of documentation
that is lacking in the SunPHIGS doc set. To be fair, I think SunView
could use a manual page set like what SunPHIGS has, but certainly
SunPHIGS could use a manual like the SunView Programmer's Guide and
System Programmer's guide, which explain the details of SunView in a
clear and complete manner, concept by concept. SunCGI and SunCore both
have this type of manual and are also bundled software (at least up to
SunOS 4.0.3). Does software have to be bundled to be well documented?
Both types of manuals (Beginner's guides and concept guides) are
necessary, in my opinion. Except for some *very obscure* things, I
have had little or no trouble doing what I've wanted with SunView,
SunCore or SunCGI by just reading the supplied manuals. Is it too
much to ask that Sun maintain a consistent "standard" for
documentation within their own company? And again, your statement
about the SunPHIGS documentation being "as good or better than
everything else out there in the PHIGS marketplace" is more a comment
on the state of the PHIGS marketplace then the quality of these
guides. Its a cop-out too.
You tell me to read the PHIGS standard sometime. Fine, but none of
Sun's documents give any details of how to obtain the standards.
Maybe they could have included the standard with the documentation
set, or if that wasn't legal, they could have said, "For more
information, refer to ANSI standard blah-blah, available from
such-and-such address", but the manuals don't even do that!
Brian> Additional tutorial information would cost a great deal of money to
Brian> produce, the cost of which would get passed on to the purchasers of the
Brian> software. The people who don't need or want that text would then complain
Brian> about the high cost of the software.
Brian> When the day comes that the market demands that further tutorial text be
Brian> included, Sun and Template and Apollo (et al) will have to deal with that;
Brian> in the meantime, if you want further training, follow the current accepted
Brian> marketplace practice and take a class.
I'm not trying to denegrate the SunPHIGS software, I'm sure in the
scheme of things its very good. But good software without adequate
documentation is not useful. Let me say that *this* part of the
market (meaning me) is demanding good documentation and while I've
been very pleased with Sun software in the past, I think in the future
I will ask to see the documentation before I purchase the software.
I, for one, feel that this is an important consideration when buying
software.
I'm sorry if you were personally offended by my remarks, but I stand
by my claims. I understand the opinions you stated are your own and
not Sun's but Sun built their reputation on listening to what their
customers wanted and providing that. Of late, they seem to have been
losing sight of this important ingredient and not just with SunPHIGS
but with other Sun products as well. If this trend continues Sun may
find their influence in the marketplace diminishing. I for one hope
they do listen to us.
Brian> Brian Herzog
Brian> herzog@sun.com
Brian> Disclaimer: The above opinions are my own and do not necessarily
Brian> represent those of Sun Microsystems, Inc.
NAME: Barry A. Warsaw USMAIL: National Institute of Standards
TELE: (301) 975-3460 and Technology (formerly NBS)
UUCP: {...}!uunet!cme-durer!warsaw Rm. B-124, Bldg. 220
ARPA: warsaw@cme.nist.gov Gaithersburg, MD 20899
This are my opinions alone and do not represent those of the U.S.
Goverment or NIST in any way.tbg@apollo.COM (Tom Gross) (06/28/89)
>I have just started using SunPHIGS, Sun's version of PHIGS, but the >documentation is very poor. They only include a "Beginner's Guide" which >has a brief overview of the PHIGS system, and a set of manual pages which >is great if you know what function you want to use but are unsure of the >syntax. I've seen the SunPHIGS documentation briefly and thought it was excellent, but I was reading it because I'm curious about a competitor's implementation, not in order to learn PHIGS. At Apollo we hear good things about our PHIGS documentation; I've recommended it before in this newsgroup. In particular I think our "programming guide" is a good, general introduction to PHIGS: Programming with Domain/PHIGS 275 pages part number 009701-A00 It costs $35 and can be ordered by calling 1-800-225-5290. (There is also a 600 page "Call Reference" available.) >For example, I>want an explanation of how to use name sets to get invisibility of >elements. I had to wade through the manpages for a week to get some vague >idea of how to do this. In "Programming with Domain/PHIGS", for example, there is a six page section called "Using Name Sets to Control Visibility and Highlighting" which includes a sample program. The sample program is included on the tape in Fortran, C, and Pascal when you buy the Domain/PHIGS development kit. -Tom Gross tbg@apollo.com
crum@usc.edu (Gary L. Crum) (06/29/89)
In article <441a51f1.1b329@apollo.COM> tbg@apollo.COM (Tom Gross) writes: >At Apollo we hear good things about our PHIGS documentation; I've recommended >it before in this newsgroup. In particular I think our "programming guide" >is a good, general introduction to PHIGS: > Programming with Domain/PHIGS> > 275 pages > part number 009701-A00 >It costs $35 and can be ordered by calling 1-800-225-5290. >(There is also a 600 page "Call Reference" available.) The programming guide (document 9701) costs $50, according to the "Instant Apollo" operator I spoke with today. Gary