Default DocSetPlatformFamily #217

Closed
Kapeli opened this Issue May 16, 2012 · 23 comments

Projects

None yet

4 participants

@Kapeli
Kapeli commented May 16, 2012

Can you set the DocSetPlatformFamily key to default to "appledoc"? Having "appledoc" as the docset platform allows Dash (http://kapeli.com/dash) to recognise a docset as Appledoc-generated and enable extra features for it (table of contents and click-to-copy). Thanks!

@tomaz
Owner
tomaz commented May 16, 2012

Could you elaborate a bit more, not sure I understand your question... It was a while since I used this functionality, but taking a quick look there is --docset-platform-family switch, is it not working? You could set it as global template so it's always used.

@Kapeli
Kapeli commented May 16, 2012

There is nothing wrong with the --docset-platform-family switch. This is a feature request, not a bug/issue.

What I was asking is to add "appledoc" as the default DocSetPlatformFamily key. That would be when there is no --docset-platform-family specified, "appledoc" would be used.

Xcode does not use the platform family for anything, as far as I know, but Dash uses it in order to determine how it will parse the pages it's displaying. It would be of help for people that are using Dash and appledoc both, if the default value would be "appledoc".

@tomaz
Owner
tomaz commented May 17, 2012

I see, I suppose I could do that, but will check with Apple docs first so that it won't surprise users that require and use it. It this case, users can add the setting to global settings, and have it available for all their projects.

@Kapeli
Kapeli commented May 17, 2012

The default currently is to have no DocSetPlatformFamily. If a user currently requires and uses it, they will be unaffected. I'm just asking to have a DocSetPlatformFamily of "appledoc" if there is NO other one (i.e. instead of having the entry missing completely, have it set to appledoc). Thanks!

@tomaz
Owner
tomaz commented May 18, 2012

I'm a bit reluctant to use "hijack" plist keys for custom functionality, but can't find the info in Apple docs anymore, so they probably don't use this key anymore. So it seems like it's safe to use appledoc by default. It's possible to change in case this isn't desired anyway...

BTW: not really related to this issue, but anyway: I really like dash (especially after "standard" mode ;) using it for quite some time now and still find it the fastest way for finding API docs. I still find Xcode navigation bar more useful and faster for reading through a guide though, so in case I come to a guide from class, I tend to switch back to Xcode and search for it in documentation. I find this reduces usability of the tool - is there some way of telling dash to open a link in Xcode? Or implement TOC for guides too? Just an idea...

@tomaz tomaz added a commit that closed this issue May 18, 2012
@tomaz Implemented better support for Dash. Closes #217.
Dash can take advantage of appledoc generated documentation sets by displaying TOC and click to copy. To be able to do so, it requires `--docset--platform-family` value to be `appledoc`. Current documentation set reference doesn't mention this key anymore, so it seems safe to hijack it. If this isn't desired, you can still revert to empty string or whichever value you want by explicitly using the cmd line switch (of course, you can also do it inside project or global settings plist files).
308c923
@tomaz tomaz closed this in 308c923 May 18, 2012
@Kapeli
Kapeli commented May 18, 2012

Thanks for adding this! I'm quite sure Xcode doesn't use the DocSetPlatformFamily key anymore.

I don't think I understand the navigation problem. Can you give an example of a page/guide/workflow that is better handled by the Xcode documentation browser, and where Dash is lacking? Apart from the fact that Dash does not search guides, of course :)

@tomaz
Owner
tomaz commented May 18, 2012

When guide is opened in dash, there's no toc available so the only way of navigating through pages is via next/prev links. In Xcode we can use navigation bar at top to see the list of all sections and jump straight to desired one.

Hope that's enough, otherwise let me know and I can prepare few screenshots that would better demonstrate the issue.

Tomaz

On Friday, 18. May 2012 at 12:54, Bogdan Popescu wrote:

Thanks for adding this! I'm quite sure Xcode doesn't use the DocSetPlatformFamily key anymore.

I don't think I understand the navigation problem. Can you give an example of a page/guide/workflow that is better handled by the Xcode documentation browser, and where Dash is lacking? Apart from the fact that Dash does not search guides, of course :)


Reply to this email directly or view it on GitHub:
#217 (comment)

@Kapeli
Kapeli commented May 18, 2012

That's enough. The main problem is that Dash was never thought of as a guide-browser. I ignored guides from the start and only dealt with API reference. I'm not sure how to best approach this problem, but I am now aware of it and will think about it. Thanks!

@lobodpav
lobodpav commented Jun 9, 2012

In Xcode 4.3.2 the DocSetPlatformFamily is probably used to identify whether or not to display Quick Help information. If the DocSetPlatformFamily is set to appledoc, the Quick Help does not work. If I set it to macosx, Quick Help starts to work well.

@Kapeli
Kapeli commented Jun 9, 2012

Does Xcode show Quick Help if there is no platform family set at all (which was the previous appledoc default)?

@lobodpav

Indeed it works when empty. If set to 'appledoc' it stops working.

@tomaz
Owner
tomaz commented Jun 10, 2012

Hm, I got several bug reports regarding this, but it didn't occur to me it was platform family... Will switch back.

As for Dash integration, the users would need to build docsets twice (they can use project settings for all defalts and only add single --docset-platform-family attribute to cmd line for building Dash compatible docsets). Or alternatively, find anoter mechanism to identify appledoc generated docsets.

On 10. jun. 2012, at 07:30, Pavel Lobodinskýreply@reply.github.com wrote:

Indeed it works when empty. If set to 'appledoc' it stops working.


Reply to this email directly or view it on GitHub:
#217 (comment)

@lobodpav

Important is that the reason for Quick Help to stop working is now known. I have added --docset-platform-family attribute into my blog so the Xcode users will get the tool working.

@Kapeli
Kapeli commented Jun 10, 2012

Sorry to everyone for suggesting this change, I was not aware of Xcode's Quick Help relying on the platform.

I've changed Dash so that it will look for a "DashDocSetFamily" key as well. If possible, please set that to be "appledoc".

@lobodpav

No worries. We just learned something new! :)

