( ESNUG 359 Item 2 ) --------------------------------------------- [9/13/00]
From: jdl@user2.teleport.com (Jay Lessert)
Subject: User Reactions To Cadence's New "cdsdoc" (OpenBook Replacement)
Let me preface this by saying that it *is* possible that I'm the only
Cadence customer in the world that actually likes OpenBook. :-)
But I've found OpenBook to be far and away superior to any on-line
documentation I've used from Mentor, Avant! or Synopsys.
I just loaded LDV 3.1 (I'm currently running IC 4.4.3/4.4.5 and LDV 3.0
in production), and was surprised to find OpenBook gone, replaced by an
HTML-based thing called cdsdoc. They fire up an http server (from
Verity, Inc., apparently) on localhost port 9000, attempt to hijack any
web browser you already running, and away you go.
I've no quarrel with the document *content* (which is largely unchanged,
as you would expect). But I've run into the following miscues, omissions
and differences compared to OpenBook. I'm not happy.
1) We fire up an http server running as the user on port 9000. I know
nothing about Verity Inc., but if I was in a security-conscious
environment, I would *never* do that with (e.g.) Apache; it's just
asking for trouble.
2) We hijack the existing Netscape browser window if it exists. Bad
idea. Guess what? I had that window up for a *reason*, and I didn't
want it to disappear without warning.
3) cdsdoc is useless unless we have JavaScript enabled on the
browser. Blank pages. Apparently no one at Cadence is aware of
the vast array of JavaScript security problems embodied in modern
browsers. This is really very serious.
Worse, there is no attempt to warn of this, either in the HTML, or
in the documentation.
4) While the content of documents (e.g., Verilog-XL reference manual) is
the same, the formatting is no where near as good as OpenBook; this
is to be expected with HTML, of course, and the formatting is not
bad, considering. But a loss nonetheless.
5) The search window is replaced when I say "Go" (replaced by the
search output). This makes iterated, increasingly refined searches
much more painful. Unforgiveably, when I hit "Back" to return to
the search page, there is no history. Hmmm, no, I see. You only
get history with cookies enabled, another security problem, and
no attempt to warn the user.
Even with cookies enabled, the history is only for the "current"
search, nothing like OpenBook's history list.
6) The documents I've looked at so far have no hot-button for Index,
so I have to go to Contents, *then* Index. This should be pretty
trivial to fix, of course.
The Verilog-XL Reference Index takes 5 seconds to load every single
time I go to it (Ultra30/300). This appears to be Netscape rendering
time, I guess. OpenBook is instant once the document is loaded.
I think I understand the motivation behind the change (Adobe declines
to port Frameviewer to Linux, right?), and if I only compare cdsdoc to
Mentor & Avant!'s offerings, it still whips 'em pretty good.
But I'm gonna cuss every minute I spend over the next two-three years
getting cdsdoc up to where it needs to be. C'est la vie, huh?
- Jay Lessert Portland, Oregon
---- ---- ---- ---- ---- ---- ----
> Let me preface this by saying that it *is* possible that I'm the only
> Cadence customer in the world that actually likes OpenBook. :-)
>
> But I've found OpenBook to be far and away superior to any on-line
> documentation I've used from Mentor, Avant! or Synopsys. ...
>
> - Jay Lessert Portland, Oregon
From: jeffb@el.nec.com (Jeff Buckles)
You're referring *only* to the Cadence doc infrastructure, right? Their
doc tools, formatting and layout, not the content? I hope?
At risk of starting a "my docs were worse than your docs" war, I must say
that the only documentation *content* that I found less useful than the
Cadence doc was the old Valid documentation. Of course nothing could beat
the ASIC vendor's doc that explained an "Item Error" message by "There is
an error in the item".
Here's an example: The CTGEN documentation uses the expression
"rise_fall_min_max" in the syntax description for some commands. One could
reasonably expect to find the definition of "rise_fall_min_max" by going to
section "R" in the index. To quote a co-worker "You could think that. But
you'd be wrong."
It has been this way *any* time I try to find useful information in
Cadence's OpenBook, among physical verification, physical design, timing,
and P&R tool docs. Only the Verilog docs come close to having a useful
index.
So, thanks for raising the topic, thereby giving me a chance to vent this
long-suppressed rant. Now I'll sit back and start watching the flames fly.
Oh, regarding the HTML docs, HLD seems to have gotten it pretty close to
"right". They still "hijack" your browser ( -remote OpenURL() ) but they
reference a static hierarchy of html files that (IIRC) do not use
javascript. Too bad Cadence didn't stick with this....
- Jeff Buckles
NEC Electronics Inc
Portland ASIC Design Center
---- ---- ---- ---- ---- ---- ----
> You're referring *only* to the doc infrastructure, right? The doc tools,
> formatting and layout, not the content? I hope?
From: jdl@user2.teleport.com (Jay Lessert)
Hmmmm, nope. I'm talking "percentage of time I find what I need in the
docs, and how long it takes me to find it".
> Here's an example: The CTGEN documentation uses the expression
> "rise_fall_min_max" in the syntax description for some commands. One
> could reasonably expect to find the definition of "rise_fall_min_max" by
> going to section "R" in the index. To quote a co-worker "You could think
> that. But you'd be wrong."
Use the force... :-) While it's unfortunate the some of the indices
suck, I just did a full search for "rise_fall_min_max", and hit the
BNF for rise_fall_min_max in the GCF reference manual:
rise_fall_min_max
::= NUMBER
||= NUMBER NUMBER
||= NUMBER NUMBER NUMBER NUMBER
Not that this is terribly exciting...
- Jay Lessert Portland, Oregon
---- ---- ---- ---- ---- ---- ----
From: Barbara Heninger <barbh@cadence.com>
Jay,
Thanks for your comments about using the new web-based online documentation.
Yes, change is annoying, and using a new system is always frustrating when
you're used to another. I'm appending an HTML file that outlines how to do
similar tasks in OpenBook and in the new web-based system. It was our goal
to avoid losing any features that were in the previous system. The
differences between the two browsers mean that we do have to do some things
differently.
Regarding some of the specific comments:
* If you prefer a "page"-like look and feel, we do provide PDF versions
of each of the documents. Click "View/Print PDF" from any document
and you'll open a PDF version of the entire book in Acroread/Acrobat.
The PDF versions include a hyperlinked table of contents, and hyperlinks
within that document are supported. The PDF versions are optimized
for printing part or all of a book.
* It's not clear how running a local http server compromises your system's
security. Can you explain your concerns in more detail?
* Over the years, we've received comments from customers both saying
we open "too many" windows, and saying we should always open
additional windows whenever opening any document. We get slightly
more comments asking us to re-use windows (that's why OpenBook
reuses its windows by default). We're going to add a "Preferences"
command to the next iteration of cdsdoc that lets you choose:
- Whether to open a new browser window when starting the system
- Whether to open a new browser window when showing Search results
At present, you can use your browser's New command to open a second
window and then start cdsdoc. Not optimum, I grant you.
* We use JavaScript 1.3 by default, which is available if you use Netscape
4.51 or higher or Internet Explorer 5.0 or higher. The requirements for
the browsers is stated in the documentation, but it doesn't state
explicitly that one reason is due to use of Javascript; I will add that
to the documentation now! Thanks for pointing this out.
* Cookies are not required, but as you note, turning them off means
any changes or entries you made in the Search form will not be
kept. Accepting cookies internally shouldn't be a security issue,
but I understand if your browser is on the web you may have turned
cookies off. I will add a note to the documentation about the
use of cookies.
* Yes, we are going to add a navigation button for "Index." We had
omitted it only because, at the time this system was developed,
many writing groups were not creating indices due to lack of manpower.
* You are correct, one reason for the change is that supporting a
separate browsing tool that is not always available on all platforms
is a big issue for us. But we also changed because, since 1996,
customers have been asking us when we would provide HTML-based
documentation. They preferred to use a single browser and were
familiar with web browsers, and they wanted to be able to link
directly to Cadence documents from internal sites.
At the International Cadence User's Group meetings in 1997 and 1998,
more than half of the users said they would like a web-based system.
Even more wanted a central website from which they could view documents,
but supporting that is more difficult due to issues regarding
which user has access to what document. We are still looking
into how to support this.
At the ICUG meeting in 1999, we showed a prototype of this system
and told users that this would be the future system. We asked for
feedback and got responses like "We've needed this for a long time!"
We asked users to try the system and a clear majority ("Yes" answers
ranged from 91% to 99% of responses) said that they thought the
new system would meet their needs for tasks like finding information
about their products, finding information in specific books, and
generally browsing installed documentation. Granted, looking at a
system in a demo is different than installing it on your own machine.
I appreciate your comments and hope that some of this information
can help you with the new system. I will also make the changes you
suggested in the documentation.
- Barbara Heninger
Sr. Tech Pubs Consultant
Cadence Design Systems San Jose, CA
[ Editor's Note: I put Barbara's html file in the "Downloads" section of
http://www.DeepChip.com to save space in this ESNUG post. - John ]
---- ---- ---- ---- ---- ---- ----
From: jdl@user2.teleport.com (Jay Lessert)
Barbara,
Thank you so much for your follow-up, it is greatly appreciated.
> * If you prefer a "page"-like look and feel, we do provide PDF versions
> of each of the documents. Click "View/Print PDF" from any document
> and you'll open a PDF version of the entire book in Acroread/Acrobat.
> The PDF versions include a hyperlinked table of contents, and hyperlinks
> within that document are supported. The PDF versions are optimized
> for printing part or all of a book.
I haven't noticed that yet. Yes, that should take care of the times
when you're doing extended reading and format matters more. At the
expense of a fair bit of disk, I suppose. :-)
% du -s ldv30/doc
61825 doc
% du -s ldv31/doc
120665 /tools/ldv31/doc
Yup!
> * It's not clear how running a local http server compromises your system's
> security. Can you explain your concerns in more detail?
This matters in organizations that need to enforce host-by-host
security. Universities are the extreme example, but some corporations
operate this way.
cdsdoc ends up with something like this:
katra:/home/jayl 6> bps | egrep 'PID|https'
USER PID %CPU %MEM VSZ RSS TT S STIME TIME COMMAND
jayl 11246 0.7 1.5 7128 3672 pts/6 S 13:56:11 0:00 ./https -port 9000 -silent -p cdsdoc
and anyone can connect to it:
katra:/home/jayl 7> telnet katra 9000
Trying 192.168.17.51...
Connected to katra.
Escape character is '^]'.
HTTP / 1.0
HTTP/1.0 200 OK
Date: Tue, 01 Jun 1999 10:10:10 GMT
Expires: Tue, 01 Jan 1980 10:10:10 GMT
Server: Verity CDPub Search Engine 4.0
MIME-version: 1
Content-type: text/html
Since the server runs as the local user, the concern is that (for
example) a buffer overflow/stack-smashing exploit on the server would
be able to run commands or read files as that local user. There are
any number of such exploits available for various versions of Apache,
IIS, Netscape/Enterprise, etc. this is one reason why a normal Unix
Apache or Netscape/Enterprise installation usually runs as user
"nobody".
A Google search for +exploit +apache, or +exploit +iis may be
illuminating. Even a search for +exploit +verity looks interesting,
though I didn't do any detailed reading. :-)
> Over the years, we've received comments from customers both saying
> we open "too many" windows, and saying we should always open
> additional windows whenever opening any document. We get slightly
> more comments asking us to re-use windows (that's why OpenBook
> reuses its windows by default).
My sympathies, I know you can't make 'em all happy. There is a bit
of qualitative difference between hijacking a Frameviewer window
(which is most likely not being used for anything besides OpenBook)
and hijacking a Netscape window (which is almost certainly being used
for 10 things besides cdsdoc).
> We're going to add a "Preferences"
> command to the next iteration of cdsdoc that lets you choose:
>
> - Whether to open a new browser window when starting the system
> - Whether to open a new browser window when showing Search results
Terrific. That goes a long way. Make sure I can set a default for
the full installation, then let users override if they need to.
> At present, you can use your browser's New command to open a second
> window and then start cdsdoc.
Yup, I'm opening training myself to grab Netscape and do an alt-N before I
click help.
> * We use JavaScript 1.3 by default, which is available if you use Netscape
> 4.51 or higher or Internet Explorer 5.0 or higher. The requirements for
> the browsers is stated in the documentation, but it doesn't state
> explicitly that one reason is due to use of Javascript; I will add that
> to the documentation now! Thanks for pointing this out.
The issue with JavaScript is security, not available versions.
In the paragraph below you can basically s/cookies/JavaScript/g.
> * Cookies are not required, but as you note, turning them off means
> any changes or entries you made in the Search form will not be
> kept. Accepting cookies internally shouldn't be a security issue,
> but I understand if your browser is on the web you may have turned
> cookies off. I will add a note to the documentation about the
> use of cookies.
That's a good start. Both JavaScript and cookies need to be in
doc/cdsuser/trouble.html, for sure. And it would be preferable
if the server could check and generate warnings, as well.
> * Yes, we are going to add a navigation button for "Index." We had
> omitted it only because, at the time this system was developed,
> many writing groups were not creating indices due to lack of manpower.
Good, thanks. You do have existing OpenBook documents that do have
good indexes (Verilog-XL reference manual comes to mind in the current
context), there's no reason to handicap it just because other documents
are deficient.
> * You are correct, one reason for the change is that supporting a
> separate browsing tool that is not always available on all platforms
> is a big issue for us. But we also changed because, since 1996,
> customers have been asking us when we would provide HTML-based
> documentation. They preferred to use a single browser and were
> familiar with web browsers, and they wanted to be able to link
> directly to Cadence documents from internal sites.
Hmmm, we've been running tools/bin/viewer from our .mailcap for years:
application/framemaker;viewer.netscape %s
application/msword;soffice %s
application/pdf;acroread %s
application/postscript;ghostview %s
application/vnd.ms-access;soffice %s
application/vnd.ms-excel;soffice %s
application/vnd.ms-powerpoint;soffice %s
> At the International Cadence User's Group meetings in 1997 and 1998,
> more than half of the users said they would like a web-based system.
Well, I guess you've finally given me a reason to go to ICUG. :-)
Thanks again for responding publically.
- Jay Lessert Portland, Oregon
---- ---- ---- ---- ---- ---- ----
From: "stockg" <stockg@yahoo.com>
The real reason for changing is neither User Group nor everything else
mentioned by the Cadence doc writer. They are follows in the order they
appear:
1. Adobe had said they would not support ANY FrameMaker from 2000 onwards.
Cadence had to look at other alternatives. Licensing for Framemaker
could have been the issue.
2. Speed of OpenBook. And here the web-page feel nad look had an advantage
over PDF. Although if I know correctly, Cadence is still working on
getting the PDF version too later.
This is also a good time to request for any changes like a new browser. And
it should be easy to implement even for a hotfix. I believe this way they
also introduce a mechanism to give a doc for hotfix, too. Else we were
stuck with the same doc for the 100th hotfix of the same release.
- "stockg"
---- ---- ---- ---- ---- ---- ----
> The real reason for changing is neither User Group nor everything else
> mentioned by the doc writer. They are follows in the order they appear:
>
> 1. Adobe had said they would not support ANY FrameMaker from 2000 onwards.
From: jdl@user2.teleport.com (Jay Lessert)
"stockg",
Can you provide a reference for this claim please? No sign of dropping
FrameMaker on www.adobe.com that I can find, and there are a large
group of manual and databook writers back at my day job that will be
most unhappy if they have to start working in Word or StarWriter or
such.
- Jay Lessert Portland, Oregon
|
|
