MapleHelp - Maple Help

MapleHelp

access help from external code

 Calling Sequence MapleHelp(kv, topic, section, writechar, writeattrib, width, data)

Parameters

 kv - kernel handle of type MKernelVector topic - topic name section - section name or NULL writechar - character output function writeattrib - attribute output function width - integer screen width data - arbitrary data passed to the write callbacks

Description

 • This function can be used in external code with OpenMaple or define_external.
 • The MapleHelp function searches for and retrieves a help page or a section of a help page, based on the topic passed to it. The results are passed as a stream of characters and attributes to the specified callback functions.
 • The topic parameter specifies the help page retrieved. For example, to look up help on integration, set topic = "int".
 • The section argument indicates which section of the page to display. If this is passed as "" or NULL, the entire page is displayed. To restrict display to a particular section of the page, pass one of the following values.

 "usage" Shows just the function name (one-line description) and calling sequence information "description" Shows the detailed description of the function "examples" Shows examples of the function's usage "seealso" Shows a list of alternate topics related to this function

 • The writechar function is called once for each character of output.  This function must be declared to match the following prototype.

 M_BOOL M_DECL writechar( void *data, int c );

 The writechar function can terminate rendering by returning TRUE.
 • The writeattrib parameter specifies the function to which attribute information is passed.  Each given attribute applies to all subsequent character sent to writechar until a new attribute is given.  This function must be declared to match the following prototype.

 M_BOOL M_DECL writeattrib( void *data, int attrib );

 The following are the possible attribute values given to the second argument of the callback.

 FN_NORM normal text mode FN_ITAL italic text mode FN_BOLD boldfaced text mode FN_UNDER underlined text mode

 The writeattrib function can be omitted by passing NULL for the writeattrib parameter.
 • The width parameter indicates the width, in characters, to which the help information is formatted.  Examples and tables are always formatted with padded spaces, centered in the middle of the given width.  Therefore, specifying a large number for width does not cause output to arrive in a single line, but rather generates output containing many blanks.
 • The data pointer is passed to the writechar and writeattrib callback functions.  It can point to any data that might be useful during processing of the callbacks.
 • The MapleHelp function returns NULL if successful, or it returns a pointer to an error message if unsuccessful.

Examples

 #include "maplec.h" typedef struct { int size, len; char *string; } myString; static M_BOOL M_DECL myWriteChar( void *data, int c ) { myString *output = (myString*)data; if( output->size-1 == output->len ) { output->size *= 2; output->string = realloc(output->string,sizeof(char)*output->size); if( !output->string ) return( TRUE ); } output->string[output->len++] = (char)c; output->string[output->len] = '0'; return( FALSE ); } ALGEB M_DECL MyHelpToString( MKernelVector kv, ALGEB *args ) { char *topic, *err; myString output; ALGEB r; if( 1 != MapleNumArgs(kv,(ALGEB)args) ) { MapleRaiseError(kv,"one argument expected"); return( NULL ); } topic = MapleToString(kv,args[1]); output.size = 256; output.len = 0; output.string = (char*)malloc(256*sizeof(char)); output.string[0] = '0'; if( (err=MapleHelp(kv,topic,NULL,myWriteChar,NULL,70,&output)) ) { if( output.string ) free(output.string); MapleRaiseError(kv,err); } if( !output.string ) { r = NULL; MapleRaiseError(kv,"out of memory"); } else { r = ToMapleString(kv,output.string); free(output.string); } return( r ); }

Execute the external function from Maple.

 > $\mathrm{with}\left(\mathrm{ExternalCalling}\right):$
 > $\mathrm{dll}≔\mathrm{ExternalLibraryName}\left("HelpExamples"\right):$
 > $\mathrm{shelp}≔\mathrm{DefineExternal}\left("MyHelpToString",\mathrm{dll}\right):$
 > $\mathrm{shelp}\left("colon"\right)$
 ${"Multiple matches found: separator typematch"}$ (1)
 > $\mathrm{shelp}\left("foo"\right)$
 ${"No exact matches found, please try one of the following: footer"}$ (2)