@tomaz
Owner
tomaz commented Jun 11, 2012

Just pushed update, appledoc now uses empty string as default for platform family and appledoc with DashDocSetFamily. Give it a go and report back in case I missed something (BTW: I've updated docset template, so you need to use the new one or Dash specific output will not be generated).

Just out of curiosity: in what way does Dash treat appledoc generated docsets differently - I can't see a difference in docsets I'm using?

@lobodpav

I have tested it just now. If the --docset-platform-family attribute is omitted in AppledocSettings.plist, the Quick Help works well. I.e. your fix works well :)

@Kapeli
Kapeli commented Jun 11, 2012

Thanks for adding the DashDocSetFamily key. Dash will support it from version 1.6.5.

Dash needs a way of knowing that the docset is appledoc so that it knows how to look inside the page to extract the class methods and display them in the filterable table of contets that shows up at the bottom. It's not required (Dash works perfectly fine without it), but it's a nice addition.

I'll check out the new template and see if it breaks anything. Thanks for letting me know.

@Kapeli
Kapeli commented Jun 11, 2012

Just tested. Everything is working fine with (future) version 1.6.5 of Dash :)

@tomaz
Owner
tomaz commented Jun 11, 2012

Cool!

On Jun 11, 2012, at 11:08, Bogdan Popescu reply@reply.github.com wrote:

Just tested. Everything is working fine with Dash :)


Reply to this email directly or view it on GitHub:
#217 (comment)

@s2m-updater s2m-updater pushed a commit to SinnerSchraderMobileMirrors/appledoc that referenced this issue Jun 29, 2012
@tomaz Fixed Xcode quick help. Fixes #217.
Turns out recent change to better support Dash broke Xcode quick help - Xcode does rely on `DocSetPlatformFamily` info plist key, must be either empty string or one of the valid platforms. To compensate and still support Dash, a custom key was introduced - `DashDocSetFamily`, if its value is `appledoc`, Dash will use optimized rendering.
f53b1aa
@TheRealKerni

This sadly doesn't work with Xcode 4.4-DP7. It requires the DocSetPlatformFamily to be not empty, not appledoc but a supported platform, e.g. iphoneos or macosx.

An option might be adding a command line parameter to set the value of this when generating the docs, so it can be set to the correct platform.

@TheRealKerni

My mistake, it is already there. So to get working QuickHelp run appledoc with this parameter: --docset-platform-family "iphoneos"

@tomaz
Owner
tomaz commented Jul 23, 2012

Thanks for reporting about this change. Didn't have much of a use for docsets lately, so didn't notice it...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment