[39458] trunk/doc-new/guide/xml/installing.xml

[markd at macports.org]

>> Hi Ryan,
>>
>> Personally, I'd prefer directing users to the place where the
>> latest Xcode
>> version is listed for the current OS (10.5) since it is a moving
>> target.
>> Otherwise we fix the guide in time more than absolutely necessary and
>> commit ourselves to updating the guide for Apple updates anywhere such
>> references are made.   Also, saying "at the time of writing" seems
>> not to
>> help since there isn't a way to know what time that is for that
>> particular
>> text snippet, so it almost invites putting the date in parenthesis.
>>
>> I see that Apple's developer site now has a button named "Download
>> Latest
>> Xcode"    [ http://developer.apple.com/tools/xcode/
>]http://developer.apple.com/tools/xcode/
>>
>> So I favor something like I pasted below.  I can't even find Xcode
>> 1.5 on
>> Apple's site (though it must be there somewhere), and since we don't
>> officially support 10.3 anymore I don't think anything needs to be
>> said on
>> that.
>>
>> ---------------------
>> Download and install the latest version of Xcode Tools by clicking the
>> button "Download Latest Xcode" here:
>> ([ http://developer.apple.com/tools/xcode/)
>]http://developer.apple.com/tools/xcode/).  Do not install Xcode Tools
>> from a Mac OS X install DVD unless you verify that you are
>> installing the
>> latest version as listed on Apple's developer site; older versions
>> often
>> cause port install failures.
>>
>> If you are installing MacPorts on Mac OS X 10.4, download and install
>> Xcode 2.5
>> ([ http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/
>]http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/
>> getSoftware?bundleID=19907)
>> ---------------------
>>
>> How does that seem?
>
>I made the change specifically in response to a user who was confused
>when Xcode 2 did not work with Leopard, because he couldn't find a
>newer version on Apple's site:
>
>[ http://lists.macosforge.org/pipermail/macports-users/2008-August/
>]http://lists.macosforge.org/pipermail/macports-users/2008-August/
>011312.html
>
>He went to ADC: Downloads: Mac OS X. The latest version I find there
>is 2.2.1.

But he wasn't led astray by the Guide.  The Guide can and needs to be
improved, but doesn't necessarily help to modify guide text to try to
solve a specific problem that arose because a user ignored that very Guide
text, especially when the text that was in front of the user's face
(Apple's) before they clicked download were ignored.  Here is Apple's text
at that link.

----------
Xcode Tools 2.2.1:
Xcode 2.2.1 is an update for the Mac OS X v10.4 Xcode Tools suite.
Please see the Read Me document for more details and installation
instructions.
-----------

What needs to be fixed is Apple's ADC site, but nowhere I know of in the
Guide do we point users there.
>
>Now, you and I know to go to ADC: Downloads: Developer Tools instead,
>which is where all versions of the Developer Tools (except Xcode 2.0)
>are located, going back to the December 2002 Developer Tools for
>Jaguar before it was even called Xcode. But if a user doesn't know
>that Xcode 2.2.1 isn't the latest, they won't go looking for a newer
>one.
>
>I don't like the "Download Latest Xcode" button because it only gives
>you the latest Xcode for Leopard; it doesn't give you the latest
>Xcode for Tiger or Panther.

Giving the link to the "latest Xcode" for 10.5 was only one part of my
suggestion:

------------------
Download and install the latest version of Xcode Tools by clicking the
button "Download Latest Xcode" here:
(http://developer.apple.com/tools/xcode/).  Do not install Xcode Tools
from a Mac OS X install DVD unless you verify that you are installing the
latest version as listed on Apple's developer site; older versions often
cause port install failures.

If you are installing MacPorts on Mac OS X 10.4, download and install
Xcode 2.5
(http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/getSoftware?bundleID=19907)
-------------------

The suggested text does tell you where to find Xcode 2.5 for 10.4, which
the current instructions do not, and finding it isn't as easy as it seems.
 Telling someone what they need and showing them where it are different
things.  Do to the magic of hyperlinking, we can do both at once and I
think this is a slight improvement.

>I do want to continue supporting Panther
>as much as possible. I know we have at least one active Panther user
>on the list. I see no reason to cut off support for Panther at this
>time.

Nobody is "cutting off" anything.  The support is what it is.  It is a
question of what is recommended.  I would not like to give the impression
that we provide better support that we actually do, and support for 10.3
is pretty darn weak.   We all know that we aren't prepared to do much to
actively support 10.3, so how long will it be before in response to a MP
developer's suggestion that (at the very least) it is wise to avoid 10.3
if possible that we hear: "But on page 1 at the top of the Guide it states
requirements for 10.3 (implying it is supported), and now you're telling
me it isn't supported?"  And we do say that, and I think we've had this
discussion many times before.

But look, I know I'm acting as a self-appointed documentation Nazi, and
probably  coming off as too argumentative, but the truth is I think there
are unstated assumptions at work in discussions about the Guide.  I think
failure to observe a certain rules ruins a document over time, and that
disagreement on those implicit assumptions is the source of most of the
disagreements on MP docs.  I have several in mind:

1) One I'm always pushing is basically the 80/20 rule (or 95/5 or
insert_your_own_numbers here).  We have a mailing list, and it will always
be used and needed, and a wiki.  Some questions are best answered by the
list, and trying to answer certain questions that fall in the 20% in the
Guide will destroy it over time.  The Guide is an attempt to document
certain things, not everything.  A document can't be all thing to all
people.

2) No duplication of text unless absolutely necessary.  This is a
volunteer project and we must minimize the effort required for
documentation, or it will seem futile to have good documents in a
reasonable length of a volunteer's time.  Soon, in a future release, the
man pages will be sourced oet of the Guide and this is a big step in
having accurate and maintainable documents.

