1 /* 2 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana 3 * University Research and Technology 4 * Corporation. All rights reserved. 5 * Copyright (c) 2004-2006 The University of Tennessee and The University 6 * of Tennessee Research Foundation. All rights 7 * reserved. 8 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, 9 * University of Stuttgart. All rights reserved. 10 * Copyright (c) 2004-2005 The Regents of the University of California. 11 * All rights reserved. 12 * Copyright (c) 2008-2011 Cisco Systems, Inc. All rights reserved. 13 * Copyright (c) 2016-2018 Intel, Inc. All rights reserved. 14 * $COPYRIGHT$ 15 * 16 * Additional copyrights may follow 17 * 18 * $HEADER$ 19 */ 20 /** 21 * @file 22 * 23 * The "show help" subsystem (SHS) in PMIX is intended to help the 24 * developer convey meaningful information to the user (read longer 25 * than is convenient in a single printf), particularly when errors 26 * occur. The SHS allows the storage of arbitrary-length help 27 * messages in text files which can be parameterized by text filename, 28 * message name, POSIX locale, and printf()-style parameters (e.g., 29 * "%s", "%d", etc.). Note that the primary purpose of the SHS is to 30 * display help messages, but it can actually be used to display any 31 * arbitrary text messages. 32 * 33 * The function pmix_show_help() is used to find a help message and 34 * display it. Its important parameters are a filename, message name, 35 * and printf()-style varargs parameters used to substitute into the 36 * message. 37 * 38 * It was originally intended that this system would support a very 39 * simple version of i18n-like support, but we got (strong) feedback 40 * that i18n support was not desired. So it never happened. 41 * 42 * As such, the file lookup is quite straightforward -- the caller 43 * passes in the filename to find the help message, and the SHS looks 44 * for that file in $pkgdatadir (typically $prefix/share/pmix). 45 * 46 * Once the file is successfully opened, the SHS looks for the 47 * appropriate help message to display. It looks for the message name 48 * in the file, reads in the message, and displays it. printf()-like 49 * substitutions are performed (e.g., %d, %s, etc.) -- 50 * pmix_show_help() takes a variable legnth argument list that are 51 * used for these substitutions. 52 * 53 * The format of the help file is simplistic: 54 * 55 * - Comments begin with #. Any characters after a # on a line are 56 * ignored. It is not possible to escape a #. 57 * - Message names are on a line by themselves and marked with []. 58 * Names can be any ASCII string within the [] (excluding the 59 * characters newline, linefeed, [, ], and #). 60 * - Messages are any characters between message names and/or the end 61 * of the file. 62 * 63 * Here's a sample helpfile: 64 * 65 * \verbatimbegin 66 * # This is a comment. 67 * [topic 1] 68 * Here's the first message. Let's substitute in an integer: %d. 69 * The quick brown fox jumped over the lazy %s. 70 * # This is another comment -- it's not displayed in the first message. 71 * [another:topic:foo:foo:foo] 72 * This is the second message. Let's just keep rolling along to get 73 * to the second line in the message for this example. 74 * \verbatimend 75 * 76 * It is expected that help messages will be grouped by filename; 77 * similar messages should be in a single file. For example, an MCA 78 * component may install its own helpfile in PMIX's $pkgdatadir, 79 * and therefore the component can invoke pmix_show_help() to display 80 * its own help messages. 81 * 82 * Message files in $pkgdatadir have a naming convention: they 83 * generally start with the prefix "help-" and are followed by a name 84 * descriptive of what kind of messages they contain. MCA components 85 * should generally abide by the MCA prefix rule, with the exception 86 * that they should start the filename with "help-", as mentioned 87 * previously. 88 */ 89 90 #ifndef PMIX_SHOW_HELP_H 91 #define PMIX_SHOW_HELP_H 92 93 #include <src/include/pmix_config.h> 94 #include <pmix_common.h> 95 96 #include <stdarg.h> 97 98 BEGIN_C_DECLS 99 100 /** 101 * \internal 102 * 103 * Initialization of show_help subsystem 104 */ 105 PMIX_EXPORT int pmix_show_help_init(void); 106 107 108 /** 109 * \internal 110 * 111 * Finalization of show_help subsystem 112 */ 113 PMIX_EXPORT int pmix_show_help_finalize(void); 114 115 116 /** 117 * Look up a text message in a text file and display it to the 118 * stderr using printf()-like substitutions (%d, %s, etc.). 119 * 120 * @param filename File where the text messages are contained. 121 * @param topic String index of which message to display from the 122 * text file. 123 * @param want_error_header Display error-bar line header and 124 * footer with the message. 125 * @param varargs Any additional parameters are substituted, 126 * printf()-style into the help message that is displayed. 127 * 128 * This function looks for the filename in the $pkgdatadir 129 * (typically $prefix/share/pmix), and looks up the message 130 * based on the topic, and displays it. If want_error_header is 131 * true, a header and footer of asterisks are also displayed. 132 * 133 * Note that the "want_error_header" argument is int instead of bool, 134 * because passing a parameter that undergoes default argument 135 * promotion to va_start() has undefined behavior (according to clang 136 * warnings on MacOS High Sierra). 137 */ 138 typedef int (*pmix_show_help_fn_t)(const char *filename, const char *topic, 139 int want_error_header, ...); 140 PMIX_EXPORT extern pmix_show_help_fn_t pmix_show_help; 141 142 /** 143 * This function does the same thing as pmix_show_help(), but accepts 144 * a va_list form of varargs. 145 */ 146 typedef int (*pmix_show_vhelp_fn_t)(const char *filename, const char *topic, 147 int want_error_header, va_list ap); 148 PMIX_EXPORT extern pmix_show_vhelp_fn_t pmix_show_vhelp; 149 150 /** 151 * This function does the same thing as pmix_show_help(), but returns 152 * its output in a string (that must be freed by the caller). 153 */ 154 PMIX_EXPORT char* pmix_show_help_string(const char *filename, 155 const char *topic, 156 int want_error_header, ...); 157 158 /** 159 * This function does the same thing as pmix_show_help_string(), but 160 * accepts a va_list form of varargs. 161 */ 162 PMIX_EXPORT char* pmix_show_help_vstring(const char *filename, 163 const char *topic, 164 int want_error_header, va_list ap); 165 166 /** 167 * This function adds another search location for the files that 168 * back show_help messages. Locations will be searched starting 169 * with the prefix installation directory, then cycled through 170 * any additional directories in the order they were added 171 * 172 * This interface allows libraries that use OMPI to take advantage 173 * of the show_help functionality. OMPI defines the show_help directory 174 * based on where OMPI was installed. However, if the library wants to 175 * use show_help to provide error output specific to itself, then it 176 * nees to tell show_help how to find its own show_help files - without 177 * interfering with the linked ORTE libs when they need to do show_help. 178 */ 179 PMIX_EXPORT int pmix_show_help_add_dir(const char *directory); 180 181 END_C_DECLS 182 183 #endif