generic/interface/HelpProc.h

/*
 *  HelpProc.h
 *  by Ben Allan          
 *  Created: 4/97
 *  Version: $Revision: 1.9 $
 *  Version control file: $RCSfile: HelpProc.h,v $
 *  Date last modified: $Date: 2003/08/23 18:43:06 $
 *  Last modified by: $Author: ballan $
 *
 *  This file is part of the ASCEND Tcl/Tk interface
 *
 *  Copyright 1997, Carnegie Mellon University
 *
 *  The ASCEND Tcl/Tk interface is free software; you can redistribute
 *  it and/or modify it under the terms of the GNU General Public License as
 *  published by the Free Software Foundation; either version 2 of the
 *  License, or (at your option) any later version.
 *
 *  The ASCEND Tcl/Tk interface is distributed in hope that it will be
 *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with the program; if not, write to the Free Software Foundation,
 *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
 *  COPYING.  COPYING is found in ../compiler.
 */

/** @file
 *  Functions & macros for the Ascend Tcl/Tk help system.
 *  <pre>
 *  To include this header, you must include the following:
 *      #include "tcl.h"
 *      #include "utilities/ascConfig.h"
 *  </pre>
 */

#ifndef ASCTK_HELPPROC_H
#define ASCTK_HELPPROC_H

/**
 * The largest number of strings that will be used in building a long
 * help string.
 */
#define MAXHELPARGS 100
/** Token for end of help strings. */
#define HLFSTOP (char *)NULL

/**
 *  <!--  macro ASCUSE                                                 -->
 *  This macro should be inserted at the beginning of all existing
 *  and future ascend callbacks registered in TCL.
 *  It checks for the command option -help and returns the helpstring
 *  with the code TCL_OK if -help is found. If -help is not found,
 *  this does nothing.
 *  All ASCEND callbacks should be written using the standard arguments
 *  ClientData cdata, Tcl_Interp *interp, int argc, char *argv[].
 *  This macro insists on it.
 */
#define ASCUSE \
  if (Asc_HelpCheck(cdata,interp,argc,argv) != TCL_OK) { return TCL_OK; }

/**
 * Prototype for a function which returns a char *
 * containing the long form help for a command.
 * provide: char *myfunc(void) to HelpDefine
 * The returned char * should be created with ascmalloc, because we
 * will ascfree it eventually.
 */
typedef char *(*HLFunc)(void);

/**
 * Defines a help function using an arbitrary number of strings.
 *
 * To get past the string literal limits of compilers,
 * use the following macro in your .c file like so:
 * <pre>
 * STDHLF(yourCmd,(your,list,of,macro,strings,HLFSTOP)) \* ; *\
 * </pre>
 * Then you can pass yourCmdHLF into the registration of your command.
 * Generally, each option of a command with many options should get
 * its own macro string. The ANSI limit on such strings is 509 chars.
 * Use STDHLF_H(yourCmd); in your header file to define your function.<br><br>
 *
 * This macro is evil because it uses nonstandard-looking syntax
 * to get past the C preprocessor without errors. (Missing ; in use and
 * missing () in definition).
 */
#define STDHLF(baseName,list_of_strings_in_parens_end_in_null) \
char * baseName##HLF(void) \
{ \
  char *result; \
  result = HelpBuildString list_of_strings_in_parens_end_in_null ; \
  return result; \
} extern int g_does_not_exist_so_do_not_use /* hack to use a ; after\} */

/**
 * Macro to make a header declaration for your function made with HLF.
 */
#define STDHLF_H(baseName) extern char *baseName##HLF(void)

extern char *HelpBuildString(char *first, ...);
/**<
 * <!--  HelpBuildString(char *, variable_number_of_args,NULL);        -->
 * Builds a long string from an arbitrary number of input strings
 * so long as the last string is NULL and the first is not.
 * All arguments must be strings (char *).
 * The string returned is the callers responsibility to free.
 * Up to the first MAXHELPARGS are used in the returned string.
 */

extern int Asc_HelpCheck(ClientData cdata, Tcl_Interp *interp, 
                         int argc, CONST84 char **argv);
/**<
 * <!--  Asc_HelpCheck(cdata,interp,argc,argv);                        -->
 * Returns TCL_BREAK if a help message is printed to the interpreter
 * or TCL_OK if not.
 * If this functions returns TCL_BREAK, the caller should return.
 */

extern int Asc_HelpInit(void);
/**<
 *  Initializes the help data structures so that commands can then
 *  be registered.
 */

extern int Asc_HelpDestroy(void);
/**<
 *  Destroys the help data structures. This should only be called at
 *  shutdown.
 */

extern int Asc_HelpDefineGroup(CONST char *froup, CONST char *explanation);
/**<
 *  <!--  Asc_HelpDefineGroup(group,explanation)                       -->
 *  <!--  CONST char *group, *explanation;                             -->
 *  Defines the generic description for the command group given.
 *  explanation should start with Explanation:
 *  group should not contain whitespace.
 *  Follows tcl return conventions.
 */

extern int Asc_HelpDefine(CONST char *name, 
                          CONST char *group, 
                          CONST char *usage,
                          CONST char *desc, 
                          HLFunc longfunc);
