classification
Title: Update broken link to Apple Publication Style Guide
Type: enhancement Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: dmi.baranov, ezio.melotti, georg.brandl, madison.may, ned.deily, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2013-05-20 13:12 by madison.may, last changed 2013-07-14 07:19 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
apple_style_guide.patch madison.may, 2013-06-03 17:13 Patch file for a simple url change
apple_style_guide_v2.patch madison.may, 2013-06-03 18:50 Fully searchable replacement for link to pdf, will presumably stay up to date
apsg_removed.patch madison.may, 2013-07-04 16:56 Patch file with references to APSG removed.
Messages (13)
msg189659 - (view) Author: Madison May (madison.may) * Date: 2013-05-20 13:12
The links at http://docs.python.org/devguide/documenting.html#building-doc and http://docs.python.org/devguide/docquality.html to http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf lead to a "Page Not Found" message and a redirect to http://developer.apple.com/library/mac/navigation/.  This url should be updated to point to another copy of the 2009 style guide or https://help.apple.com/asg/mac/2013/ASG_2013.pdf, the 2013 version of Apple's Style Guide.
msg190551 - (view) Author: Madison May (madison.may) * Date: 2013-06-03 17:13
The attached patch updates the urls on the Documenting and Doc Quality pages to reference the new Apple Style Guide.
msg190552 - (view) Author: Dmi Baranov (dmi.baranov) * Date: 2013-06-03 18:22
That link will be outdated in next few months (I believe :-)). What about https://help.apple.com/asg/mac ?
msg190553 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-06-03 18:30
The latter link redirects to the current online searchable html version,
http://help.apple.com/asg/mac/2013/ 
and presumably always will. I think this is better than the 200 page pdf.
msg190555 - (view) Author: Madison May (madison.may) * Date: 2013-06-03 18:50
Updated patch to link instead to http://help.apple.com/asg/mac.

Thanks for that catch, Dmi and Terry.  I have to agree that its a much better alternative.
msg190567 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2013-06-03 21:34
Has anyone looked at the current Apple style guide to determine whether it is still an appropriate reference for Python doc usage?  It appears to have undergone some major changes over the years as Apple's docs have changed.
msg190578 - (view) Author: Madison May (madison.may) * Date: 2013-06-04 02:41
I actually had a bit of a hard time even locating a copy of the 2009 version.  Thanks to the Wayback Machine, here's the 2009 version of the pdf for reference: http://web.archive.org/web/20121221004340/https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf
msg190593 - (view) Author: Madison May (madison.may) * Date: 2013-06-04 09:47
So I've done a quick comparison of the two, and for the most part each entry is an identical copy of the 2009 version.  Some dated entries have been removed, which I would consider a plus -- who realistically needs to know how to refer to a 56K modems these day, anyhow :) 

Aside from this kind of removal, a slightly modified layout, and a few updated images, I haven't noticed any significant differences.  What caught your eye, Ned?
msg190608 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2013-06-04 19:49
"Documenting Python" references to the Apple Style Guide go back to at least Python 2.3.5's documentation, at that time to the 2001 version of the Apple Style Guide.  I was more curious if the Apple Style Guide was still being actively consulted by the documentation team or if this had become a vestigial link, being updated by rote.  So, I'd say update the link unless Georg or someone else says it is no longer relevant.
msg190609 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-06-04 20:04
I don't think I ever read/consulted that page, except maybe the first time I came across that link.  I consult http://docs.python.org/devguide/documenting.html regularly, but that is mostly for the rst markup.  Usually I just try to be consistent with the document I'm working on.
Removing the link altogether would be fine with me.
msg192299 - (view) Author: Madison May (madison.may) * Date: 2013-07-04 16:56
If the general consensus is that the APSG link should be removed, here's one more patch for you.
msg193032 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-07-14 07:12
New changeset dcb9ec098781 by Ezio Melotti in branch 'default':
#18021: remove broken link to the Apple Style Guide.  Patch by Madison May.
http://hg.python.org/devguide/rev/dcb9ec098781
msg193033 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-07-14 07:19
Since this was keep getting reported (see e.g. #18446) I now removed the link.  If you think an updated link to the Apple Style Guide should be included instead please reopen, but from a quick look at it it's hard to tell what parts are relevant to our docs.
Thanks Madison for the patch(es).
History
Date User Action Args
2013-07-14 07:19:14ezio.melottisetstatus: open -> closed
type: behavior -> enhancement
messages: + msg193033

assignee: ezio.melotti
resolution: fixed
stage: patch review -> resolved
2013-07-14 07:12:10python-devsetnosy: + python-dev
messages: + msg193032
2013-07-04 16:56:41madison.maysetfiles: + apsg_removed.patch

messages: + msg192299
2013-07-04 12:03:52ronaldoussorenlinkissue18358 superseder
2013-06-04 20:04:14ezio.melottisetmessages: + msg190609
2013-06-04 19:49:21ned.deilysetnosy: + georg.brandl
messages: + msg190608
2013-06-04 09:47:10madison.maysetmessages: + msg190593
2013-06-04 02:41:35madison.maysetmessages: + msg190578
2013-06-03 21:34:02ned.deilysetnosy: + ned.deily
messages: + msg190567
2013-06-03 18:50:46madison.maysetfiles: + apple_style_guide_v2.patch

messages: + msg190555
2013-06-03 18:30:29terry.reedysetnosy: + terry.reedy

messages: + msg190553
stage: needs patch -> patch review
2013-06-03 18:22:38dmi.baranovsetnosy: + dmi.baranov
messages: + msg190552
2013-06-03 17:13:08madison.maysetfiles: + apple_style_guide.patch
keywords: + patch
messages: + msg190551
2013-06-03 16:19:09brett.cannonsetstage: patch review -> needs patch
2013-06-03 16:18:58brett.cannonsetstage: patch review
2013-05-20 13:37:47madison.maysettype: enhancement -> behavior
2013-05-20 13:12:18madison.maycreate