f2a51409ff069c592fd84ef3672951badf6e692a
[alioth/magicpoint.git] / mgp.1
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 .Dd July 20, 2019
28 .Dt MGP 1
29 .Os MagicPoint
30 .Sh NAME
31 .Nm mgp
32 .Nd MagicPoint, an X11-based presentation tool
33 .Sh SYNOPSIS
34 .Nm mgp
35 .Op Fl BCeGhnOoPqRSUVv
36 .Op Fl b Ar bgcolour
37 .Op Fl D Ar htmldir
38 .Op Fl d Op Ar interval
39 .Op Fl E Ar htmlimage
40 .Op Fl F Ar mode,effect,value
41 .Op Fl g Ar geometry
42 .Op Fl p Ar page
43 .Op Fl Q Ar quality
44 .Op Fl T Ar timestampfile
45 .Op Fl t Ar timeslot
46 .Op Fl X Ar gsdevice
47 .Op Fl x Ar engine
48 .Ar file
49 .Sh DESCRIPTION
50 .Nm
51 .Pq MagicPoint
52 is an X11-based presentation tool.
53 It is designed to make
54 simple presentations easy while to make complicated presentations
55 possible.
56 Its presentation file
57 .Pq whose suffix is typically Li .mgp
58 is just text so that you can create presentation files quickly with
59 your favorite editor (such as jupp or Emacs).
60 .Pp
61 The
62 .Li .mgp
63 file consists of text and
64 control commands (such as pagebreak, centering, and/or inline image).
65 Control commands are specified on the beginning of lines started with
66 one percent sign
67 .Pq Sq Li % .
68 You can include numerous kinds of image format files
69 onto the presentation file.
70 .Pp
71 .Nm
72 uses X11 scalable fonts.
73 .Pp
74 The following options are available:
75 .Bl -tag -width indent
76 .It Fl B
77 Omit background image.
78 .It Fl b Ar bgcolour
79 Set background colour to
80 .Ar bgcolour .
81 (The default value is black)
82 .It Fl C
83 Use private colourmap.
84 .It Fl D Ar htmldir
85 Generate html pages of the presentation into
86 .Ar htmldir .
87 You will need
88 .Xr xwintoppm 1
89 (included in mgp kit),
90 and
91 .Xr pnmscale 1 ,
92 .Xr cjpeg 1 ,
93 and
94 .Xr djpeg 1
95 .Po
96 included in
97 .Li netpbm
98 and
99 Independent Jpeg Group
100 .Li jpeg
101 package
102 .Pc .
103 .It Fl d [ Ar interval ]
104 Demonstration mode.
105 Browse all page automatically, spending
106 .Ar interval
107 secounds on each page and terminate. If
108 .Ar interval
109 is not specified, it will be set to 0.
110 .It Fl E Ar htmlimage
111 Specifies html image type. Now
112 .Dq Li jpg
113 and
114 .Dq Li png
115 are supported, default value is
116 .Dq Li jpg .
117 It works when the
118 .Fl D
119 option is set.
120 .It Fl F Ar mode,effect,value
121 Specifies forward page cache options.
122 .Ar Mode ,
123 .Ar effect
124 and
125 .Ar value
126 are numbers.
127 .Ar Mode
128 specifies caching mode.
129 .Ar Mode
130 0 means caching is executed after 2 seconds idle.
131 .Ar Mode
132 1 means caching is executed immediately.
133 .Ar Effect
134 specifies a
135 .Sq special effect
136 for the forward page cache.
137 Currently, two special effects are supported.
138 .Ar Effect
139 1 means that the next page will come in from the left side.
140 .Ar Effect
141 2 means that the current page will go out to the left side.
142 .Ar Effect
143 0 means no special effect.
144 .Ar Value
145 specifies speed of special effect.
146 .Ar Value
147 1 means the highest speed. A higher value for
148 .Ar value
149 decreases effect speed.
150 .It Fl G
151 Specifies to turn on page guide function.
152 At the bottom of the screen, the titles of next page and previous page are
153 displayed to assist the presentation.
154 Page guide can be turned on and off by keyboard too.
155 .It Fl g Ar geometry
156 Set the size and location of the window.
157 Please note that
158 .Fl g
159 implies
160 .Fl o.
161 .Nm
162 will not override the window manager if you specify the geometry.
163 .It Fl h
164 Display the usage and exit without performing a presentation.
165 .It Fl n
166 .Nm
167 accepts any key inputs from invoked terminal as
168 KEY OPERATION described below.
169 .Fl n
170 disables this feature.
171 (This option may be removed in the future release)
172 .It Fl O
173 Obey to the window manager, but with less decoration around the window.
174 The behavior of this option is affected by how the window manager
175 is implemented; this option may have no effect on some of the window managers.
176 .It Fl o
177 Do not override window manager.
178 (By default,
179 .Nm
180 overrides window manager and occupies the whole display)
181 .It Fl p Ar page
182 Start presentation from
183 .Ar page ,
184 rather than the first page.
185 .It Fl Q Ar quality
186 Set background image quality (0 to 100) in percent.
187 .It Fl q
188 Do not beep on errors.
189 .It Fl R
190 .Nm
191 will usually reload the presentation file if it gets updated,
192 based on the file modification time taken by
193 .Xr stat 2 .
194 .Fl R
195 disables this auto-reloading feature.
196 .It Fl S
197 Be secure.
198 Skip directives that fork/exec the child process.
199 It is suggested to use this option if you got some presentation file
200 from others.
201 This is enabled by default.
202 .It Fl T Ar timestampfile
203 If the option is specified,
204 .Nm
205 will modify the content of
206 .Ar timestampfile
207 every time it updates the presentation window.
208 This option is useful for external process to understand when
209 .Nm
210 modifies the window.
211 .It Fl t Ar timeslot
212 Specify the timeslot assigned to the presentation in minute.
213 The timer is invoked when the second page is displayed and the remaining
214 presentation time is indicated by the length of bar shown at the bottom of
215 the display.
216 The timebar is updated when some X11 event is raised,
217 for instance some keypress.
218 Timebar will be green if you have more than 50% of the timeslot,
219 yellow while you have more than 30% of the timeslot,
220 and red for the other cases.
221 When the assigned timeslot is expired, exceeding time is also shown as
222 a timebar growing from left to right.
223 Current page is indicated by the position of a small vertical bar; the vertical
224 bar is drawn at the leftend when the first page is displayed while the
225 bar is drawn at the rightend when the last page is displayed.
226 .It Fl Fl title Ar name
227 Set the title of the window to
228 .Ar name .
229 .It Fl U
230 Be unsecure.
231 Enable directives that fork/exec the child process.
232 Allows using non-ASCII filenames.
233 .It Fl V
234 Display the MagicPoint version and exit without performing a presentation.
235 .It Fl v
236 Be verbose.
237 Generate debugging output to standard output.
238 .It Fl X Ar gsdevice
239 .Nm
240 sometimes invokes
241 .Xr ghostscript 1
242 to render postscript images.
243 .Fl X
244 enables you to specify the device to be used by
245 .Xr ghostscript 1 .
246 .\"If your
247 .\".Xr ghostscript 1
248 .\"is capable of using
249 .\".Li x11alpha
250 .\"device, you should try using that.
251 If you specify
252 .Ar gsdevice
253 with a trailing
254 .Sq + ,
255 .Xr pnmscale 1
256 and
257 .Xr pnmdepth 1
258 will be invoked for anti-aliasing.
259 The default
260 .Ar gsdevice
261 is
262 .Dq pnmraw+ .
263 .It Fl x Ar engine
264 Do not use rendering engine, specified by
265 .Ar engine .
266 .Ar engine
267 can be
268 .Li xft .
269 .El
270 .Sh KEY OPERATION
271 The keyboard/mouse commands are:
272 .Bl -tag -width XX
273 .It mouse button 1 (leftmost button)
274 Go forward a page.
275 Space key, downward cursor key, scroll down key,
276 .Dq f
277 key,
278 .Dq j
279 key and
280 .Dq n
281 key have the same effect.
282 If <number> is specified, go forward <number> pages.
283 .It mouse button 3 (rightmost button)
284 Go to the previous page.
285 .Dq b
286 key,
287 .Dq k
288 key,
289 .Dq p
290 key, backspace key, scroll up key and upward cursor key
291 have the same effect.
292 If <number> is specified, go back <number> pages.
293 .It 0 - 9 (number buttons)
294 Set prefix number in decimal.
295 i.e. <number> = <number> * 10 + <keyN> - <key0>.
296 For example, by typing in
297 .Dq 10g
298 you can jump to page 10.
299 .It g
300 Go to the <number> page.
301 If number is 0, go to the last page.
302 .It Control key
303 Display the page listing menu while held.
304 See below for details.
305 .It G
306 Enable/disable page guide.
307 See description for option
308 .Fl G
309 for details.
310 .It x
311 Enable/disable rakugaki (jotting) mode.
312 You can make an annotation (by mouse) on the presentation.
313 Mouse button 2 (middle) has the same effect.
314 .It X
315 Change the pen colour for rakugaki (jotting) mode.
316 .It t
317 Enable/disable the timebar if
318 .Fl t
319 timeslot option is specified.
320 .It c
321 Enable/disable forward page cache.
322 .It w
323 Toggle full screen mode with EWMH.
324 (You need a EWMH-aware window manager and need to run mgp with
325 .Fl o
326 or
327 .Fl g
328 option)
329 .It ^L
330 Repaint the current page.
331 Use this if you messed up the page by jotting too much.
332 .It ^R
333 Reload the current presentation file.
334 If the current page becomes unavailable, page pointer will be moved back to 1.
335 .It Escape key
336 Quit the currently running
337 .Nm mgp .
338 .Dq q
339 key also has the same effect.
340 .El
341 .Pp
342 During the presentation, you can see the page list at the bottom of the
343 window when you press a Control key.
344 Choosing a page with the mouse and clicking it with the leftmost mouse button,
345 you can go to corresponding page directly.
346 Releasing the Control key, the page list disappears and you can continue
347 with the current page.
348 This function is useful during the Q-and-A period after your presentation
349 completes.
350 .Sh CONFIGURATION FILES
351 .Nm
352 imports various image draw functions from
353 .Xr xloadimage 1 .
354 This means that the location of image files can be specified
355 by
356 .Pa ~/.xloadimagerc
357 file.
358 If you specify the presentation file with its directory, that directory
359 is searched first and then the path specified in the
360 .Pa ~/.xloadimagerc
361 is searched.
362 .Sh SECURITY ISSUES
363 The presentation file can include directives to call the external process,
364 just like shell process.
365 Therefore, the presentation file should be treated just like shell script
366 or perl script.
367 This is STRONGLY recommended to review the content
368 of the presentation file before invoking
369 .Nm mgp ,
370 if you got the file from others.
371 By adding the
372 .Fl S
373 option to the command line argument, directives that call external processes
374 will be skipped.
375 .Sh SEE ALSO
376 .Xr mgp2ps 1 ,
377 .Xr mgpnet 1 ,
378 .Xr xloadimage 1
379 .Sh AUTHOR CONTACT
380 Yoshifumi Nishida <nishida@csl.sony.co.jp>
381 .Sh CONTRIBUTION
382 Jun-ichiro Hagino <itojun@itojun.org>, Akira Kato <kato@wide.ad.jp>,
383 Atsushi Onoe <onoe@sm.sony.co.jp>, Kazu Yamamoto <Kazu@Mew.org>,
384 Youjiro Uo <yuo@nui.org>, and Masaki Minami <Masaki@Minami.org>
385 extensively contributed improvements, bug fixes, and documents.
386 Special thanks to Chaki Kusakari <chaki@sfc.wide.ad.jp>.
387 .Sh HISTORY
388 .Nm
389 was created shortly after the autumn camp of WIDE Project in 1997,
390 which was originally called
391 .Nm tp
392 .Pq TinyPoint .
393 .Pp
394 This version of
395 .Nm
396 is a contemporary fork by mirabilos, started in 2019, focussing on
397 UTF-8 support.