Update broken link to Apple Publication Style Guide

[MadisonMay]

BPO	18021
Nosy	@birkenfeld, @terryjreedy, @ned-deily, @ezio-melotti
Files	apple_style_guide.patch: Patch file for a simple url change apple_style_guide_v2.patch: Fully searchable replacement for link to pdf, will presumably stay up to date apsg_removed.patch: Patch file with references to APSG removed.

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ezio-melotti'
closed_at = <Date 2013-07-14.07:19:14.977>
created_at = <Date 2013-05-20.13:12:18.183>
labels = ['type-feature', 'docs']
title = 'Update broken link to Apple Publication Style Guide'
updated_at = <Date 2013-07-14.07:19:14.975>
user = 'https://bugs.python.org/madisonmay'

bugs.python.org fields:

activity = <Date 2013-07-14.07:19:14.975>
actor = 'ezio.melotti'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2013-07-14.07:19:14.977>
closer = 'ezio.melotti'
components = ['Devguide']
creation = <Date 2013-05-20.13:12:18.183>
creator = 'madison.may'
dependencies = []
files = ['30456', '30457', '30775']
hgrepos = []
issue_num = 18021
keywords = ['patch']
message_count = 13.0
messages = ['189659', '190551', '190552', '190553', '190555', '190567', '190578', '190593', '190608', '190609', '192299', '193032', '193033']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'terry.reedy', 'ned.deily', 'ezio.melotti', 'python-dev', 'dmi.baranov', 'madison.may']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue18021'
versions = []

[MadisonMay]

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.

[MadisonMay]

The attached patch updates the urls on the Documenting and Doc Quality pages to reference the new Apple Style Guide.

[dmibaranov]

That link will be outdated in next few months (I believe :-)). What about https://help.apple.com/asg/mac ?

[terryjreedy]

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.

[MadisonMay]

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.

[ned-deily]

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.

[MadisonMay]

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

[MadisonMay]

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?

[ned-deily]

"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.

[ezio-melotti]

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.

[MadisonMay]

If the general consensus is that the APSG link should be removed, here's one more patch for you.