Help Files on the Pocket PC [Archive]

View Full Version : Help Files on the Pocket PC

Jason Dunn

08-12-2003, 11:00 AM

Marcelo Bona Boff, a Pocket PC Thoughts reader who's working on a project for school involving Pocket PCs, asked me to post the question below. It brings up an interesting point - are help files on the Pocket PC very helpful? I have to admit that I never look at them, largely because they're usually so useless. A flat data file can only be so useful. Marcelo aims to possibly change that by creating a help file format that supports a table of contents, index, and search functions. The question below is aimed at developers, since they're the ones who would chose to use this in their applications.

rhmorrison

08-12-2003, 12:17 PM

It brings up an interesting point - are help files on the Pocket PC very helpful? I have to admit that I never look at them, largely because they're usually so useless. A flat data file can only be so useful. Marcelo aims to possibly change that by creating a help file format that supports a table of contents, index, and search functions.
What FLAT DATA FILE are you referring to?

The help file for PocketPC is a HTML file with the ability to designate the end of a topic. You can create your own index and table of contents by using HTML links and the Help Search function will find any topics keywords that contain the search expression (NOT however in the help text itself).

What MIGHT be helpful is a preprocessor (could be an AWK, or PERL script. or a program) that automatically generates and index and Table of Contents based on the topics. If you are interested I can send you a sample of how my preliminary help file for my "RHM Mühle" program that I am currently developing. Each page (except for the Table of Contents) has a link at the top "RHM Mühle" and the bottom "Table of Contents" that both jump to the Table of Contents page.

I suspect that the ONLY REASON that you think that PocketPC help files are a flat file format is because a lot of developers don't bother to define individual topic section so the user can scroll through the whole file but this is usually only the case for very small help files. For example my "Table of Contents' page and "Origins" pages are as follows:
<A NAME="Main_Contents"></A>RHM Mühle - Table of Contents
<ul type="square">
<li>Mühle: <A HREF="RHM Mühle.htm#origins">Origin</A>, <A HREF="RHM Mühle.htm#rules">Rules</A>, <A HREF="RHM Mühle.htm#playing">Playing</A></li> 
<li>GAMES: <A HREF="RHM Mühle.htm#loading">Load</A>, <A HREF="RHM Mühle.htm#saving">Save</A>, <A HREF="RHM Mühle.htm#details">Details</A></li>
<li>SETUP: <A HREF="RHM Mühle.htm#setup">Board</A>, <A HREF="RHM Mühle.htm#options">Options</A></li>
<li>SKINS: <A HREF="RHM Mühle.htm#skins">Select</A>, <A HREF="RHM Mühle.htm#make_skins">Create</A></li> 
<li><A HREF="RHM Mühle.htm#history">History</A></li>
<li><A HREF="RHM Mühle.htm#credits">Credits</A></li>
</ul>
 
 
<HR>

<A NAME="origins"></A><A HREF="RHM Mühle.htm#Main_Contents">RHM Mühle</A> - Origin of the Game
Mühle has to be a contender as one of the world's oldest board games
still being played today. Archaeological evidence has been found in ancient Egypt, Israel, Troy, Ireland,
Norway - even on a 1000 year old Viking burial ship - to name just a few places
in the world where this game was played. It has been speculated that perhaps
Greek or Phoenician traders introduced the game to Northern Europe, while
others indicate that Arabic people from North Africa may have introduced the
game into southern Europe.

The game has many related names in different languages - Mill, Morris, or
Nine Men's Morris games in English, Mérelles in French, Morels in Spanish,
Mühle in German, and Mølle in Norwegian to name a few. 

Some scholars indicated that the name of the game may have come from an Old French
word "merel" - the word for coin or counter (marker). The word "morris" is thought to be a
slur of the original French word. A second theory is that the name may be a
corruption of the word "Moor" - the name of the Arabic people from North Africa
who may have introduced the game into southern Europe.

<A HREF="RHM Mühle.htm#Main_Contents">Table of Contents</A>
 
 
<HR>


