1.\" $NetBSD: msgc.1,v 1.27 2021/10/11 18:08:12 rillig Exp $ 2.\" 3.\" Copyright 1997 Piermont Information Systems Inc. 4.\" All rights reserved. 5.\" 6.\" Written by Philip A. Nelson for Piermont Information Systems Inc. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of Piermont Information Systems Inc. may not be used to endorse 17.\" or promote products derived from this software without specific prior 18.\" written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY PIERMONT INFORMATION SYSTEMS INC. ``AS IS'' 21.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL PIERMONT INFORMATION SYSTEMS INC. BE 24.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 30.\" THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd October 11, 2021 33.Dt MSGC 1 34.Os 35.Sh NAME 36.Nm msgc , 37.Nm msg_window , 38.Nm msg_string , 39.Nm msg_clear , 40.Nm msg_standout , 41.Nm msg_standend , 42.Nm msg_display , 43.Nm msg_display_add , 44.Nm msg_printf , 45.Nm msg_prompt , 46.Nm msg_prompt_add , 47.Nm msg_prompt_win , 48.Nm msg_prompt_noecho , 49.Nm msg_row , 50.Nm msg_table_add 51.Nd simple message list compiler 52.Sh SYNOPSIS 53msgc 54.Op Fl o Ar name 55.Ar file 56.Pp 57.Fd #include \&"msg_defs.h" 58.Ft void 59.Fn msg_window "WINDOW *window" 60.Ft const char * 61.Fn msg_string "msg msg_no" 62.Ft void 63.Fn msg_clear "void" 64.Ft void 65.Fn msg_standout "void" 66.Ft void 67.Fn msg_standend "void" 68.Ft void 69.Fn msg_display "msg msg_no" ... 70.Ft void 71.Fn msg_display_add "msg msg_no" ... 72.Ft void 73.Fn msg_printf "fmt" ... 74.Ft void 75.Fn msg_prompt "msg msg_no" "const char *def" "char *val" "int max_chars" ... 76.Ft void 77.Fn msg_prompt_add "msg msg_no" "const char *def" "char *val" "int max_chars" ... 78.Ft void 79.Fn msg_prompt_win "msg msg_no" "WINDOW *win" "const char *def" "char *val" "int max_chars" ... 80.Ft void 81.Fn msg_prompt_noecho "msg msg_no" "const char *def" "char *val" "int max_chars" ... 82.Ft int 83.Fn msg_row "void" 84.Ft void 85.Fn msg_table_add "msg msg_no" ... 86.Sh DESCRIPTION 87This implements a curses based message display system. 88A source file that lists messages with associated names is given to 89.Nm 90and produces both a .c and a .h file that implement the menu system. 91The standard root name of the files is 92.Pa msg_defs . 93The 94.Fl o Ar name 95can be used to specify a different root name. 96.Sh ENVIRONMENT 97.Bl -tag -width MSGDEF 98.It Ev MSGDEF 99Can be set to point to a different set of 100definition files for 101.Nm msgc . 102The current location defaults to 103.Pa /usr/share/misc . 104.El 105.Sh FILES 106.Bl -item 107.It 108.Pa /usr/share/misc/msg_sys.def 109.El 110.Sh SOURCE DESCRIPTION 111The format is very simple. 112Each message is started with the word 113.Sq message 114followed by the name of the message. 115The body of the message is next and is started by a { and closed by a }. 116The braces are not part of the message. 117Everything, including newlines between the braces, is part of the message. 118.Sh MESSAGE FUNCTIONS 119The defined messages are used through calls to routines that manipulate 120the messages. 121You first need to set the 122.Xr curses 3 123environment up and then tell the message system which window to use 124for displaying the messages by calling the function 125.Fn msg_window . 126.Pp 127All variable argument lists in the functions are used as arguments to 128.Xr sprintf 3 . 129The messages may have 130.Xr sprintf 3 131conversions in them and the corresponding parameters should match. 132Messages are identified by name using the notation 133.Sq MSG_name 134where 135.Dq name 136is the name in the message source file. 137(The definitions are accessed by including the generated .h file into each 138source file wanting to use the message routines.) 139.Pp 140The function 141.Fn msg_string 142just returns a pointer to the actual message string. 143The functions 144.Fn msg_clear , 145.Fn msg_standout 146and 147.Fn msg_standend 148respectively clear the message window, set standout mode and clear standout 149mode. 150.Pp 151The functions 152.Fn msg_display 153and 154.Fn msg_display_add 155cause the given message to be displayed in the message window and do 156the requested conversions before printing. 157The difference is that 158.Fn msg_display 159clears the window before displaying the message. 160These functions fill paragraphs for readability. 161The 162.Fn msg_table_add 163function behaves like 164.Fn msg_display_add 165but does not fill text. 166.Pp 167The function 168.Fn msg_printf 169allows to display a raw message without going through the message catalog. 170.Pp 171The remaining functions deal with a prompt facility. 172A prompt message is either taken from the message directory or from a 173given string. 174The message is processed with 175.Xr sprintf 3 176and then displayed. 177If the parameter 178.Ar def 179is 180.No non- Ns Dv NULL 181and not a string of zero length, a default value is printed 182in brackets. 183The user is allowed to type in a response. 184If the user types just the newline character, the default is returned 185in the value. 186The parameter 187.Ar max_chars 188is the length of the parameter 189.Ar val , 190where the results are stored. 191The parameters 192.Ar def 193and 194.Ar val 195may point to the same character array. 196If the default is chosen, the character array is not changed. 197The functions 198.Fn msg_echo 199and 200.Fn msg_noecho 201control whether the prompt routines echo or don't echo the input that 202is typed by the user. 203.Pp 204.Fn msg_prompt_win 205uses the specified curses window instead of the default one. 206.Pp 207.Fn msg_row 208return the current row - i.e.: getcury(msg_win) + getbegy(msg_win). 209.Sh AUTHORS 210Philip A. Nelson for Piermont Information Systems Inc. 211