usr.bin/msgc/msgc.1

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