3) Minimalism is good, because people only have so much time to read. 
Everything that can be said shouldn't be.  All text needs to support the
main purpose of the document.

I think probably we should hash out this stuff as a community, and I'm
always willing to submit this sort of thing to a vote.  I think a certain
ruthless adherence to these principals will get us a better Guide in the
end since comprehensive documentation is difficult and none of us get paid
for this.  I can look at almost any part of the Guide and think "That
could be a lot better", but I think when trying to do so I think there
should be overall consideration of the document design principles.  BTW, I
do intend to start in on the unfinished sections of the Guide very soon,
and also address the tickets on it.  Hopefully in a matter of weeks.
>
>I agree "as of this writing" isn't good without a date, and that I
>shouldn't have created the situation where we have to update the
>Guide with "latest" information about Xcode releases, even if they
>are infrequent. Instead, how about we list a minimum Xcode version?
>The minimum supported Xcode version for MacPorts is 3.0 on Leopard,
>2.4 on Tiger and 1.5 on Panther, as seen in the MacPorts configure
>script:
>
>
>case "$XCODE_VERSION" in
>   1.[[0-1]]*|2.[[0-1]]*)
>     AC_WARN(This version of Xcode Tools is not supported)
>     AC_WARN(Please upgrade at [ http://connect.apple.com/
>]http://connect.apple.com/)
>     ;;
>   1.[[2-4]]*|2.[[2-3]]*)
>     AC_WARN(This version of Xcode Tools is out of date)
>     AC_WARN(Please consider upgrading as some ports fail compiling)
>     ;;
>   1.5*|2.4*|3.*)
>     dnl Supported version
>     ;;
>   *)
>     ;;
>esac 

I prefer to let the scripts do their job and warn the user appropriately
without duplicating the script messages in the documentation.  Principal
#2.  :)

Please don't take me as being rude or argumentative.  I just have a vision
for the docs I'd like to argue for and to put forth some working
assumptions that I've always used for the Guide.  I think discussing these
issues as a community is a good thing.

Cheers,

Mark