helpfile.txt

HELP文件格式定义清单说明

Inside help files Bitmaps and Metafiles are stored in lP- or lp-format. This
is the format of SHG/MRB files that SHED/MRBC produce and may contain multiple
pictures at different resolutions, each with optional additional hotspot data.
Pictures may be embedded in LinkData2 of |TOPIC or appear as |bm<x> files
(or bm<x> in case of Windows 3.0 HC30). Each picture starts with this header
data. The PictureOffset tells you where to look for the desired picture.

short Magic				  0x506C (SHG,lP) or 0x706C (MRB,lp)
short NumberOfPictures			  >1 if multi-resolution-bitmap
long PictureOffset[NumberOfPictures]	  relative to &Magic

You shouldn't depend on Magic lP/lp upon reading, as there are some MRBs
flagged like SHG, but please write correct values.

Seek to PictureOffset and you will find this:

char PictureType	   5=DDB 6=DIB 8=metafile
char PackingMethod	   0=uncompressed 1=RunLen 2=LZ77 3=both

If PictureType is 5 or 6 the picture is a bitmap described by:

compressed unsigned long Xdpi		    resolution in dpi, not PelsPerMeter
compressed unsigned long Ydpi		    resolution in dpi, not PelsPerMeter
compressed unsigned short Planes
compressed unsigned short BitCount
compressed unsigned long Width
compressed unsigned long Height
compressed unsigned long ColorsUsed
compressed unsigned long ColorsImportant    1 if bitmap is transparent
compressed unsigned long CompressedSize
compressed unsigned long HotspotSize	    0 if none are defined
unsigned long CompressedOffset		    relative to &PictureType
unsigned long HotspotOffset		    relative to &PictureType

If PictureType is 6 a color palette follows immediatly

COLORREF palette[ColorsUsed]		    or 1<<BitCount if ColorsUsed=0

If PackingMethod is 0 copy CompressedSize bytes starting at CompressedOffset
to retrieve the bitmap data. If PackingMethod is 1 seek to CompressedOffset,
and decode CompressedSize bytes using the RunLen algorithm:
  n=getc(f); if(n&0x80) copy n&0x7F bytes, else copy next byte n times.
If PackingMethod is 2 use the LZ77 algorithm described above and if Packing-
Method is 3 first use LZ77, then RunLen to decompress.

If PictureType is 8 the picture is a metafile described by:

compressed unsigned short MappingMode
unsigned short Width
unsigned short Height
compressed unsigned long DecompressedSize   can be used to allocate buffer
compressed unsigned long CompressedSize
compressed unsigned long HotspotSize	    0 if none are defined
unsigned long CompressedOffset		    relative to &PictureType
unsigned long HotspotOffset		    relative to &PictureType

Seek to CompressedOffset and decompress CompressedSize bytes as described
above to retrieve metafile data.

If HotspotSize or HotspotOffset is 0, no hotspots are defined. Otherwise
seek to HotspotOffset and retrieve HotspotSize bytes of hotspot definition
as declared below. Each macro hotspot contributes data to MacroData in a
way not fully understood at this moment.

unsigned char Always1
unsigned short NumberOfHotspots
unsigned long SizeOfMacroData
struct
{
    unsigned char id0,id1,id2;
    unsigned short x,y,w,h;
    unsigned long hash;
}
Hotspot[NumberOfHotspots]
char MacroData[SizeOfMacroData]       if SizeOfMacroData>0 the first byte
				      of MacroData is always 2.
struct
{
    STRINGZ HotspotName
    STRINGZ ContextNameOrMacro
}
StringData[NumberOfHotspots]

Possible values of id0,id1,id2 are:
0xC8 0x00 0x00	macro visible
0xCC 0x04 0x00	macro invisible
0xE2 0x00 0x00	popup jump visible
0xE3 0x00 0x00	topic jump visible
0xE6 0x04 0x00	popup jump invisible
0xE7 0x04 0x00	topic jump invisible
0xEA 0x00 0x00	popup jump into external file visible
0xEB 0x00 0x00	topic jump into external file / secondary window visible
0xEE 0x04 0x00	popup jump into external file invisible
0xEF 0x04 0x00	topic jump into external file / secondary window invisible

