Re: Xcode 3 doc window woes (was: Lost markers after Reference Library update)
Re: Xcode 3 doc window woes (was: Lost markers after Reference Library update)
- Subject: Re: Xcode 3 doc window woes (was: Lost markers after Reference Library update)
- From: Ronald Hayden <email@hidden>
- Date: Mon, 31 Dec 2007 14:53:45 -0800
I'd like to piggyback off of this to express my disappointment at the
regressions in the Xcode 3 docs window. There seem to be more and
more of
them.
I understand the frustration, and I want to let you know our progress
on these items. My team handles the doc viewing functionality, and
for Leopard our focus was on getting big new features in place to
address long-standing developer requests such as allowing 3rd-party
documentation; fixing the annoying aspects of the doc update system;
not requiring the downloading of large chunks of documentation if you
don't happen to be a WebObjects or Java developer; providing enhanced
search functionality, and making it easier to find out about
documentation (the Xcode News window) and access documentation as you
work (the Research Assistant).
These features required a complete reworking of the documentation
system and a lot of new technology, and that took up all our time and
resources. Now that these things are in place, our focus is entirely
on addressing the various quality of life bugs that have accumulated
over the last couple of years. Here is where we stand on the items
you mentioned:
* As noted in the piggybacked thread, the second popup (the one
listing
methods in the current page) is no longer reliably appearing.
This is exposed by the fixing of another problem: We had numerous
complaints about the "vanishing TOC" -- depending on how you accessed
a page, the TOC for the book might not display because we were using
old-fashioned framesets. Because the TOC wouldn't always display,
people sometimes didn't realize there was more to the book than the
three paragraphs they were looking at (we actually had a bug saying
"How come this book is only three paragraphs of text?"), and very
frequently they missed the fact that a PDF version of the book was
available, as well knowing what book they were looking at, etc. It
also caused various navigation and back button problems in Xcode.
After years of complaints about this, we finally got a chance to get
rid of the old frameset mechanism (replaced by iframes), and this
exposed a fragility in our Xcode handling of the popup menu, whereby a
race condition means the popup doesn't always appear. We saw this in
our internal testing, but I decided that given the choice between this
regression for the popup menu and addressing the many problems with
the frameset-based TOC, we should proceed with the new TOC and fix the
popup for a future Xcode release. This is an unfortunately situation,
but I believe the choice is correct.
* "Find" doesn't work within a page either. It seems to find only
the first
instance of something. For example, on the NSText class ref page, hit
Command-F and search for "delete". You can only find the first
instance;
hitting Command-G repeatedly does nothing.
This is a new item (though we also just happened to get a bug report
for it), and we'll investigate ASAP and enhance our regression testing
to cover this functionality.
* Option-double-clicking something in my code sometimes takes me to
the
wrong page. For example, option-double-clicking the class name
QTMovie takes
me to a "deprecated" page about the QTMovie function that tells me I
really
ought to be looking at the page about the class QTMovie (well, duh).
This is not a bug in that we don't really know what "QTMovie" page you
are after, since both the method and the class are valid
destinations. Option-double-clicking simply does an API search for
the text and displays the first location found among the results. In
this case, both the QTMovie method and class are in the results, and
the method happens to come up first. The class (in my testing) is the
second item in the list.
In the past this situation would have caused more confusion, as the
legacy doc wasn't clearly labelled. As you mention, we now make it
very obvious that you are looking at legacy doc and we provide you a
link to what you should be looking at, which has helped people steer
clear of stuff they shouldn't be using in new development.
* Sometimes, option-double-clicking something in my code does
nothing. It
brings the docs page to the front but we don't switch content from
what's
already showing there.
If you can provide a specific example in a bug report, that would be
very helpful. Especially if you indicate what page was showing and
what symbol you option-double-clicked on.
* The bug where hitting the "back" button sometimes does not take
you to the
previously viewed page, but rather rockets you unexpectedly into
Safari, is
not fixed.
This has been discussed multiple times previously, and we believe
we've fixed it for a future release.
* The bug where, if hitting the "back" button works, it does not
take you to
the particular area of the frameset that you were looking at before,
but
rather to the top of the first page of the frameset, is not fixed.
This is one of the items actually fixed by our new TOC approach, and
I'm unable to reproduce what you are reporting. The next time you see
this, can you indicate what document it occurs in? If it's in some
old document still using a frameset TOC, that would be expected; if
it's in a document using the newer TOC, we'll need to look into this.
* There are still some malformed links. For example, the NSString
page still
thinks the info on CFString is to be found on a page called
"Introduction to
Messier Demo Book".
I don't recall a previous report on this. Fortunately the link is not
actually malformed and takes you to the correct destination, but our
production system is supplying the wrong title. We'll follow up on
this.
-- Ron
On Dec 29, 2007, at 7:26 PM, Matt Neuburg wrote:
On Fri, 28 Dec 2007 23:26:30 -0600, Ken Thomases
<email@hidden> said:
If I search for a method (for example, typing "setbyadd" in the
search
field) and then click on one of the matches (e.g.
"setByAddingObject:"), the resulting page does not have a function/
method/etc. pop-up. However, if I click on the same match a second
time, then the page refreshes and the pop-up does show up.
It's a nuisance, but it gets me the functionality I need.
Also, I may be misremembering but I don't think the pages used to
show
the table of contents on the left of the page. Now they do. I can
click the Hide TOC link to get back to the display I'm used to, but
that's an additional nuisance. Also, if I want the function/method/
etc. pop-up I need to perform the first trick before clicking Hide
TOC. Doing it in the reverse order fails because the second click on
the search match causes the table of contents to reappear.
I just now did a bit of experimenting. Using the "breadcrumb" link
for the reference page also switches from lacking the pop-up to
showing it.
More experimentation: the lack of the pop-up seems to be a timing
thing. If I keep clicking on a search match, the pop-up will
sometimes show and sometimes vanish. It is not as simple as it
toggling back and forth with each click. It seems random. My guess
is it's a race condition between the parsing and layout of the HTML
(and CSS?) and the layout of the window elements. If the former has
not completed before the latter, then the window doesn't know it
needs
a pop-up and hides it (or fails to create it).
I'd like to piggyback off of this to express my disappointment at the
regressions in the Xcode 3 docs window. There seem to be more and
more of
them. Here are some phenomena I've recently noticed:
* As noted in the piggybacked thread, the second popup (the one
listing
methods in the current page) is no longer reliably appearing.
* "Find" doesn't work within a page either. It seems to find only
the first
instance of something. For example, on the NSText class ref page, hit
Command-F and search for "delete". You can only find the first
instance;
hitting Command-G repeatedly does nothing.
* Option-double-clicking something in my code sometimes takes me to
the
wrong page. For example, option-double-clicking the class name
QTMovie takes
me to a "deprecated" page about the QTMovie function that tells me I
really
ought to be looking at the page about the class QTMovie (well, duh).
* Sometimes, option-double-clicking something in my code does
nothing. It
brings the docs page to the front but we don't switch content from
what's
already showing there.
* The bug where hitting the "back" button sometimes does not take
you to the
previously viewed page, but rather rockets you unexpectedly into
Safari, is
not fixed.
* The bug where, if hitting the "back" button works, it does not
take you to
the particular area of the frameset that you were looking at before,
but
rather to the top of the first page of the frameset, is not fixed.
* There are still some malformed links. For example, the NSString
page still
thinks the info on CFString is to be found on a page called
"Introduction to
Messier Demo Book".
m.
--
matt neuburg, phd = email@hidden, <http://www.tidbits.com/matt/>
A fool + a tool + an autorelease pool = cool!
One of the 2007 MacTech Top 25: <http://tinyurl.com/2rh4pf>
AppleScript: the Definitive Guide - Second Edition!
<http://www.amazon.com/gp/product/0596102119>
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden