magicpoint-1.10a.tar.gz (MirPorts)
[alioth/magicpoint.git] / mgp.man
1 .\" Copyright (C) 1997 and 1998 WIDE Project.  All rights reserved.
2 .\"
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
5 .\" are met:
6 .\" 1. Redistributions of source code must retain the above copyright
7 .\"    notice, this list of conditions and the following disclaimer.
8 .\" 2. Redistributions in binary form must reproduce the above copyright
9 .\"    notice, this list of conditions and the following disclaimer in the
10 .\"    documentation and/or other materials provided with the distribution.
11 .\" 3. Neither the name of the project nor the names of its contributors
12 .\"    may be used to endorse or promote products derived from this software
13 .\"    without specific prior written permission.
14 .\" 
15 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\" 
27 .\"     $Id: mgp.man,v 1.60 2003/05/21 09:07:26 nishida Exp $
28 .\"
29 .Dd November 1997
30 .Dt MGP 1
31 .Os
32 .\"
33 .Sh NAME
34 .Nm mgp
35 .Nd MagicPoint -- an X11 based presentation tool
36 .\"
37 .Sh SYNOPSIS
38 .Nm mgp
39 .Op Fl dhlnoqvBCGORSV
40 .Op Fl b Ar bgcolor
41 .Op Fl c Ar vfcap
42 .Op Fl f Ar vfont
43 .Op Fl g Ar geometry
44 .Op Fl p Ar page
45 .Op Fl t Ar timeslot
46 .Op Fl w Ar wdir
47 .Op Fl x Ar engine
48 .Op Fl D Ar htmldir
49 .Op Fl E Ar htmlimage
50 .Op Fl F Ar mode,effect,value
51 .Op Fl Q Ar quality
52 .Op Fl T Ar timestampfile
53 .Op Fl X Ar gsdevice
54 .Ar file
55 .\"
56 .Sh DESCRIPTION
57 .Nm
58 is an X11 based presentation tool.
59 It is designed to make
60 simple presentations easy while to make complicated presentations
61 possible.
62 Its presentation file
63 .Pq whose suffix is typically Li .mgp
64 is
65 just text so that you can create presentation files quickly with your
66 favorite editor (such as Emacs).
67 .Pp
68 The 
69 .Li .mgp
70 file consists of text and
71 control commands (such as pagebreak, centering, and/or inline image).
72 Control commands are specified on the beginning of lines started with
73 one
74 .Li %
75 sign.
76 You can include numerous kinds of image format files
77 onto the presentation file.
78 .Pp
79 .Nm
80 uses Japanese/English fonts in various sizes.
81 .Nm
82 uses X11 scalable fonts provided by X11 servers.
83 .Nm
84 can also utilize the Japanese outline font library, "VFlib",
85 if configured to do so at compilation time.
86 .Pp
87 The following options are available:
88 .Bl -tag -width indent
89 .It Fl b Ar bgcolor
90 Set background color to
91 .Ar bgcolor .
92 (The default value is black)
93 .It Fl c Ar vfcap
94 Specify a VFlib configuration file.
95 .It Fl d [ Ar interval ]
96 Demonstration mode.
97 Browse all page automatically, spending 
98 .Ar interval 
99 secounds on each page and terminate. If 
100 .Ar interval 
101 is not specified, it will be set to 0.
102 .It Fl f Ar vfont
103 Specify the font name to be used by VFlib.
104 (The default value is minsl)
105 .It Fl g Ar geometry
106 Set the size and location of the window.
107 Please note that
108 .Fl g
109 implies
110 .Fl o.
111 .Nm
112 will not override the window manager if you specify the geometry.
113 .It Fl h
114 Display the usage and exit without performing a presentation.
115 .It Fl l
116 There are two kind of fonts available by VFlib;
117 They are outline font and bitmap font.
118 By specifying
119 .Fl l ,
120 you can disable the use of outline fonts.
121 .It Fl n
122 .Nm
123 accepts any key inputs from invoked terminal as
124 KEY OPERATION described below.
125 .Fl n
126 disables this feature.
127 (This option may be removed in the future release)
128 .It Fl o
129 Do not override window manager.
130 (By default, 
131 .Nm
132 overrides window manager and occupies the whole display)
133 .It Fl p Ar page
134 Start presentation from
135 .Ar page ,
136 rather than the first page.
137 .It Fl q
138 Do not beep on errors.
139 .It Fl t Ar timeslot
140 Specify the timeslot assigned to the presentation in minute.
141 The timer is invoked when the second page is displayed and the remaining
142 presentation time is indicated by the length of bar shown at the bottom of
143 the display.
144 The timebar is updated when some X11 event is raised,
145 for instance some keypress.
146 Timebar will be green if you have more than 50% of the timeslot,
147 yellow while you have more than 30% of the timeslot,
148 and red for the other cases.
149 When the assigned timeslot is expired, exceeding time is also shown as 
150 a timebar growing from left to right.
151 Current page is indicated by the position of a small vertical bar; the vertical
152 bar is drawn at the leftend when the first page is displayed while the
153 bar is drawn at the rightend when the last page is displayed.
154 .It Fl v
155 Display the MagicPoint version and exit without performing a presentation.
156 .It Fl w Ar wdir
157 specifies the working directory used for store embedded images if any.
158 To generate an embedded MGP file, use 
159 .Xr mgpembed 1 .
160 .It Fl x Ar engine
161 Do not use rendering engine, specified by
162 .Ar engine .
163 .Ar engine
164 can be
165 .Li VFlib
166 or
167 .Li FreeType .
168 .It Fl B
169 Omit background image.
170 .It Fl C
171 Use private colormap.
172 .It Fl D Ar htmldir
173 Generate html pages of the presentation into
174 .Ar htmldir .
175 You will need
176 .Xr xwintoppm 1
177 (included in mgp kit),
178 and
179 .Xr pnmscale 1 ,
180 .Xr cjpeg 1 ,
181 and
182 .Xr djpeg 1
183 .Po
184 included in
185 .Li netpbm
186 and
187 Independent Jpeg Group
188 .Li jpeg
189 package
190 .Pc .
191 .It Fl E Ar htmlimage
192 Specifies html image type. Now "jpg" and "png" are supported.
193 default value is "jpg". It works when -D option is set.
194 .It Fl F Ar mode,effect,value
195 Specifies forward page cache options.
196 .Ar Mode ,
197 .Ar effect
198 and
199 .Ar value
200 are numbers. 
201 .Ar Mode
202 specifies caching mode. 
203 .Ar Mode
204 0 means caching is executed after 2 seconds idle.
205 .Ar Mode
206 1 means caching is executed immediately.
207 .Ar Effect 
208 specifies 'special effect' for the forward page cache. Currently, 
209 two special effects are supported.
210 .Ar Effect 
211 1 means that the next page will come in from the left side.
212 .Ar Effect 
213 2 means that the current page will go out to the left side.
214 .Ar Effect 
215 0 means no special effect.
216 .Ar Value
217 specifies speed of special effect. 
218 .Ar Value
219 1 means the highest speed. A higher value for 
220 .Ar value
221 decreases effect speed.
222 .It Fl G
223 Specifies to turn on page guide function.
224 At the bottom of the screen, the titles of next page and previous page are
225 displayed to assist the presentation.
226 Page guide can be turned on and off by keyboard too.
227 .It Fl O
228 Obey to the window manager, but with less decoration around the window.
229 The behavior of this option is affected by how the window manager
230 is implemented; this option may have no effect on some of the window managers.
231 .It Fl Q Ar quality
232 Set background image quality(0-100).
233 .It Fl R
234 .Nm
235 will usually reload the presentation file if it gets updated,
236 based on the file modification time taken by 
237 .Xr stat 2 .
238 .Fl R
239 disables this auto-reloading feature.
240 .It Fl S
241 Be secure.
242 Skip directives that fork/exec the child process.
243 It is suggested to use this option if you got some presentation file
244 from others.
245 This is enabled by default.
246 .It Fl U
247 Be unsecure.
248 Enable directives that fork/exec the child process.
249 .It Fl T Ar timestampfile
250 If the option is specified,
251 .Nm
252 will modify the content of
253 .Ar timestampfile
254 every time it updates the presentation window.
255 This option is useful for external process to understand when
256 .Nm
257 modifies the window.
258 .It Fl V
259 Be verbose.
260 Generate debugging output to standard output.
261 .It Fl X Ar gsdevice
262 .Nm
263 sometimes invokes
264 .Xr ghostscript 1
265 to render postscript images.
266 .Fl X
267 enables you to specify the device to be used by
268 .Xr ghostscript 1 .
269 .\"If your
270 .\".Xr ghostscript 1
271 .\"is capable of using
272 .\".Li x11alpha
273 .\"device, you should try using that.
274 If you specify
275 .Ar gsdevice
276 with a trailing '+',
277 .Xr pnmscale 1
278 and
279 .Xr pnmdepth 1
280 will be invoked for anti-aliasing.
281 The default
282 .Ar gsdevice
283 is "pnmraw+".
284
285 .El
286 .\"
287 .Sh KEY OPERATION
288 The keyboard/mouse commands are:
289 .Bl -tag -width -diag indent
290 .It mouse button 1 (leftmost button)
291 Go forward a page.
292 Space key, downward cursor key, scroll down key, "f" key, "j" key,
293 and "n" key have the same effect.
294 If <number> is specified, go forward <number> pages.
295 .It mouse button 3 (rightmost button)
296 Go to the previous page.
297 "b" key, "k" key, "p" key, backspace key, scroll up key and upward cursor
298 key have the same effect.
299 If <number> is specified, go back <number> pages.
300 .It 0 - 9 (number buttons)
301 Set prefix number in decimal.
302 i.e. <number> = <number> * 10 + <keyN> - <key0>.
303 For example, by typing in "10g" you can jump to page 10.
304 .It g
305 Go to the <number> page.
306 If number of 0 is specified, go to the last page.
307 .It control key
308 Display the page listing menu.
309 See below for details.
310 .It G
311 Enable/disable page guide.
312 See description for option
313 .Fl G
314 for details.
315 .It x
316 Enable/disable rakugaki (jotting) mode.
317 You can make an annotation (by mouse) on the presentation.
318 Mouse button 2 (middle) has the same effect.
319 .It X
320 Change the pen color for rakugaki (jotting) mode.
321 .It t
322 Enable/disable the timebar if -t timeslot option is specified.
323 .It c
324 Enable/disable forward page cache.
325 .It control-L
326 Repaint the current page.
327 Use this if you messed up the page by jotting too much.
328 .It control-R
329 Reload the current presentation file.
330 If the current page becomes unavailable, page pointer will be moved back to 1.
331 .It escape key
332 Quit the currently running
333 .Nm mgp .
334 "q" key also has the same effect.
335 .El
336 .Pp
337 During the presentation, you can see the page list at the bottom of the
338 window when you press a Control Key.
339 Choosing a page with the mouse and clicking it with the leftmost mouse button,
340 you can go to corresponding page directly.
341 Releasing the Control Key, the page list disappears and you can continue
342 with the current page.
343 This function is useful during the Q-and-A period after your presentation
344 completes.
345 .\"
346 .Sh CONFIGURATION FILES
347 .Nm
348 will look at a file named
349 .Pa ~/.mgprc
350 in your home directory.
351 The content of the file must be a limited set of magicpoint directives,
352 one directive per line, without 
353 .Li %
354 sign.
355 Lines start with
356 .Li # ,
357 or empty lines, will be silently ignored.
358 See
359 .Pa SYNTAX
360 for eligible directives.
361 .Pp
362 .Nm
363 imports various image draw functions from
364 .Xr xloadimage 1 .
365 This means that the location of image files can be specified
366 by
367 .Pa ~/.xloadimagerc
368 file.
369 If you specify the presentation file with its directory, that directory
370 is searched first and then the path specified in the
371 .Pa ~/.xloadimagerc
372 is searched.
373 .\"
374 .Sh SECURITY ISSUES
375 The presentation file can include directives to call the external process,
376 just like shell process.
377 Therefore, the presentation file should be treated just like shell script
378 or perl script.
379 This is STRONGLY recommended to review the content
380 of the presentation file before invoking
381 .Nm mgp ,
382 if you got the file from others.
383 By adding the
384 .Fl S
385 option to the command line argument, directives that call external processes
386 will be skipped.
387 .\"
388 .Sh SEE ALSO
389 .Xr mgp2ps 1 ,
390 .Xr xloadimage 1 ,
391 .Xr mgpembed 1
392 .\"
393 .Sh AUTHOR CONTACT
394 Yoshifumi Nishida <nishida@csl.sony.co.jp>
395 .\"
396 .Sh CONTRIBUTION
397 Jun-ichiro Hagino <itojun@itojun.org>, Akira Kato <kato@wide.ad.jp>,
398 Atsushi Onoe <onoe@sm.sony.co.jp>, Kazu Yamamoto <Kazu@Mew.org>,
399 Youjiro Uo <yuo@nui.org>, and Masaki Minami <Masaki@Minami.org> 
400 extensively contributed improvements, bug fixes, and documents.
401 Special thanks to Chaki Kusakari <chaki@sfc.wide.ad.jp>.
402 .\"
403 .Sh HISTORY
404 .Nm
405 was created shortly after the autumn camp of WIDE Project in 1997,
406 which was originally called
407 .Nm tp
408 .Pq TinyPoint .