Re: Help with Help
Re: Help with Help
- Subject: Re: Help with Help
- From: Gordon Apple <email@hidden>
- Date: Wed, 07 May 2014 12:08:04 -0500
- Thread-topic: 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" <email@hidden> 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 (email@hidden)
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:
This email sent to email@hidden