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