A simple MACRO capability that could be implemented in any script language (I'm a big fan of AWK) would allow supporting a common header/footer, index, and a Table of Contents (although I think it is easier to build a useful Table of Contents by hand).

Peter Foot

08-12-2003, 12:20 PM

Windows CE help files do already support contents pages and keyword Find functionality, however some work is required to implement it by getting down and dirty with the html file.
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnppc2k2/html/WinCEHelp.asp
If all you create is a linear html page for help then you are missing out some of the fun and games you can have by defining topics, contents lists and keywords which the built in help viewer (peghelp.exe) sorts out behind the scenes to give a richer help experience. The advantage of using the built in viewer is that there is no reader to distribute, register file types etc.
Perhaps what is required is an easier editor to create help files in the correct format for peghelp - like the help workshop available to create desktop help files.

pocketsetup

08-12-2003, 01:38 PM

The new help file format I have created has some features that the actual Peghelp doesn't have:
1. It is compressed. The compiler compresses all help topics (HTML files) and images in an unique help file using the LZO compression method (like HTMLHelp).
2. It has a table of contents like HTMLHelp or WinHelp (with a tree view), that is easier to navigate than a HTML based table of contents.
3. It has an index, like HTMLHelp/WinHelp, with a list of keywords.
4. The compilers generates a digital searching tree that allows the user search any word or phrase inside the topics.

This help file format would be very useful since the final help file (with table of contents, keywords and seraching tree) is smaller than a Peghelp help file, because it is compressed.

You can download the viewer for Pocket PC (ARM processor) at (it is only 35kb):
http://www.e-pocketsetup.com/pockethelp/PHViewer_PPC.STRONGARM.cab

And, you can download a compiled help file sample at:
http://www.e-pocketsetup.com/pockethelp/PocketHelp.phh

Install the viewer in your Pocket PC and then copy the help file to your device. Click the help file in the File Explorer and it will open the viewer.

Bandito

08-12-2003, 02:53 PM

Why not just write something that can read CHM files? These files are all over the place, included with every MS product, and meet all your requirements. Plus, you're not reinventing the wheel. Team One Reader handles CHMs, though not extremely well. This would also provide compatibility with the desktop, rather than supporting yet another Proprietary Pocket format (.PSW anyone?)

rhmorrison

08-12-2003, 03:01 PM

And, you can download a compiled help file sample at:
http://www.e-pocketsetup.com/pockethelp/PocketHelp.phh

Install the viewer in your Pocket PC and then copy the help file to your device. Click the help file in the File Explorer and it will open the viewer.
I have looked at your PocketHelp 1.2 and have a few comments...

PRO: Tree TOC looks very nice Keyword Index is also useful SEARCH function is very nice
CON: Help file not listed in master HELP list MUST install seperate viewer
I would have to compare the resulting help files to see what the size advantage is for PocketHelp.

Some questions:
Are any pictures also compressed and embedded in the help file or are they seperate .2bp files like for PocketPC Help? Can it be invoked with a topic like the normal Help to jump directly to a specific topic?
I noticed that if you open all the nodes and then double tap on a help topic that the next time that you open the tree that ONLY the node that was double tapped is open and all other nodes are closed. Is this a 'bug' or a 'feature'?

kagayaki1

08-12-2003, 04:41 PM

I'm a little concerned that with big help files, the standard index and search features could really slow down the device.

For me, I'd rather focus on making the help section more intuitive to find. Perhaps some kind of icon that came up in the top bar when a program was active. I can't count the number of times the credibility in my faith of the PPC platform has been dashed by telling someone, "if you need help, you have to tap Start, and then Help."

Their response: "That's not very obvious. Thanks! I probably never would have found that without your help..." Uh, yeah, but MS thinks you should be able to. :roll:

rhmorrison

08-12-2003, 04:48 PM

For me, I'd rather focus on making the help section more intuitive to find. Perhaps some kind of icon that came up in the top bar when a program was active. I can't count the number of times the credibility in my faith of the PPC platform has been dashed by telling someone, "if you need help, you have to tap Start, and then Help."

Their response: "That's not very obvious. Thanks! I probably never would have found that without your help..." Uh, yeah, but MS thinks you should be able to. :roll:
You can do this yourself. I have a Help Menu in my Program with Help and About... menu items. You could also add a help button to your command bar, of course, you must realize that doing either of these things will prevent you from ever obtaining PocketPC certification for your program from Microsoft! The same goes for having a File - Exit (or in my case a Game - Exit) menu item.

Peter Foot

08-12-2003, 05:20 PM

I have a Help Menu in my Program with Help and About... menu items. You could also add a help button to your command bar, of course, you must realize that doing either of these things will prevent you from ever obtaining PocketPC certification for your program from Microsoft!

I think this requirement of the logo guidelines will have to be relaxed - especially as it is not possible to trap the Start > Help tap for .NET Compact Framework applications. One approach which is fairly intuitive (and yes Microsoft uses it themselves) is on the Email Account wizard in the Inbox application. In the top right hand corner there is a ? button which lauches context sensitive help for the current screen.

rhmorrison

08-12-2003, 05:40 PM

BudPritchard

08-12-2003, 06:07 PM

What is nice about Peghelp is you can create a help file on a storage card so that space on the PPC isn't used.
For example, I created my own help file for Pocket Informant. Created a folder on my storage card and used
\cf card\PI\PocketInformant.htm on all href tags. Works great.

Was using a regular editor to create the html help file until I found this program: HTML-KIT (http://www.chami.com/html-kit/)

The link file in the Help folder points to the help file on the storage card.
Works fine when tapped on in \start\help.

However, tapping \start\help when PI is active gives an error message that the Main contents tag cannot be found in Windows\PocketInformant.htm.

Fixed by moving the original help file back into the Windows folder and updating it with a href tag to the storage card.

The same thing happens if img src tags use \cf card\PI\image.2bp.
Pephelp appends "Windows\" in these cases causing not found conditions.
Any images that you would use, needs to be in the windows folder.
Images aren't recommended for help files since they eat up storage space.

Used IE to test the hyperlinks in a cf\PI folder on my C: drive that contained the Help file.

pocketsetup

08-12-2003, 06:12 PM

Are any pictures also compressed and embedded in the help file or are they seperate .2bp files like for PocketPC Help?

Yes, the image files are compressed and embedded in the help file. It also supports 2bp, gif and jpeg.

Can it be invoked with a topic like the normal Help to jump directly to a specific topic?

To jump to a specific topic, just call the viewer (PHViewer.exe) with the help file as the first parameter and the topic's name you want as the second parameter.
If the help viewer is already opened, it just activates the viewer and then changes the active topic.
You need to define an unique topic name for each topic.

Why not just write something that can read CHM files?

Since CHM files specification is not opened, I cannot develop a viewer that completely supports this help file format.
Also, the specification of this new help file format will be open (every one will be able to access the file specification).

I noticed that if you open all the nodes and then double tap on a help topic that the next time that you open the tree that ONLY the node that was double tapped is open and all other nodes are closed. Is this a 'bug' or a 'feature'?

No, it isn't a bug. :D

Peter Foot

08-12-2003, 07:25 PM

I think this requirement of the logo guidelines will have to be relaxed - especially as it is not possible to trap the Start > Help tap for .NET Compact Framework applications.
WHY NOT, it's just the WM_HELP message! The same as if the user pressed the F1 key on a Windows PC.

Because a Compact Framework form gobbles the system messages itself, and unlike the full framework you cannot override the message loop. Agreed that its a really simple thing to implement, and something I campaigned for throughout the Compact Framework beta :cry:

ctmagnus

08-13-2003, 04:52 AM

rhmorrison

08-13-2003, 04:41 PM

I'm a little concerned that with big help files, the standard index and search features could really slow down the device.
WHY should this effect anything?