[swift-evolution] [Review] SE-0112: Improved NSError Bridging

[Ben Rimmington]

> On 6 Jul 2016, at 18:09, Douglas Gregor <dgregor at apple.com> wrote:
> 
>> On Jul 5, 2016, at 10:35 PM, Ben Rimmington <me at benrimmington.com <mailto:me at benrimmington.com>> wrote:
>> 
>>> On 5 Jul 2016, at 21:41, Douglas Gregor <dgregor at apple.com <mailto:dgregor at apple.com>> wrote:
>>> 
>>>> The following comment is incorrect, AFAIK. The `helpAnchor` is the name attribute of a HTML anchor element.
>>>> 
>>>> 	/// A localized message providing "help" text if the user requests help.
>>>> 	var helpAnchor: String? { get }
>>> 
>>> Apple’s documentation says:
>>> 
>>> NSHelpAnchorErrorKey
>>> The corresponding value is an NSString containing the localized help corresponding to the help button. See helpAnchor <https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/#//apple_ref/occ/instp/NSError/helpAnchor> for more information.
>>> 
>> 
>> A `helpAnchor` in AppKit is the name of an HTML anchor element:
>> 
>> AppKit > NSPrintPanel > helpAnchor
>> <https://developer.apple.com/reference/appkit/nsprintpanel/1490537-helpanchor <https://developer.apple.com/reference/appkit/nsprintpanel/1490537-helpanchor>>
>> 
>> AppKit > NSHelpManager > openHelpAnchor(_:inBook:)
>> <https://developer.apple.com/reference/appkit/nshelpmanager/1500908-openhelpanchor <https://developer.apple.com/reference/appkit/nshelpmanager/1500908-openhelpanchor>>
>> 
>> Apple Help Programming Guide > Authoring Apple Help > Indexing Your Help Book > Setting Anchors
>> <https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-CHDFBEHF <https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html#//apple_ref/doc/uid/TP30000903-CH206-CHDFBEHF>>
> 
> The relevant “helpAnchor” is from the NSError reference documentation:
> 
> 	https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/#//apple_ref/occ/instp/NSError/helpAnchor <https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/#//apple_ref/occ/instp/NSError/helpAnchor>
> 
> which says:
> 
> A string to display in response to an alert panel help anchor button being pressed. (read-only)
> 
> Declaration
> SWIFT
> var helpAnchor: String <https://developer.apple.com/library/mac/documentation/Swift/Reference/Swift_String_Structure/index.html#//apple_ref/swift/struct/s:SS>? { get }
> OBJECTIVE-C
> @property(readonly, copy) NSString  <https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/index.html#//apple_ref/doc/c_ref/NSString>*helpAnchor
> Discussion
> The object in the user info dictionary for the key NSHelpAnchorErrorKey <https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/#//apple_ref/c/data/NSHelpAnchorErrorKey>. If the user info dictionary doesn’t contain a value for NSHelpAnchorErrorKey <https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSError_Class/#//apple_ref/c/data/NSHelpAnchorErrorKey>, this property is nil.
> 
> If this property is non-nil for an error being presented by alertWithError: <https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Classes/NSAlert_Class/index.html#//apple_ref/occ/clm/NSAlert/alertWithError:>, the alert panel will include a help anchor button that can display this string.
> 
> Availability
> Available in OS X v10.6 and later.
> 
> 	- Doug
> 

The documentation on NSError help anchors is incorrect.

	<rdar://problem/27208074>

I've tested this with a document-based Cocoa application. In the NSDocument subclass, I modified the template as follows:

	override func data(ofType typeName: String) throws -> Data {
	    throw NSError(domain: NSOSStatusErrorDomain, code: unimpErr, userInfo: [NSHelpAnchorErrorKey: "ibks5f526382"])
	}

	override func read(from data: Data, ofType typeName: String) throws {
	    throw NSError(domain: NSOSStatusErrorDomain, code: unimpErr, userInfo: [NSHelpAnchorErrorKey: "pbhlp3714a9d"])
	}

Those help anchors were copied from the following file (in macOS 10.11.5):
<file:/Library/Documentation/Help/MacHelp.help/Contents/Resources/en.lproj/navigation.json>

When I try to open or save a document, an NSAlert with a help button is presented. Clicking on that help button shows the expected help page:

	{"name":"Read books in iBooks","href":"help:anchor='ibks5f526382' bookID='com.apple.iBooksX.help'"}

	{"name":"Take a Photo Booth photo","href":"help:anchor='pbhlp3714a9d' bookID='com.apple.PhotoBooth.help'"}

But if I use a normal word or phrase with NSHelpAnchorErrorKey, the Mac Help window displays:

	The selected topic is currently unavailable.
	The topic you were trying to view could not be found.

-- Ben

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160707/a93bc8c3/attachment.html>