Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update broken link to Apple Publication Style Guide #62221

Closed
MadisonMay mannequin opened this issue May 20, 2013 · 13 comments
Closed

Update broken link to Apple Publication Style Guide #62221

MadisonMay mannequin opened this issue May 20, 2013 · 13 comments
Assignees
@ezio-melotti
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@MadisonMay
Copy link
Mannequin

MadisonMay mannequin commented May 20, 2013

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
    Copy link
    Mannequin Author

    MadisonMay mannequin commented May 20, 2013

    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 MadisonMay mannequin added type-feature A feature request or enhancement docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error and removed type-feature A feature request or enhancement labels May 20, 2013
    @MadisonMay
    Copy link
    Mannequin Author

    MadisonMay mannequin commented Jun 3, 2013

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

    @dmibaranov
    Copy link
    Mannequin

    dmibaranov mannequin commented Jun 3, 2013

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

    @terryjreedy
    Copy link
    Member

    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
    Copy link
    Mannequin Author

    MadisonMay mannequin commented Jun 3, 2013

    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
    Copy link
    Member

    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
    Copy link
    Mannequin Author

    MadisonMay mannequin commented Jun 4, 2013

    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
    Copy link
    Mannequin Author

    MadisonMay mannequin commented Jun 4, 2013

    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
    Copy link
    Member

    "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
    Copy link
    Member

    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
    Copy link
    Mannequin Author

    MadisonMay mannequin commented Jul 4, 2013

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

    @python-dev
    Copy link
    Mannequin

    python-dev mannequin commented Jul 14, 2013

    New changeset dcb9ec098781 by Ezio Melotti in branch 'default':
    bpo-18021: remove broken link to the Apple Style Guide. Patch by Madison May.
    http://hg.python.org/devguide/rev/dcb9ec098781

    @ezio-melotti
    Copy link
    Member

    Since this was keep getting reported (see e.g. bpo-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).

    @ezio-melotti ezio-melotti self-assigned this Jul 14, 2013
    @ezio-melotti ezio-melotti added type-feature A feature request or enhancement and removed type-bug An unexpected behavior, bug, or error labels Jul 14, 2013
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @hugovk hugovk mentioned this issue Mar 19, 2024
    Merged
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees

    @ezio-melotti ezio-melotti

    Labels
    docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @ned-deily @terryjreedy @ezio-melotti