Re: Help with Help
Thanks for that info. I’ll look deeper into it. Sometimes I put out statements in hope that someone will clarify the issue. Our app is complex, years in development, and will require a substantial help book, including videos (maybe the web version), external links, and contextual-help anchors. On 5/7/14 10:46 PM, Dennis li...@dbandel.com wrote: As somebody who did a lot of development work on early versions of Simple Help Editor, I’d like to point out a misstatement. It does not require one to write their own HTML. It does a quite capable job of translating styled text into HTML, but does offer the ability to handle custom HTML for things like tables, that don’t translate easily as styled text. I would agree that it can be a complex application if you want to get beyond the basics. On May 7, 2014, at 10:08 AM, Gordon Apple g...@ed4u.com wrote: I then tried the $150 (limited free trial) SimpleHelpEditor. It¹s a lot more capable, but complex, and you end up having to write all the HTML yourself anyway, so why bother? ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
For those interested, I put together a blog entry of my personal notes over the years on using Apple's Help: Help on OS X Help http://www.toddheberlein.com/blog/2014/5/8/help-on-os-x-help On May 8, 2014, at 10:50 AM, Gordon Apple g...@ed4u.com wrote: Our app is complex, years in development, and will require a substantial help book, including videos (maybe the web version), external links, and contextual-help anchors. You might want to think about just putting all your Help on a web site then. From anywhere in your application you can provide a button or menu item that will jump to an IBAction method that simply opens the appropriate web page in the user's web browser. Here is an example from my code: [[NSWorkspace sharedWorkspace] openURL: [NSURL URLWithString:@http://www.netsq2.com/tools/audit-viewer/downloads;]]; Todd ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
On 29 Apr 2014, at 19:52, Gordon Apple g...@ed4u.com wrote: We would like to get a recommendation on the best way to generate a help system for a fairly complex application. We started by using a simple web view and created about 120 screens in BBEdit, mostly drill-down outlines. Unfortunately, this has been proven to be difficult to maintain. We¹ve looked into web generators like RapidWeaver, Freeway, and even Dreamweaver, but all of these have been described as ³roach motels² where you enter but can never leave. We would like to have both local and web-based or web-updated content and have contextual help. This all brings us to Apple¹s ³Help Book², which seems to have been around forever and presents its own learning curve. So the question is: Is this the way to go? It it still current? What are the experiences in using it? At its core, a help book is just HTML, with a few extra tags thrown in. So I'd recommend that. That said, if you're looking for a tool to generate such help, that's your answer as well. Pick anything that spits out HTML and lets you add the required extra tags. This includes all web programming languages, i.e. I worked on a project where we ran the PHP command line tool over a bunch of PHP files and generated plain HTML files suitable for use with Apple Help from that. These days you'd probably go with Ruby or so. Cheers, -- Uli Kusterer The Witnesses of TeachText are everywhere... http://www.zathras.de ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
I'd strongly recommend against using Apple's Help Book application. There are a few problems with Apple Help: Problems with Help Books First of all, they are poorly documented. It is extremely difficult to structure them in the right way. You can't use HTML5, you have to use some special XHTML doctype. It took me weeks to find the right tags / anchors and all the implicit requirements to get it working. Once you get them working, they might fail mysteriously. Sometimes Help Viewer won't find your Help Book. Sometimes it will take 30 seconds or longer until the Help Book is displayed, without any sensible feedback to the user. Sometimes old versions of your Help Book will be displayed. Searching Help Books is slow. Again, no feedback, so your users will think there are no results, when in reality Help Viewer is still indexing your help book. Additionally, the erratic behaviour seemed to change with every major version of OS X. Finally, when I contacted Apple Developer Technical Support, they told me that they don't offer support for Help Books. Alternatives = The solution I went with was to use a simple web view that displays normal HTML pages. A plain window with three toolbar items: back / forward / index. Additionally, I provide the documentation for the latest version on my website. The HTML in the app and on the website is slightly different, I use PHP to generate the HTML. A more modern approach would probably be to use a static site generator like Jekyll, which would allow you to use templates, write in Markdown, etc. Best wishes, Jakob Am 29.04.2014 um 19:52 schrieb Gordon Apple g...@ed4u.com: We would like to get a recommendation on the best way to generate a help system for a fairly complex application. We started by using a simple web view and created about 120 screens in BBEdit, mostly drill-down outlines. Unfortunately, this has been proven to be difficult to maintain. We¹ve looked into web generators like RapidWeaver, Freeway, and even Dreamweaver, but all of these have been described as ³roach motels² where you enter but can never leave. We would like to have both local and web-based or web-updated content and have contextual help. This all brings us to Apple¹s ³Help Book², which seems to have been around forever and presents its own learning curve. So the question is: Is this the way to go? It it still current? What are the experiences in using it? ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/jakob%40eggerapps.at This email sent to ja...@eggerapps.at ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
On May 7, 2014, at 9:44 AM, Jakob Egger ja...@eggerapps.at wrote: Problems with Help Books First of all, they are poorly documented. I disagree with most of Mr. Egger's comments about Help Book problems, but he is certainly right that they are still poorly documented. The documentation confuses the pre- and post-Snow Leopard forms of Help Books and is virtually impossible to follow, despite years of complaints to Apple. As far as I know, the only comprehensive explanation of the new post-Snow Leopard version of Help Books is Chapter 11 of my book, Cocoa Recipes for Mac OS X, Second Edition (Peachpit Press 2010). -- Bill Cheeseman - b...@cheeseman.name ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
Wow! That¹s quite an indictment of one of Apple, Inc¹s supposed developer tools. You¹d think that with $190B cash, they could fix this. One of the problems I ran into is that I couldn¹t find the indexing tool without going back to old versions. When I tried to use it, it choked, spewing a litany of error messages. So much for that (and using contextual help anchors). I did take a stab at using the $39 (30-day free trial) HelpSupreme app. Aside from a few bugs, anomalies, and irritations, it worked, but I didn¹t care for the format. (That might be fixable in their CSS files.) Unfortunately, it has no provision for external links, movie files, or anchors. I then tried the $150 (limited free trial) SimpleHelpEditor. It¹s a lot more capable, but complex, and you end up having to write all the HTML yourself anyway, so why bother? One thing I found out is that if your root file is not index.html, you¹d better make sure your help file identifier does not have any spaces in it. I¹m considering just going back to my original (successful) approach and doing it all in BBEdit, for lack of finding any superior approach. On 5/7/14 8:44 AM, Jakob Egger ja...@eggerapps.at wrote: I'd strongly recommend against using Apple's Help Book application. There are a few problems with Apple Help: Problems with Help Books First of all, they are poorly documented. It is extremely difficult to structure them in the right way. You can't use HTML5, you have to use some special XHTML doctype. It took me weeks to find the right tags / anchors and all the implicit requirements to get it working. Once you get them working, they might fail mysteriously. Sometimes Help Viewer won't find your Help Book. Sometimes it will take 30 seconds or longer until the Help Book is displayed, without any sensible feedback to the user. Sometimes old versions of your Help Book will be displayed. Searching Help Books is slow. Again, no feedback, so your users will think there are no results, when in reality Help Viewer is still indexing your help book. Additionally, the erratic behaviour seemed to change with every major version of OS X. Finally, when I contacted Apple Developer Technical Support, they told me that they don't offer support for Help Books. Alternatives = The solution I went with was to use a simple web view that displays normal HTML pages. A plain window with three toolbar items: back / forward / index. Additionally, I provide the documentation for the latest version on my website. The HTML in the app and on the website is slightly different, I use PHP to generate the HTML. A more modern approach would probably be to use a static site generator like Jekyll, which would allow you to use templates, write in Markdown, etc. Best wishes, Jakob ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
Apple help is unacceptably slow.
I just opened Safari's help, and it timed out, giving the no information for
that topic message. Subsequent invocations are faster, but it is still a
painful performance.
And this was on an Core i7 MBP with 16gB of RAM.
I further note that Apple's own iWork apps use online help pages that open in
Safari.
Perhaps that is a hint.
Kirk Kerekes
(iPhone)
On May 7, 2014, at 12:08 PM, cocoa-dev-requ...@lists.apple.com wrote:
Send Cocoa-dev mailing list submissions to
cocoa-dev@lists.apple.com
To subscribe or unsubscribe via the World Wide Web, visit
https://lists.apple.com/mailman/listinfo/cocoa-dev
or, via email, send a message with subject or body 'help' to
cocoa-dev-requ...@lists.apple.com
You can reach the person managing the list at
cocoa-dev-ow...@lists.apple.com
When replying, please edit your Subject line so it is more specific
than Re: Contents of Cocoa-dev digest...
Today's Topics:
1. NSWorkspace issue (Varun Chandramohan)
2. Re: NSWorkspace issue (Ken Thomases)
3. Re: How to convert a UTF-8 byte offset into an NSString
characteroffset? (Uli Kusterer)
4. Re: Help with Help (Uli Kusterer)
5. Resizing last column of NSTableView when it touches window
border (Jakob Egger)
6. Re: Help with Help (Jakob Egger)
7. Re: Help with Help (Bill Cheeseman)
8. NSData problems and viewing buffer data in hex (William Squires)
9. Re: NSData problems and viewing buffer data in hex (Jens Alfke)
10. NSNumberFormatter 10.0+ style exception with zero (Howard Moon)
11. Re: Help with Help (Gordon Apple)
--
Message: 1
Date: Wed, 07 May 2014 05:02:54 +
From: Varun Chandramohan varun.chandramo...@wontok.com
To: Cocoa dev Cocoa-dev@lists.apple.com
Subject: NSWorkspace issue
Message-ID: cf8ffbad.14fd%varun.chandramo...@wontok.com
Content-Type: text/plain; charset=us-ascii
Hi All,
I wanted to open a Finder window from my app with a file pre-selected. The
user could perform any Finder operations needed. I looked around the internet
and it turns out the best way to do this is using NSWorkspace.
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification
{
// Insert code here to initialize your application
NSURL *fileURL = [NSURL URLWithString:@/Users/usr/Desktop/libd.dylib];
NSArray *fileURLs = [NSArray arrayWithObjects:fileURL, nil];
[[NSWorkspace sharedWorkspace] activateFileViewerSelectingURLs:fileURLs];
}
However, I am not sure what is going on. The Finder window never pops up. I
do see the top bar change to Finder bar but then the window is never present.
The file I am trying to highlight is present. Is there anyway to know error
code? The method is void.
Regards,
Varun
--
Message: 2
Date: Wed, 07 May 2014 00:58:21 -0500
From: Ken Thomases k...@codeweavers.com
To: Varun Chandramohan varun.chandramo...@wontok.com
Cc: Cocoa dev Cocoa-dev@lists.apple.com
Subject: Re: NSWorkspace issue
Message-ID: bfe724aa-f5dd-418c-839f-b320f5401...@codeweavers.com
Content-Type: text/plain; charset=us-ascii
On May 7, 2014, at 12:02 AM, Varun Chandramohan wrote:
NSURL *fileURL = [NSURL URLWithString:@/Users/usr/Desktop/libd.dylib];
This is not correct. +[NSURL URLWithString:] expects a valid URL string.
What you're providing is a file path string, which is not a URL string. A
URL string might be http://www.apple.com; or
file:///Users/usr/Desktop/libd.dylib. However, never just prepend
file:// to a file path to try to make it into a URL string. That doesn't
correctly handle a path which contains characters which are not valid in URLs.
The correct thing to do is use +[NSURL fileURLWithPath:] or a similar method.
Regards,
Ken
--
Message: 3
Date: Wed, 07 May 2014 14:13:52 +0200
From: Uli Kusterer witness.of.teacht...@gmx.net
To: Quincey Morris quinceymor...@rivergatesoftware.com
Cc: Cocoa Dev List cocoa-dev@lists.apple.com
Subject: Re: How to convert a UTF-8 byte offset into an NSString
characteroffset?
Message-ID: ab2992a3-25bb-4335-97ed-21fedbf08...@gmx.net
Content-Type: text/plain; charset=windows-1252
On 06 May 2014, at 20:12, Quincey Morris
quinceymor...@rivergatesoftware.com wrote:
FWIW, my opinion is that if your library clients are specifying UTF-8
sequences at the API, and expect byte offsets into those sequences to be
meaningful, you might well be forced to maintain the original UTF-8 sequence
in the library’s internal data model — or, perhaps, an array of the original
code points — and do all of your internal processing in terms of code
points. Conversion to NSString would happen only in the journey from data
model to UI text field.
This is pretty much what I do in one of my projects. I hand-wrote code
Re: Help with Help
On May 7, 2014, at 6:53 AM, Bill Cheeseman wjcheese...@gmail.com wrote: As far as I know, the only comprehensive explanation of the new post-Snow Leopard version of Help Books is Chapter 11 of my book, Cocoa Recipes for Mac OS X, Second Edition (Peachpit Press 2010). I used Cheeseman’s book, and it did help a lot. Still, getting all the variables set in both the app’s and the HelpBook’s .plist files set up right can be a pain. One minor mistake and nothing seems to work. Also, the Help document is cached somewhere, so when I make a change, recompile, and test the new Help, the old cached version is typically loaded (not the new one). I’ve forgotten how to get rid of that cached HelpBook gracefully. I often just logout and log back in to reset it. Another challenge is making sure there are no syntax errors in your HTML. With just the tiniest error, hiutil will stop indexing it, and by default, it will stop quietly. Make sure you use the “-v” option to flag anything. Here are the steps I follow to index my system (at least for English). Watch the output of the first two hiutil commands carefully because (at least for me) this is where I find many of my mistakes. $ hiutil -Cavf /tmp/MyHelp.helpindex English.lproj $ hiutil -Fvf /tmp/MyHelp.helpindex $ cd English.lproj $ cp /tmp/MyHelp.helpindex . Todd signature.asc Description: Message signed with OpenPGP using GPGMail ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
The HTML in the app and on the website is slightly different, I use PHP to generate the HTML. A more modern approach would probably be to use a static site generator like Jekyll, which would allow you to use templates, write in Markdown, etc. You can use Markdown with PHP: https://github.com/michelf/php-markdown and possibly others to generate your static pages, too. Marc ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
On May 7, 2014, at 2:06 PM, Todd Heberlein wrote: On May 7, 2014, at 6:53 AM, Bill Cheeseman wjcheese...@gmail.com wrote: As far as I know, the only comprehensive explanation of the new post-Snow Leopard version of Help Books is Chapter 11 of my book, Cocoa Recipes for Mac OS X, Second Edition (Peachpit Press 2010). I used Cheeseman’s book, and it did help a lot. Still, getting all the variables set in both the app’s and the HelpBook’s .plist files set up right can be a pain. One minor mistake and nothing seems to work. Also, the Help document is cached somewhere, so when I make a change, recompile, and test the new Help, the old cached version is typically loaded (not the new one). I’ve forgotten how to get rid of that cached HelpBook gracefully. I often just logout and log back in to reset it. Shot in the dark, but If the help doc reference is a URL, is it possible to force an fresh load by tacking a ? on to the end of the URL when it is loaded and supplying no parameters? GL, - Alex ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
On May 7, 2014, at 12:00 PM, Kirk kirkkere...@gmail.com wrote: I further note that Apple's own iWork apps use online help pages that open in Safari. We use HTML and open Safari when user selects help. Great for our cross platform products. -koko ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
As somebody who did a lot of development work on early versions of Simple Help Editor, I’d like to point out a misstatement. It does not require one to write their own HTML. It does a quite capable job of translating styled text into HTML, but does offer the ability to handle custom HTML for things like tables, that don’t translate easily as styled text. I would agree that it can be a complex application if you want to get beyond the basics. On May 7, 2014, at 10:08 AM, Gordon Apple g...@ed4u.com wrote: I then tried the $150 (limited free trial) SimpleHelpEditor. It¹s a lot more capable, but complex, and you end up having to write all the HTML yourself anyway, so why bother? ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
On 30 Apr 2014, at 00:52, Gordon Apple g...@ed4u.com wrote: We would like to get a recommendation on the best way to generate a help system for a fairly complex application. You might also try techwrl-list, they're the experts on help systems: http://www.techwr-l.com/frequently-asked-questions.html#subscribe signature.asc Description: Message signed with OpenPGP using GPGMail ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help
It's best to use Apple's help. However, you may want to consider the case where your app supports a localization that Apple's Help app doesn't and give the user the option of opening your help pages in the user's web browser. In one app some time back, the help would show English while the user was running Turkish. That particular case may be workable now, but a similar one may occur. See how Apple does this in Xcode for their documentation viewer. -- Gary L. Wade (Sent from my iPhone) http://www.garywade.com/ On Apr 29, 2014, at 10:52 AM, Gordon Apple g...@ed4u.com wrote: We would like to get a recommendation on the best way to generate a help system for a fairly complex application. We started by using a simple web view and created about 120 screens in BBEdit, mostly drill-down outlines. Unfortunately, this has been proven to be difficult to maintain. We¹ve looked into web generators like RapidWeaver, Freeway, and even Dreamweaver, but all of these have been described as ³roach motels² where you enter but can never leave. We would like to have both local and web-based or web-updated content and have contextual help. This all brings us to Apple¹s ³Help Book², which seems to have been around forever and presents its own learning curve. So the question is: Is this the way to go? It it still current? What are the experiences in using it? ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
Re: Help with Help (AHLookupAnchor)
On Wed, 1 Jul 2009 12:02:16 +1000, Graham Cox graham@bigpond.com said: Hi all, I'm trying to link help buttons in my app to topics in my help book. I have a simple scheme where the (hidden) title of the button contains the anchor and I pass it to AHLookupAnchor. The help window opens as 'untitled' with a blank content, but AHLookupAnchor returns noErr (0). I have checked that the help book is indexed correctly and have verified that the anchors are listed using the Unarchiver tool and that the anchor I'm testing with is listed. Note that my help book shows up in the Help menu and can be opened from there and browsed normally. Any other ideas on what I might be doing wrong? My answer is not much help because I don't use AHLookupAnchor (I use AHGotoPage). But it occurs to me that it might be best to ask on the Apple Help Implementors list. Since you appear to be doing everything correctly, my first suggestion would be to clean out the help cache and restart the machine, because Help is notoriously touchy, and blank pages are a typical sign of its touchiness. I take it that anchor indexing is turned on in the Help Indexer prefs, right? But I recommend that you *uncheck* Use remote root because this is just the sort of thing that results in these blank hangs, while the Help tries to connect to the Internet for no reason at all... m. -- matt neuburg, phd = m...@tidbits.com, http://www.tidbits.com/matt/ A fool + a tool + an autorelease pool = cool! AppleScript: the Definitive Guide - Second Edition! http://www.tidbits.com/matt/default.html#applescriptthings ___ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