The hash field is only used if id0 = 0xE2, 0xE3, 0xE6, 0xE7. It is 1 if
id0 = 0xC8 or 0xCC.
The ContextNameOrMacro contains a macro if id0 = 0xC8 or 0xCC, otherwise
it contains a ContextName (id0 = 0xE2, 0xE3, 0xE6, 0xE7) or the complete
reference ContextName>Window@File (id0 = 0xEA, 0xEB, 0xEE, 0xEF) (@File
may be missing if target is in same file).

Annotation file format

An annotation file created by WinHelp uses the same basic file format as
a Windows help file. The first 16 bytes contain the same header as a help
file, with same Magic. DirectoryStart points to a FILEHEADER of an internal
directory formatted the same way as a help file internal directory. There
are just internal files of different name and format used to collect the
annotations.

@VERSION

The first internal file described contains (after the usual FILEHEADER) 6
bytes of version info:
0x08 0x62 0x6D 0x66 0x01 0x00	       (I've never seen other values)

@LINK

The @LINK internal file contains (after the usual FILEHEADER) the number of
annotations and the TOPICOFFSET of every annotation. The TopicOffset separates
into a TopicBlockNumber in it's upper bits and TopicBlockOffset pointing into
the decompression buffer in it's lower bits as explained above in the
description of the |TOPIC format and points the the first TOPICLINK following
the TOPICHEADER of the topic where the annotation belongs to.

unsigned short NumberOfAnnotations
struct
{
    unsigned long TopicOffset
    unsigned long Unknown1	  // always 0
    unsigned long Unknown2	  // always 0
}
AnnotationTopicRef[NumberOfAnnotations]

n!0

For each annotation the ANN file also carrys an internal file with a name like
12345!0, where 12345 is the decimal representation of the TopicOffset (as
listed in the @LINK array) where the annotation belongs to. These files
contain the annotation text as unformatted, uncompressed plain ANSI characters,
and are not NUL terminated.

That's all what I've seen in an annotation file.

*.CAC, *.AUX

Multimedia files using extensions *.CAC or *.AUX are formatted like helpfiles,
but contain only auxillary files, no |SYSTEM or |TOPIC.
Investigate them yourself. HELPDECO may be used to display or extract files
contained in them.

LZ77

You want to handle LZ77 compressed data in HLPs, MRBs, and SHGs yourself ?
Here is an algorithm to do it:

// LZ77 compression / decompression algorithm
// this is the compression Microsoft used in Windows *.HLP and *.MRB files

// so it works like Microsoft COMPRESS.EXE/EXPAND.EXE/LZEXPAND.DLL
//#define MSEXPAND

#include <stdio.h>
#include <stdlib.h>

#define N 4096
#define F 16
#define THRESHOLD 3

#define dad (node+1)
#define lson (node+1+N)
#define rson (node+1+N+N)
#define root (node+1+N+N+N)
#define NIL -1

char *buffer;
int *node;
int pos;

int insert(int i,int run)
{
    int c,j,k,l,n,match;
    int *p;

    k=l=1;
    match=THRESHOLD-1;
    p=&root[(unsigned char)buffer[i]];
    lson[i]=rson[i]=NIL;
    while((j=*p)!=NIL)
    {
	for(n=min(k,l);n<run&&(c=(buffer[j+n]-buffer[i+n]))==0;n++) ;
	if(n>match)
	{
	    match=n;
	    pos=j;
	}
	if(c<0)
	{
	    p=&lson[j];
	    k=n;
	}
	else if(c>0)
	{
	    p=&rson[j];
	    l=n;
	}
	else
	{
	    dad[j]=NIL;
	    dad[lson[j]]=lson+i-node;
	    dad[rson[j]]=rson+i-node;
	    lson[i]=lson[j];
	    rson[i]=rson[j];
	    break;
	}
    }
    dad[i]=p-node;
    *p=i;
    return match;
}

void delete(int z)
{
    int j;

    if(dad[z]!=NIL)
    {
	if(rson[z]==NIL)
	{
	    j=lson[z];
	}
	else if(lson[z]==NIL)
	{
	    j=rson[z];
	}
	else
	{
	    j=lson[z];
	    if(rson[j]!=NIL)
	    {
		do
		{
		    j=rson[j];
		}
		while(rson[j]!=NIL);
		node[dad[j]]=lson[j];
		dad[lson[j]]=dad[j];
		lson[j]=lson[z];
		dad[lson[z]]=lson+j-node;
	    }
	    rson[j]=rson[z];
	    dad[rson[z]]=rson+j-node;
	}
	dad[j]=dad[z];
	node[dad[z]]=j;
	dad[z]=NIL;
    }
}

void compress(FILE *f,FILE *out)
{
    int ch,i,run,len,match,size,mask;
    char buf[17];

    buffer=malloc(N+F+(N+1+N+N+256)*sizeof(int)); // 28.5 k !
    if(buffer)
    {
#ifdef MSEXPAND
	struct { long magic, magic2; int magic3; long filesize; } header;

	header.magic=0x44445A53L; // SZDD
	header.magic2=0x3327F088L;
	header.magic3=0x0041;
	header.filesize=filelength(fileno(f));
	fwrite(&header,sizeof(header),1,out);
#endif
	node=(int *)(buffer+N+F);
	for(i=0;i<256;i++) root[i]=NIL;
	for(i=NIL;i<N;i++) dad[i]=NIL;
	size=mask=1;
	buf[0]=0;
	i=N-F-F;
	for(len=0;len<F&&(ch=getc(f))!=-1;len++)
	{
	    buffer[i+F]=ch;
	    i=(i+1)&(N-1);
	}
	run=len;
	do
	{
	    ch=getc(f);
	    if(i>=N-F)
	    {
		delete(i+F-N);
		buffer[i+F]=buffer[i+F-N]=ch;
	    }
	    else
	    {
		delete(i+F);
		buffer[i+F]=ch;
	    }
	    match=insert(i,run);
	    if(ch==-1)
	    {
		run--;
		len--;
	    }
	    if(len++>=run)
	    {
		if(match>=THRESHOLD)
		{
#ifdef MSEXPAND
		    buf[size++]=pos;
		    buf[size++]=((pos>>4)&0xF0)+(match-3);
#else
		    buf[0]|=mask;
		    *(int *)(buf+size)=((match-3)<<12)|((i-pos-1)&(N-1));
		    size+=2;
#endif
		    len-=match;
		}
		else
		{
#ifdef MSEXPAND
		    buf[0]|=mask;
#endif
		    buf[size++]=buffer[i];
		    len--;
		}
		if(!((mask+=mask)&0xFF))
		{
		    fwrite(buf,size,1,out);
		    size=mask=1;
		    buf[0]=0;
		}
	    }
	    i=(i+1)&(N-1);
	}
	while(len>0);
	if(size>1) fwrite(buf,size,1,out);
	free(buffer);
    }
}

void expand(FILE *f,FILE *out)
{
    int bits,ch,i,j,len,mask;
    char *buffer;

#ifdef MSEXPAND
    struct { long magic, magic2; int magic3; long filesize; } header;

    i=fread(&header,1,sizeof(header),f);
    if(i!=sizeof(header)||header.magic!=0x44445A53L||header.magic2!=0x3327F088L||header.magic3!=0x0041)
    {
	fwrite(&header,1,i,out);
	while((ch=getc(f))!=-1) putc(ch,out);
	return;
    }
#endif
    buffer=malloc(N);
    if(buffer)
    {
	i=N-F;
	while((bits=getc(f))!=-1)
	{
	    for(mask=0x01;mask&0xFF;mask<<=1)
	    {
#ifdef MSEXPAND
		if(!(bits&mask))
		{
		    j=getc(f);
		    if(j==-1) break;
		    len=getc(f);
		    j+=(len&0xF0)<<4;
		    len=(len&15)+3;
#else
		if(bits&mask)
		{
		    j=getw(f);
		    len=((j>>12)&15)+3;
		    j=(i-j-1)&(N-1);
#endif
		    while(len--)
		    {
			putc(buffer[i]=buffer[j],out);
			j=(j+1)&(N-1);
			i=(i+1)&(N-1);
		    }
		}
		else
		{
		    ch=getc(f);
#ifndef MSEXPAND
		    if(ch==-1) break;
#endif
		    putc(buffer[i]=ch,out);
		    i=(i+1)&(N-1);
		}
	    }
	}
	free(buffer);
    }
}

That's all I can tell you about the format of Windows 3.x/95 help files.
If you found out more, please let me know.

M. Winterhoff
[e-mail]