/* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
/*
* Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
* University Research and Technology
* Corporation. All rights reserved.
* Copyright (c) 2004-2006 The University of Tennessee and The University
* of Tennessee Research Foundation. All rights
* reserved.
* Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
* University of Stuttgart. All rights reserved.
* Copyright (c) 2004-2005 The Regents of the University of California.
* All rights reserved.
* Copyright (c) 2008-2018 Cisco Systems, Inc. All rights reserved.
* Copyright (c) 2018 Triad National Security, LLC. All rights
* reserved.
* $COPYRIGHT$
*
* Additional copyrights may follow
*
* $HEADER$
*/
/**
* @file
*
* The "show help" subsystem (SHS) in Open MPI is intended to help the
* developer convey meaningful information to the user (read longer
* than is convenient in a single printf), particularly when errors
* occur. The SHS allows the storage of arbitrary-length help
* messages in text files which can be parameterized by text filename,
* message name, POSIX locale, and printf()-style parameters (e.g.,
* "%s", "%d", etc.). Note that the primary purpose of the SHS is to
* display help messages, but it can actually be used to display any
* arbitrary text messages.
*
* The function opal_show_help() is used to find a help message and
* display it. Its important parameters are a filename, message name,
* and printf()-style varargs parameters used to substitute into the
* message.
*
* It was originally intended that this system would support a very
* simple version of i18n-like support, but we got (strong) feedback
* that i18n support was not desired. So it never happened.
*
* As such, the file lookup is quite straightforward -- the caller
* passes in the filename to find the help message, and the SHS looks
* for that file in $pkgdatadir (typically $prefix/share/openmpi).
*
* Once the file is successfully opened, the SHS looks for the
* appropriate help message to display. It looks for the message name
* in the file, reads in the message, and displays it. printf()-like
* substitutions are performed (e.g., %d, %s, etc.) --
* opal_show_help() takes a variable legnth argument list that are
* used for these substitutions.
*
* The format of the help file is simplistic:
*
* - Comments begin with #. Any characters after a # on a line are
* ignored. It is not possible to escape a #.
* - Message names are on a line by themselves and marked with [].
* Names can be any ASCII string within the [] (excluding the
* characters newline, linefeed, [, ], and #).
* - Messages are any characters between message names and/or the end
* of the file.
*
* Here's a sample helpfile:
*
* \verbatimbegin
* # This is a comment.
* [topic 1]
* Here's the first message. Let's substitute in an integer: %d.
* The quick brown fox jumped over the lazy %s.
* # This is another comment -- it's not displayed in the first message.
* [another:topic:foo:foo:foo]
* This is the second message. Let's just keep rolling along to get
* to the second line in the message for this example.
* \verbatimend
*
* It is expected that help messages will be grouped by filename;
* similar messages should be in a single file. For example, an MCA
* component may install its own helpfile in Open MPI's $pkgdatadir,
* and therefore the component can invoke opal_show_help() to display
* its own help messages.
*
* Message files in $pkgdatadir have a naming convention: they
* generally start with the prefix "help-" and are followed by a name
* descriptive of what kind of messages they contain. MCA components
* should generally abide by the MCA prefix rule, with the exception
* that they should start the filename with "help-", as mentioned
* previously.
*/
#ifndef OPAL_SHOW_HELP_H
#define OPAL_SHOW_HELP_H
#include "opal_config.h"
#include <stdarg.h>
BEGIN_C_DECLS
/**
* \internal
*
* Initialization of show_help subsystem
*/
OPAL_DECLSPEC int opal_show_help_init(void);
/**
* Look up a text message in a text file and display it to the
* stderr using printf()-like substitutions (%d, %s, etc.).
*
* @param filename File where the text messages are contained.
* @param topic String index of which message to display from the
* text file.
* @param want_error_header Display error-bar line header and
* footer with the message.
* @param varargs Any additional parameters are substituted,
* printf()-style into the help message that is displayed.
*
* This function looks for the filename in the $pkgdatadir
* (typically $prefix/share/openmpi), and looks up the message
* based on the topic, and displays it. If want_error_header is
* true, a header and footer of asterisks are also displayed.
*
* Note that the "want_error_header" argument is int instead of bool,
* because passing a parameter that undergoes default argument
* promotion to va_start() has undefined behavior (according to clang
* warnings on MacOS High Sierra).
*/
typedef int (*opal_show_help_fn_t)(const char *filename, const char *topic,
int want_error_header, ...);
OPAL_DECLSPEC extern opal_show_help_fn_t opal_show_help;
/**
* This function does the same thing as opal_show_help(), but accepts
* a va_list form of varargs.
*/
typedef int (*opal_show_vhelp_fn_t)(const char *filename, const char *topic,
int want_error_header, va_list ap);
OPAL_DECLSPEC extern opal_show_vhelp_fn_t opal_show_vhelp;
/**
* This function does the same thing as opal_show_help(), but returns
* its output in a string (that must be freed by the caller).
*/
OPAL_DECLSPEC char* opal_show_help_string(const char *filename,
const char *topic,
int want_error_header, ...);
/**
* This function does the same thing as opal_show_help_string(), but
* accepts a va_list form of varargs.
*/
OPAL_DECLSPEC char* opal_show_help_vstring(const char *filename,
const char *topic,
int want_error_header, va_list ap);
/**
* This function adds another search location for the files that
* back show_help messages. Locations will be searched starting
* with the prefix installation directory, then cycled through
* any additional directories in the order they were added
*
* This interface allows libraries that use OMPI to take advantage
* of the show_help functionality. OMPI defines the show_help directory
* based on where OMPI was installed. However, if the library wants to
* use show_help to provide error output specific to itself, then it
* nees to tell show_help how to find its own show_help files - without
* interfering with the linked ORTE libs when they need to do show_help.
*/
OPAL_DECLSPEC int opal_show_help_add_dir(const char *directory);
END_C_DECLS
#endif