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