/**<
 *  <!--  Asc_HelpDefine(name,group,usage,desc,longfunc)               -->
 *  <!--  CONST char *name, *group, *usage, *desc;                     -->
 *  <!--  char * HLFunc(void);                                         -->
 *  Defines the help strings for the command name given.
 *
 *  All the strings given should be static strings, because we may
 *  store pointers to them.
 *  HLFunc should return a string that we become the owner of, or NULL.
 *  All 5 parameters should be coming via defines in the
 *  C header files for the function being documented.
 *  See Asc_HelpCmd() for an example of same.<br><br>
 *
 *  If you have not written up someplace else the information that
 *  is required here, you obviously have not thought the command you
 *  are registering through and you should not be registering it.
 *
 *  @param name     The tcl registration string.
 *  @param group    The command group name.  It should not contain whitespace.
 *  @param usage    The command syntax by example or in man page style.
 *  @param desc     The basic one-line description of the command. (<= 70 char)
 *  @param longfunc Function returning the detailed explanation of the command.
 */

extern CONST char *Asc_HelpGetShort(Tcl_Interp *interp, CONST84 char *commandname);
/**<
 *  <!--  Asc_HelpGetShort(interp,commandname)                         -->
 *  Returns the short string for the command given, if there is one.
 *  If interp is not NULL, also appends the returned string to the
 *  interpreter's result string.
 */

extern CONST char *Asc_HelpGetLong(Tcl_Interp *interp, CONST84 char *commandname);
/**<
 *  <!--  Asc_HelpGetLong(interp,commandname)                          -->
 *  Returns the long string for the command given, if there is one.
 *  If interp is not NULL, also appends the returned string to the
 *  interpreter's result string.
 */

extern CONST char *Asc_HelpGetUsage(Tcl_Interp *interp, CONST84 char *commandname);
/**<
 *  <!--  Asc_HelpGetUsage(interp,commandname)                         -->
 *  Returns the usage string for the command given, if there is one.
 *  If interp is not NULL, also appends the returned string to the
 *  interpreter's result string.
 */

extern int Asc_HelpGetGroup(Tcl_Interp *interp, CONST84 char *groupname);
/**<
 *  <!--  Asc_HelpGetGroup(interp,groupname)                           -->
 *  Returns the members of a group, and the group explanation
 *  if there is one, in the interpreter.
 *  All is in a list format and the explanation is first
 *  if it exists. If group does not exist, returns an error message.
 *  By use convention: the group explanation is a list element which
 *  starts with "Explanation".
 *  The return code follows TCL conventions.
 */

extern int Asc_HelpCommandGroups(Tcl_Interp *interp);
/**<
 *  <!--  Asc_HelpCommandGroups(interp)                                -->
 *  Appends the complete list of groups to the interpreter.
 *  Commands are sorted in some reasonable fashion.
 *  The return code follows TCL conventions.
 */

extern int Asc_HelpCommandList(Tcl_Interp *interp);
/**<
 *  <!--  Asc_HelpCommandList(interp)                                  -->
 *  Appends the complete list of commands to the interpreter.
 *  Commands are sorted in alphabetical order.
 *  The return code follows TCL conventions.
 */

extern int Asc_HelpCommandsByGroups(Tcl_Interp *interp);
/**<
 *  <!--  Asc_HelpCommandsByGroups(interp)                             -->
 *  Appends the complete list of commands to the interpreter.
 *  Groups are sorted and then commands are sorted in alphabetical order.
 *  The return code follows TCL conventions.
 */

STDHLF_H(Asc_HelpCmd);
/**<  Function returning our long help string. */

extern int Asc_HelpCmd(ClientData cdata, Tcl_Interp *interp, 
                       int arcg, CONST84 char **argv);
/**<
 * <!--  Asc_HelpCmd(cdata,interp,argc,argv);                          -->
 * This is the tcl callback for our commandline help facility.
 */

/** Registered as */
#define Asc_HelpCmdHN "help"
/** Usage */
#define Asc_HelpCmdHU \
  "help [commandname] OR help help"
/** Short help text */
#define Asc_HelpCmdHS \
  "returns information on C functions ASCEND defines as Tcl commands"
/** Long help text part 1. */
#define Asc_HelpCmdHL1 \
"\
 * Returns help on a registered command name, or command group name,\n\
 * or the list of commands alphabetized or the list groups alphabetized,\n\
 * or the list of commands alphabetized by groups.\n\
 * For help on specific commands you can also try: <commandname> -h\n\
 * Most of our callbacks supply their own help.\n\
"
/** Long help text part 2. */
#define Asc_HelpCmdHL2 \
"\
 *\n\
 * help examples:\n\
 * help -h         returns a short definition & UNIX man page style syntax.\n\
 * help -H         returns a long explanation\n\
 * help help       returns this text.\n\
"
/** Long help text part 3. */
#define Asc_HelpCmdHL3 \
"\
 * help system     returns the description of the system group.\n\
 * help groups     returns the alphabetized list of group names.\n\
 * help all        returns the alphabetized list of commands.\n\
 * help commands   returns the alphabetized listing of groups.\n\
 *\n\
"
/** Long help text part 4. */
#define Asc_HelpCmdHL4 \
"\
 * All output is to the tcl interpreter in the form of list elements.\n\
 * For better formatted help output, use Help which has the same\n\
 * syntax as this command but writes the output more neatly to stdout.\n\
"
/*
 * If we follow the style above for all our tcl callback headers we
 * end up with better documented tcl callbacks in C and consistent
 * runtime help.
 * The pattern is to define 3 macros in the pattern
 * nameHN, nameHU, nameHS, and function nameHLF via the macro STDHLF
 * above.
 * In this example name is Asc_HelpCmd.
 */

#endif  /* ASCTK_HELPPROC_H */

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