Help file creation

General
#1

Where in the Xojo documentation is the subject of help file creation?

#2

I don’t think anywhere because it’s not directly related to Xojo.

I’m sure there’s many different approaches, but what I do - cross-platform - is:

  1. Create an HTML hierarchy, just like a Web ‘area’.

  2. For Windows, I use the old HTML Help Workshop by Microsoft and create an index file that mimics the “table of contents” that the Web ‘area’ works under. I compile and get a .chm file.

  3. For Mac, I simply copy the .html structure into folder structure: English.lproj/documentation within the Resources folder of the app bundle.

To open the Help Files on Mac and Windows, I use this code. ‘f’ is the folder that the .chm file (Win) or the index.html (Mac) file is in.

[code]Sub OpenHelpFile(f As FolderItem)

#if TargetWin32 Then

f.Launch

#else

Dim ItemStr as String
Dim sh As Shell

ItemStr = Chr(39) + f.ShellPath + Chr(39)
ItemStr = ReplaceAll(ItemStr, "\", "")

sh = New Shell
sh.Execute "open -b com.apple.helpviewer " + ItemStr

#endif

End Sub
[/code]

  1. For the PDF, this is a bit harder. I create a document in Adobe InDesign (one could use Word too I guess) and copy the text and graphics from the HTML pages and format it so it looks great. I then make the PDF.

So for updating the documentation, I make sure I do the Web area and the InDesign document in parallel, updating BOTH as I go along. Then I create the PDF again, recompile the .chm in HTML HelpWorkshop, and move the Web area over to the Mac.

I wish I didn’t have to do the parallel updating of the PDF and Web area, but the design needs of a PDF are drastically different than a Web page. I don’t even think it’s possible to have a program that does both - there are that exist - which formats the PDF in the way I would like it seen.

Regardless, I think it’s a great system that makes great looking Help documents and in a system where I can maintain them quite easily.

#3

On Windows, see CHM generators http://alternativeto.net/software/robohelp/

#4

Take a look at “Answers” …
https://forum.xojo.com/16248-answers-1-0-5-the-long-awaited-update-where-you-can-add-images
http://nswrs.com/

#5

While this still works, Apple have advised users to create Help Books instead, since OS X 10.6 and as Apple seem to be on the drive to flush out old functionality…

I’ve added a function in the forthcoming App Wrapper update to take simple HTML folders and to build Apple Help Books from them. Otherwise you can manually build a help book by checking out the documentation on Apple’s developer site. Sorry I don’t have the links to hand.

#6

That will be great. So one can use Answers or any hTML editor to build the site, and then App Wrapper will turn it into an Apple Help Book ?

Will users of AW 2.5 be able to update/upgrade to 3.00 ?

#7

Very appreciated feature, worth every price.

#8

Yes, there will be a time limited discount allowing anyone who purchased App Wrapper before to upgrade. If you purchased App Wrapper this month, contact me and I’ll provide a free upgrade.

More information will be released next week.

#9

Garth,

If I use your code I get an error message: “An exception of class NilObjectException was not ahndled. he application must shut down”.

I am using a Mac. Any ideas why this would occur?

#10

Thats sounded great. But the post was 2014, I have App Wrapper, and I cant find that function.
Did it not make it to the build or am I just not seeing it?

#11

It’s there, simply drag your HTML help folder into the help section and fill in some details and click build.

#12

That’s what I do with the customers’ requirements. Just throw the whole story in the navigator and click Build.

#13

There’s some advantages to using the Apple Help system:

  1. Using the right declares it displays the help in the standard Apple Help Viewer.
  2. Is searchable from the “Help” menu and also the Help Viewer (even when opened from a separate application).

Unfortunately there is a huge disadvantage in modern versions of the macOS:

  • The OS will cache the help in a undisclosed location (which they change with almost every OS release), and it’s a hit or miss affair whether the user will get the current help or old help. Even restarting doesn’t help.

I’ve tried over the years to keep up with Apple’s changes to the help system, but even I’ve lost patience and as I’ve seen several “Promoted” apps on the App Store that don’t use the Apple help. I myself also don’t anymore.

Right now my solution isn’t that great as it requires an internet connection, but I will change that over time.

#14