usr.bin/msgc/msgc.1

   1 .\"     $NetBSD: msgc.1,v 1.26 2012/03/06 16:26:01 mbalmer 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 March 3, 2012
  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
  53 msgc
  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
  87 This implements a curses based message display system.
  88 A source file that lists messages with associated names is given to
  89 .Nm
  90 and produces both a .c and a .h file that implement the menu system.
  91 The standard root name of the files is
  92 .Pa msg_defs .
  93 The
  94 .Fl o Ar name
  95 can be used to specify a different root name.
  96 .Sh ENVIRONMENT
  97 .Bl -tag -width MSGDEF
  98 .It Ev MSGDEF
  99 Can be set to point to a different set of
 100 definition files for
 101 .Nm msgc .
 102 The 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
 111 The format is very simple.
 112 Each message is started with the word
 113 .Sq message
 114 followed by the name of the message.
 115 The body of the message is next and is started by a { and closed by a }.
 116 The braces are not part of the message.
 117 Everything, including newlines between the braces are part of the message.
 118 .Sh MESSAGE FUNCTIONS
 119 The defined messages are used through calls routines that manipulate
 120 the messages.
 121 You first need to set the
 122 .Xr curses 3
 123 environment up and then tell the message system which window to use
 124 for displaying message by calling the function
 125 .Fn msg_window .
 126 .Pp
 127 All variable argument lists in the functions are used as
 128 are arguments to
 129 .Xr sprintf 3 .
 130 The messages may have
 131 .Xr sprintf 3
 132 conversions in them and the corresponding parameters should match.
 133 Messages are identified by name using the notation
 134 .Sq MSG_name
 135 where
 136 .Dq name
 137 is the name in the message source file.
 138 (The definitions are accessed by including the generated .h file into a
 139 source file wanting to use the message routines.)
 140 .Pp
 141 The function
 142 .Fn msg_string
 143 just returns a pointer to the actual message string.
 144 The functions
 145 .Fn msg_clear ,
 146 .Fn msg_standout
 147 and
 148 .Fn msg_standend
 149 respectively clear the message window, set standout mode and clear standout
 150 mode.
 151 .Pp
 152 The functions
 153 .Fn msg_display
 154 and
 155 .Fn msg_display_add
 156 cause a defined message to be displayed in the message window and does
 157 the requested conversions before printing.
 158 The difference is that
 159 .Fn msg_display
 160 clears the window before displaying the message.
 161 These functions fill paragraphs for readability.
 162 The
 163 .Fn msg_table_add
 164 function behaves like
 165 .Fn msg_display_add
 166 but does not fill text.
 167 .Pp
 168 The function
 169 .Fn msg_printf
 170 allows to display a raw message without going through the message catalog.
 171 .Pp
 172 The remaining functions deal with a prompt facility.
 173 A prompt message is either taken from the message directory or from a
 174 given string.
 175 The message is processed with
 176 .Xr sprintf 3
 177 and then displayed.
 178 If the parameter
 179 .Ar def
 180 is
 181 .No non- Ns Dv NULL
 182 and not a string of zero length, a default value is printed
 183 in brackets.
 184 The user is allowed to type in a response.
 185 If the user types just the newline character, the default is returned
 186 in the value.
 187 The parameter
 188 .Ar max_chars
 189 is the length of the parameter
 190 .Ar val ,
 191 where the results are stored.
 192 The parameters
 193 .Ar def
 194 and
 195 .Ar val
 196 may point to the same character array.
 197 If the default is chosen, the character array is not changed.
 198 The functions
 199 .Fn msg_echo
 200 and
 201 .Fn msg_noecho
 202 control whether the prompt routine echo or don't echo the input that
 203 is typed by the user.
 204 .Pp
 205 .Fn msg_prompt_win
 206 uses the specified curses window instead of the default one.
 207 .Pp
 208 .Fn msg_row
 209 return the current row - i.e.: getcury(msg_win) + getbegy(msg_win).
 210 .Sh AUTHORS
 211 Philip A. Nelson for Piermont Information Systems Inc.