update forward page cache docs
[alioth/magicpoint.git] / USAGE
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2
3                  How to make .mgp files (cheat sheet)
4
5                       Kazu Yamamoto (with Chaki)
6
7                             March 14, 2001
8
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10
11 All .mgp commands start with "%". After making sure that
12 /usr/X11R6/lib/X11/mgp/default.mgp exists, add the following line to
13 the beginning of the .mgp file.
14
15         %include default.mgp
16
17 This determines the default style. Each page begins with "%page".
18
19         %page
20
21         TITLE
22
23         Body
24
25 MagicPoint is line oriented. Don't write anything in the first line
26 because the default style uses the first line for making space at the
27 top of the screen. The second line is the title of the page. The third
28 line is transformed into a horizontal line. The fourth line on becomes
29 the body.
30
31 When there is a "%" at the beginning of a line, the rest of the line
32 becomes a command. Multiple commands separated by "," can be written
33 in a single line. To make the size 7% of the screen and the foreground
34 color yellow, one would write:
35
36         %size 7, fore "yellow"
37         This line is big and yellow.
38
39 Any line that starts with "%" won't show up on the screen nor will it
40 be counted as a line. The following parameters can be used to change
41 how a line looks.
42
43         text color                      %fore
44         background color                %back
45         text size                       %size
46         text placement                  %center, %leftfill, %rightfill
47         space between characters        %hgap
48         space between lines             %vgap
49         Font                            %font
50
51 There are a few others, but this should be enough for now. The
52 parameters of default.mgp are set as follows:
53
54         %default 1 leftfill, size 2, fore "white", back "black", font "thick"
55         %default 2 size 7, vgap 10, prefix " "
56         %default 3 size 2, bar "gray70", vgap 10
57         %default 4 size 5, fore "white", vgap 30, prefix " ", font "standard"
58
59 %default set the parameters for the line specified in the first
60 argument to the values specified the second and later argments. In the
61 first line, the size is 2% and in the second line the size is set to
62 7%. Parameters set in previous lines are valid unless
63 overwritten. Therefore, the text in the second line will be white.
64
65 When MagicPoint shows a particular line, it first refers to the %tab,
66 and then refers to the %default values. After that, it refers to the values
67 set within the body. Values of the previous line remain valid unless set
68 otherwise.
69
70 Let's take a look at the following example:
71
72         %page
73                                                 (A space of 2%)
74         TITLE --- size 7% color white and in thick font
75                                                 (A horizontal line)
76         text --- size 5% white thick font
77         %fore yellow, size 4
78         text --- size 4% yellow thick font
79         %font min
80         text --- size 4% yellow standard font
81
82 %tab is a command that directly associates with the line. In
83 default.mgp it is set as follows:
84
85         %tab 1 size 5, vgap 40, prefix "  ", icon box green 50
86         %tab 2 size 4, vgap 40, prefix "      ", icon arc yellow 50
87         %tab 3 size 3, vgap 40, prefix "            ", icon delta3 white 40
88
89 When there is a singular tab at the head of the line, the values of
90 %tab become valid. When there are two tabs at the head of the line,
91 %tab 2 becomes valid, when there are three tabs at the head of the line
92 %tab 3 becomes valid and so on.
93
94 In other words,
95 1 tab means text size 5% and the line starts with spaces and green box icon.
96 2 tabs mean text size 4% and the line starts with spaces and yellow arc icon.
97 3 tabs mean text size 3% and the line starts with spaces and white delta icon.
98
99
100 By using this, it's easy to itemise. Let's take a look at an example:
101
102         %page
103
104         Emacs and friends
105
106                 Emacs
107                         20.7 is currently the main stream
108                         21 is coming
109                 Mule
110                         2.3 is most used
111                         Integrated to Emacs and XEmacs
112                 XEmacs
113                         21.1 is most used
114                         21.2 is coming
115
116 To find out more about the other commands, take a look at SYNTAX or
117 sample/*.mgp.
118
119 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
120
121                             Life with tgif
122
123 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
124
125 MagicPoint cannot display "tgif" objs but there is a way to sort of
126 get around this.
127
128 (1) If you cannot use "ghostscript":
129     - make "tgif" create a GIF file for screen display
130     - make "tgif" create an EPS file for printing out
131
132 (2) If you have "ghostscript":
133     - craete an EPS file from a "tgif" obj file and use that for both cases
134
135 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
136
137 (1) If you cannot use "ghostscript":
138
139 The image created by "tgif" is displayed "as is" on MagicPoint's
140 screen.  This is pretty sad when fonts aren't displayed clearly when
141 viewing with "tgif". Either Mincho or Gothic font is provided for 14,
142 16, 24, and 26 dot. So it's possible to give "xrdb" something like the
143 following, and then make "tgif" create a GIF file.
144
145
146 %%%%
147 Tgif*Background: black
148 Tgif*Foreground: white
149 Tgif.WhereToPrint:             GIF
150 Tgif.XpmToGif: xpmtoppm %s | ppmtogif -transparent black
151 Tgif.FontSizes:                 8 10 12 14 16 18 20 24 26 32 40 48 64
152 Tgif.PreeditType:               overthespot
153 Tgif.InitialPrintInColor:      false
154 %%%%
155
156
157 EPS files can be created just by typing:
158         tgif -print -eps *.obj
159 This is convenient when you have a whole lot of files.
160
161 However, some files might not get the right colors using this way. If
162 you find any files that don't have the right colors, try manually
163 creating the EPS file using "tgif".
164
165 If corresponding filename.eps exists for filename.{gif,jpg,...},
166 "mgp2ps" uses filename.eps when creating a PS file.
167
168 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
169
170 (2) If you can "ghostscript":
171
172 Generate an EPS file, again by using
173         tgif -print -eps *.obj
174 command.
175
176 Paste the EPS file into your presentation by adding
177         %image "foobar.eps"
178 then, mgp will render the EPS file on-the-fly, by invoking "ghostscript".
179 "mgp2ps" will properly include the EPS file into the output.
180
181 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
182
183 (3) Distributing presentation materials
184
185 If you want to bundle two pages into one, you could try this:
186         pstops '2:0R@.6(1.5cm,28cm)+1R@.6(1.5cm,13.85cm)' input.ps > output.ps
187
188 If you want to bundle six pages into one, you could try this:
189         pstops '6:0R@.33(0.5cm,26cm)+1R@.33(10.5cm,26cm)+2R@.33(0.5cm,18cm)+3R@.33(10.5cm,18cm)+4R@.33(0.5cm,10cm)+5R@.33(10.5cm,10cm)' input.ps > output.ps
190
191 "pstops" is included the "psutils"
192 package(ftp://ftp.dcs.ed.ac.uk/pub/ajcd).
193
194 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
195
196                      Tips for better presentation
197
198 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
199
200
201 (1) Refrain from using "xfont" directive directly.
202     Use "deffont" in preamble and "font" in body instead.
203     This should allow people to view your presentation in all the
204     configuration of the renderer.
205
206 (2) Use EPS files for vector image.
207
208 (3)Install the latest "ghostscript".  Configure so that it can
209    generate grayscaled image as output.
210
211 (4) Before the actual presentation, go through the presentation in the
212     same configuration as "the real thing".  It will make rendering
213     faster.  (For the included EPS images, pixel image will be
214     generated and be cached).  If you execute "mgp" with the "-F"
215     option (e.g. "mgp -F 1"), "mgp" fetches and caches the next page
216     so that it makes faster to visualise the next page.
217
218     NOTE: this means mgp will leave around files named similarily to
219     .gscache.dad.eps.446x133 (.gscache. + original filename + . + size)
220     in the presentation source directory for caching!
221
222 (5) Check/practice the connection with the VGA projector.
223
224 (6) Practice your oral presentation well :-)
225
226 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
227
228                         Mathematical Formulas
229
230 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
231
232 There are, at least, three way to include mathematical formulas in
233 .mgp file.
234
235 (1) TeX
236 - Obtain .dvi file for the expression with TeX.
237 e.g. the following code would do:
238
239 \documentstyle{article}
240 \pagestyle{empty}
241 \thispagestyle{empty}
242 \begin{document}
243 ...formula...
244 \end{document}
245
246 - With dvips you can obtain .eps file for the dvi.
247
248 e.g. latex foo.tex ; dvips -f -E foo.dvi > foo.eps
249
250 - Include .eps file into your presentation as follows:
251
252         %image "foo.eps" 0 width height
253
254 (2) "eqn"/"troff"
255 - Obtain .ps file for the expression with "eqn"/"troff".
256 - Convert .ps file to .eps file. (e.g. "pstoepsi")
257 - Include .eps file into your presentation as follows:
258
259         %image "foo.eps"
260
261 (3) Bitmap (not recommended)
262 - Obtain .ps file for the expression with TeX or "eqn"/"troff".
263 - Convert .ps file to .pnm file.(e.g. "pstopnm")
264 - Convert .pnm file to .pbm file (e.g. "pnmcrop")
265 - Include .pbm file into your presentation as follows:
266
267         %image "foo.pbm"
268
269 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
270
271                       Pasting foils onto the web
272
273 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
274
275 If you wish to paste your MagicPoint presentation, you have three options.
276
277 (1) If you can assume that the client-side has MagicPoint, send
278     them a tarball or open your repository for them to read.
279
280 (2) If you cannot asuume that there's no MagicPoint at the client's
281     site, you'll need to convert presentation into a html file.  Use
282     the -D option for this.
283
284 (3) You may convert your presentation as postscript file, after
285     processing it with "mgp2ps".  It would be nice if you would like
286     nobody to reuse your work at ease.
287
288 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%