/[ascend]/trunk/tcltk98/generic/interface/HelpProc.h
ViewVC logotype

Contents of /trunk/tcltk98/generic/interface/HelpProc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 67 - (show annotations) (download) (as text)
Wed Nov 30 16:31:29 2005 UTC (16 years, 5 months ago) by johnpye
File MIME type: text/x-chdr
File size: 11189 byte(s)
Standardised the "if seen" #defines to [ASC|ASCTK|ASCPY|ASCXX]_FILENAME_H
Fixed compile on FC3
1 /*
2 * HelpProc.h
3 * by Ben Allan
4 * Created: 4/97
5 * Version: $Revision: 1.9 $
6 * Version control file: $RCSfile: HelpProc.h,v $
7 * Date last modified: $Date: 2003/08/23 18:43:06 $
8 * Last modified by: $Author: ballan $
9 *
10 * This file is part of the ASCEND Tcl/Tk interface
11 *
12 * Copyright 1997, Carnegie Mellon University
13 *
14 * The ASCEND Tcl/Tk interface is free software; you can redistribute
15 * it and/or modify it under the terms of the GNU General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
18 *
19 * The ASCEND Tcl/Tk interface is distributed in hope that it will be
20 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with the program; if not, write to the Free Software Foundation,
26 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
27 * COPYING. COPYING is found in ../compiler.
28 */
29
30 /** @file
31 * Functions & macros for the Ascend Tcl/Tk help system.
32 * <pre>
33 * To include this header, you must include the following:
34 * #include "tcl.h"
35 * #include "utilities/ascConfig.h"
36 * </pre>
37 */
38
39 #ifndef ASCTK_HELPPROC_H
40 #define ASCTK_HELPPROC_H
41
42 /**
43 * The largest number of strings that will be used in building a long
44 * help string.
45 */
46 #define MAXHELPARGS 100
47 /** Token for end of help strings. */
48 #define HLFSTOP (char *)NULL
49
50 /**
51 * <!-- macro ASCUSE -->
52 * This macro should be inserted at the beginning of all existing
53 * and future ascend callbacks registered in TCL.
54 * It checks for the command option -help and returns the helpstring
55 * with the code TCL_OK if -help is found. If -help is not found,
56 * this does nothing.
57 * All ASCEND callbacks should be written using the standard arguments
58 * ClientData cdata, Tcl_Interp *interp, int argc, char *argv[].
59 * This macro insists on it.
60 */
61 #define ASCUSE \
62 if (Asc_HelpCheck(cdata,interp,argc,argv) != TCL_OK) { return TCL_OK; }
63
64 /**
65 * Prototype for a function which returns a char *
66 * containing the long form help for a command.
67 * provide: char *myfunc(void) to HelpDefine
68 * The returned char * should be created with ascmalloc, because we
69 * will ascfree it eventually.
70 */
71 typedef char *(*HLFunc)(void);
72
73 /**
74 * Defines a help function using an arbitrary number of strings.
75 *
76 * To get past the string literal limits of compilers,
77 * use the following macro in your .c file like so:
78 * <pre>
79 * STDHLF(yourCmd,(your,list,of,macro,strings,HLFSTOP)) \* ; *\
80 * </pre>
81 * Then you can pass yourCmdHLF into the registration of your command.
82 * Generally, each option of a command with many options should get
83 * its own macro string. The ANSI limit on such strings is 509 chars.
84 * Use STDHLF_H(yourCmd); in your header file to define your function.<br><br>
85 *
86 * This macro is evil because it uses nonstandard-looking syntax
87 * to get past the C preprocessor without errors. (Missing ; in use and
88 * missing () in definition).
89 */
90 #define STDHLF(baseName,list_of_strings_in_parens_end_in_null) \
91 char * baseName##HLF(void) \
92 { \
93 char *result; \
94 result = HelpBuildString list_of_strings_in_parens_end_in_null ; \
95 return result; \
96 } extern int g_does_not_exist_so_do_not_use /* hack to use a ; after\} */
97
98 /**
99 * Macro to make a header declaration for your function made with HLF.
100 */
101 #define STDHLF_H(baseName) extern char *baseName##HLF(void)
102
103 extern char *HelpBuildString(char *first, ...);
104 /**<
105 * <!-- HelpBuildString(char *, variable_number_of_args,NULL); -->
106 * Builds a long string from an arbitrary number of input strings
107 * so long as the last string is NULL and the first is not.
108 * All arguments must be strings (char *).
109 * The string returned is the callers responsibility to free.
110 * Up to the first MAXHELPARGS are used in the returned string.
111 */
112
113 extern int Asc_HelpCheck(ClientData cdata, Tcl_Interp *interp,
114 int argc, CONST84 char **argv);
115 /**<
116 * <!-- Asc_HelpCheck(cdata,interp,argc,argv); -->
117 * Returns TCL_BREAK if a help message is printed to the interpreter
118 * or TCL_OK if not.
119 * If this functions returns TCL_BREAK, the caller should return.
120 */
121
122 extern int Asc_HelpInit(void);
123 /**<
124 * Initializes the help data structures so that commands can then
125 * be registered.
126 */
127
128 extern int Asc_HelpDestroy(void);
129 /**<
130 * Destroys the help data structures. This should only be called at
131 * shutdown.
132 */
133
134 extern int Asc_HelpDefineGroup(CONST char *froup, CONST char *explanation);
135 /**<
136 * <!-- Asc_HelpDefineGroup(group,explanation) -->
137 * <!-- CONST char *group, *explanation; -->
138 * Defines the generic description for the command group given.
139 * explanation should start with Explanation:
140 * group should not contain whitespace.
141 * Follows tcl return conventions.
142 */
143
144 extern int Asc_HelpDefine(CONST char *name,
145 CONST char *group,
146 CONST char *usage,
147 CONST char *desc,
148 HLFunc longfunc);
149 /**<
150 * <!-- Asc_HelpDefine(name,group,usage,desc,longfunc) -->
151 * <!-- CONST char *name, *group, *usage, *desc; -->
152 * <!-- char * HLFunc(void); -->
153 * Defines the help strings for the command name given.
154 *
155 * All the strings given should be static strings, because we may
156 * store pointers to them.
157 * HLFunc should return a string that we become the owner of, or NULL.
158 * All 5 parameters should be coming via defines in the
159 * C header files for the function being documented.
160 * See Asc_HelpCmd() for an example of same.<br><br>
161 *
162 * If you have not written up someplace else the information that
163 * is required here, you obviously have not thought the command you
164 * are registering through and you should not be registering it.
165 *
166 * @param name The tcl registration string.
167 * @param group The command group name. It should not contain whitespace.
168 * @param usage The command syntax by example or in man page style.
169 * @param desc The basic one-line description of the command. (<= 70 char)
170 * @param longfunc Function returning the detailed explanation of the command.
171 */
172
173 extern CONST char *Asc_HelpGetShort(Tcl_Interp *interp, CONST84 char *commandname);
174 /**<
175 * <!-- Asc_HelpGetShort(interp,commandname) -->
176 * Returns the short string for the command given, if there is one.
177 * If interp is not NULL, also appends the returned string to the
178 * interpreter's result string.
179 */
180
181 extern CONST char *Asc_HelpGetLong(Tcl_Interp *interp, CONST84 char *commandname);
182 /**<
183 * <!-- Asc_HelpGetLong(interp,commandname) -->
184 * Returns the long string for the command given, if there is one.
185 * If interp is not NULL, also appends the returned string to the
186 * interpreter's result string.
187 */
188
189 extern CONST char *Asc_HelpGetUsage(Tcl_Interp *interp, CONST84 char *commandname);
190 /**<
191 * <!-- Asc_HelpGetUsage(interp,commandname) -->
192 * Returns the usage string for the command given, if there is one.
193 * If interp is not NULL, also appends the returned string to the
194 * interpreter's result string.
195 */
196
197 extern int Asc_HelpGetGroup(Tcl_Interp *interp, CONST84 char *groupname);
198 /**<
199 * <!-- Asc_HelpGetGroup(interp,groupname) -->
200 * Returns the members of a group, and the group explanation
201 * if there is one, in the interpreter.
202 * All is in a list format and the explanation is first
203 * if it exists. If group does not exist, returns an error message.
204 * By use convention: the group explanation is a list element which
205 * starts with "Explanation".
206 * The return code follows TCL conventions.
207 */
208
209 extern int Asc_HelpCommandGroups(Tcl_Interp *interp);
210 /**<
211 * <!-- Asc_HelpCommandGroups(interp) -->
212 * Appends the complete list of groups to the interpreter.
213 * Commands are sorted in some reasonable fashion.
214 * The return code follows TCL conventions.
215 */
216
217 extern int Asc_HelpCommandList(Tcl_Interp *interp);
218 /**<
219 * <!-- Asc_HelpCommandList(interp) -->
220 * Appends the complete list of commands to the interpreter.
221 * Commands are sorted in alphabetical order.
222 * The return code follows TCL conventions.
223 */
224
225 extern int Asc_HelpCommandsByGroups(Tcl_Interp *interp);
226 /**<
227 * <!-- Asc_HelpCommandsByGroups(interp) -->
228 * Appends the complete list of commands to the interpreter.
229 * Groups are sorted and then commands are sorted in alphabetical order.
230 * The return code follows TCL conventions.
231 */
232
233 STDHLF_H(Asc_HelpCmd);
234 /**< Function returning our long help string. */
235
236 extern int Asc_HelpCmd(ClientData cdata, Tcl_Interp *interp,
237 int arcg, CONST84 char **argv);
238 /**<
239 * <!-- Asc_HelpCmd(cdata,interp,argc,argv); -->
240 * This is the tcl callback for our commandline help facility.
241 */
242
243 /** Registered as */
244 #define Asc_HelpCmdHN "help"
245 /** Usage */
246 #define Asc_HelpCmdHU \
247 "help [commandname] OR help help"
248 /** Short help text */
249 #define Asc_HelpCmdHS \
250 "returns information on C functions ASCEND defines as Tcl commands"
251 /** Long help text part 1. */
252 #define Asc_HelpCmdHL1 \
253 "\
254 * Returns help on a registered command name, or command group name,\n\
255 * or the list of commands alphabetized or the list groups alphabetized,\n\
256 * or the list of commands alphabetized by groups.\n\
257 * For help on specific commands you can also try: <commandname> -h\n\
258 * Most of our callbacks supply their own help.\n\
259 "
260 /** Long help text part 2. */
261 #define Asc_HelpCmdHL2 \
262 "\
263 *\n\
264 * help examples:\n\
265 * help -h returns a short definition & UNIX man page style syntax.\n\
266 * help -H returns a long explanation\n\
267 * help help returns this text.\n\
268 "
269 /** Long help text part 3. */
270 #define Asc_HelpCmdHL3 \
271 "\
272 * help system returns the description of the system group.\n\
273 * help groups returns the alphabetized list of group names.\n\
274 * help all returns the alphabetized list of commands.\n\
275 * help commands returns the alphabetized listing of groups.\n\
276 *\n\
277 "
278 /** Long help text part 4. */
279 #define Asc_HelpCmdHL4 \
280 "\
281 * All output is to the tcl interpreter in the form of list elements.\n\
282 * For better formatted help output, use Help which has the same\n\
283 * syntax as this command but writes the output more neatly to stdout.\n\
284 "
285 /*
286 * If we follow the style above for all our tcl callback headers we
287 * end up with better documented tcl callbacks in C and consistent
288 * runtime help.
289 * The pattern is to define 3 macros in the pattern
290 * nameHN, nameHU, nameHS, and function nameHLF via the macro STDHLF
291 * above.
292 * In this example name is Asc_HelpCmd.
293 */
294
295 #endif /* ASCTK_HELPPROC_H */
296

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22