1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
/*
* winhelp.h header file for winhelp.c
*/
typedef struct WHLP_tag *WHLP;
typedef struct WHLP_TOPIC_tag *WHLP_TOPIC;
/*
* Initialise a new WHlp context and begin accumulating data in it.
*/
WHLP whlp_new(void);
/*
* Close a WHlp context and write out the help file it has created.
*/
void whlp_close(WHLP h, char *filename);
/*
* Abandon and free a WHlp context without writing out anything.
*/
void whlp_abandon(WHLP h);
/*
* Specify the title and copyright notice of a help file. Also
* specify Help macros to be run on loading.
*/
void whlp_title(WHLP h, char *title);
void whlp_copyright(WHLP h, char *copyright);
void whlp_start_macro(WHLP h, char *macro);
/*
* Register a help topic. Irritatingly, due to weird phase-order
* issues with the whole file format, you have to register all your
* topics _before_ actually outputting your text. This seems likely
* to require two passes over the source document.
*
* If you want to specify a particular context string (for
* reference from other programs, to provide context-sensitive
* help), you can supply it here. Otherwise, just pass NULL and a
* nondescript one will be allocated automatically.
*
* If you specify two context strings which clash under the Windows
* help file hash algorithm, this function will return NULL and
* provide a pointer to the other context string that this one
* clashed with, and you must tell your user to fix the clash.
* Sadly this is the only way to do it; despite HLP files having a
* perfectly good method of mapping arbitrary strings to things,
* they didn't see fit to use that method for help contexts, so
* instead they hash the context names and expect the hashes to be
* unique. Sigh.
*
* On success (i.e. in any circumstance other than a hash clash), a
* valid WHLP_TOPIC is returned for later use.
*/
WHLP_TOPIC whlp_register_topic(WHLP h, char *context_name, char **clash);
/*
* After calling whlp_register_topic for all topics, you should
* call this, which will sort out all loose ends and allocate
* context names for all anonymous topics. Then you can start
* writing actual text.
*/
void whlp_prepare(WHLP h);
/*
* Call this if you need the id of a topic and you don't already
* know it (for example, if whlp_prepare has allocated it
* anonymously for you). You might need this, for example, in
* creating macros for button-bar bindings.
*
* The string returned will be freed when the WHLP context is
* closed. You should not free it yourself.
*
* Do not call this before calling whlp_prepare().
*/
char *whlp_topic_id(WHLP_TOPIC topic);
/*
* Call this to specify which help topic will be the first one
* displayed when the help file is loaded.
*/
void whlp_primary_topic(WHLP h, WHLP_TOPIC topic);
/*
* Call this when about to begin writing out the text for a topic.
*
* Any additional arguments are Help macros, terminated with a
* NULL. So the minimum call sequence is
*
* whlp_begin_topic(helpfile, mytopic, "Title", NULL);
*/
void whlp_begin_topic(WHLP h, WHLP_TOPIC topic, char *title, ...);
/*
* Routines to output paragraphs and actual text (at last).
*
* You should start by calling whlp_para_attr() to set any
* paragraph attributes that differ from the standard settings.
* Next call whlp_begin_para() to start the paragraph. Then call
* the various in-paragraph functions until you have output the
* whole paragraph, and finally call whlp_end_para() to finish it
* off.
*/
enum {
WHLP_PARA_SPACEABOVE=1, WHLP_PARA_SPACEBELOW, WHLP_PARA_SPACELINES,
WHLP_PARA_LEFTINDENT, WHLP_PARA_RIGHTINDENT, WHLP_PARA_FIRSTLINEINDENT,
WHLP_PARA_ALIGNMENT
};
enum {
WHLP_ALIGN_LEFT, WHLP_ALIGN_RIGHT, WHLP_ALIGN_CENTRE
};
enum {
WHLP_FONT_TITLE, WHLP_FONT_NORMAL, WHLP_FONT_ITALIC, WHLP_FONT_FIXED
};
enum {
WHLP_PARA_SCROLL, WHLP_PARA_NONSCROLL
};
void whlp_para_attr(WHLP h, int attr_id, int attr_param);
void whlp_begin_para(WHLP h, int para_type);
void whlp_end_para(WHLP h);
void whlp_set_font(WHLP h, int font_id);
void whlp_text(WHLP h, char *text);
|
