| blob | ebfd8c88e76a20915d7c29dfda167e613bd5f4d0 |
1 ============================\r
2 Slides from reStructuredText\r
3 ============================\r
4 \r
5 :author: Alan Glen Isaac\r
6 :date: 2010-09-06\r
7 :source: `rst2slides.rst`_\r
8 \r
9 .. _rst2slides.rst: rst2slides.rst\r
10 \r
11 A Need\r
12 ======\r
13 \r
14 Slide writers need one or more test documents\r
15 that all slide writers should be able to handle.\r
16 (See below.)\r
17 \r
18 The present document has very low requirements.\r
19 It does not include:\r
20 \r
21 - subtitle\r
22 - sections and subsections\r
23 - images and tables\r
24 - overlays\r
25 - math\r
26 \r
27 Therefore it is not an adequate test document.\r
28 But certainly all writers should be able to handle the present document.\r
29 \r
30 Test Suite\r
31 ==========\r
32 \r
33 Here is a test suite based on the discussion below.\r
34 \r
35 - http://subversion.american.edu/aisaac/misc/slides_test01.rst\r
36 - http://subversion.american.edu/aisaac/misc/slides_test02.rst\r
37 - http://subversion.american.edu/aisaac/misc/slides_test03.rst\r
38 - http://subversion.american.edu/aisaac/misc/slides_test04.rst\r
39 \r
40 \r
41 Some Problems\r
42 =============\r
43 \r
44 1. There is no settled reST slide format, so writers\r
45 do not offer consistent handling\r
46 The test documents are intended to lead toward\r
47 greater uniformity.\r
48 \r
49 2. The lack of math support in the docutils core is pretty devastating.\r
50 (Jens’s work should be moved to the docutils core,\r
51 at least as an “experimental” feature.)\r
52 However some writers implement math support independently.\r
53 \r
54 \r
55 Core Goal\r
56 =========\r
57 \r
58 Implementing slides with standard reST sectioning\r
59 \r
60 - is easiest to write\r
61 - looks a lot better as text\r
62 \r
63 Therefore sections should be the basic way to determine\r
64 what is a slide.\r
65 \r
66 \r
67 Sectioning\r
68 ==========\r
69 \r
70 Proposal: the lowest section level present should always treated as a slides.\r
71 \r
72 What about sections within slides?\r
73 That what the ``topic`` or ``rubric`` directives are for!\r
74 \r
75 Some writers must change to implement this.\r
76 E.g., rst2beamer takes this approach, but rst2s5 does not.\r
77 For backwards compatibility,\r
78 this default could be overridden with an option:\r
79 ``--slide-section-level=N``\r
80 \r
81 Note that docutils imposes section-level consistency.\r
82 So if you want any slide in a sections and a subsection,\r
83 the first slides must be in a section and in a subsection.\r
84 (Because slides are based on sectioning.)\r
85 \r
86 \r
87 \r
88 \r
89 Other Objects as Slides\r
90 =============================\r
91 \r
92 Guenter Milde suggests that slide writers should recognize a\r
93 ``slide`` class on objects.\r
94 An object with the slide class always generates a new slide.\r
95 \r
96 This would be excellent and very flexible.\r
97 In this setting, Milde proposed that the above-mentioned option\r
98 ``--slide-section-level=N``\r
99 simply tag all sections at that level.\r
100 \r
101 If the default is ``--slide-section-level=-1``\r
102 and that means "tag the lowest subsection level".\r
103 This has a good fit with the previous proposed solution.\r
104 \r
105 If two nested objects are both tagged with the ``slide`` class,\r
106 the initial content of the first goes on a slide,\r
107 the content of the second goes on a second slide,\r
108 and any left-over content from the first then goes on a third slide.\r
109 \r
110 \r
111 Additional Proposals for Slide Writers\r
112 ======================================\r
113 \r
114 Recognize the following special class arguments\r
115 (proposed by G. Milde):\r
116 \r
117 overlay\r
118 place object on a new "overlay" (which gives the appearance of\r
119 incremental exposure of a given slide).\r
120 notesonly\r
121 do not place object on any slide (i.e. ignore when producing slides)\r
122 (Achievable via docutils’ ``strip-elements-with-class`` setting).\r
123 slidesonly\r
124 do not place object in the notes (i.e. when generating\r
125 standard HTML/LaTeX/PDF output for the handout or notes).\r
126 (Achievable via docutils’ ``strip-elements-with-class`` setting).\r
127 \r
128 \r
129 Additional Proposals for Slide Writers\r
130 ======================================\r
131 \r
132 Additionally:\r
133 it is important to be able to tag lists (at least)\r
134 as say ``incremental``, to signal to the writer to generate\r
135 a sequence of overlays.\r
136 \r
137 rst2beamer currently allows users to tag any slides\r
138 with ``overlay`` or ``nooverlay``, which override\r
139 the default.\r
140 \r
141 As a LaTeX specific attribute, Ryan Krauss\r
142 also added ``fragile`` and ``notfragile``\r
143 class attribute support for beamer slides.\r
144 This is a good idea for any LaTeX slide writer.\r
145 \r
146 \r
147 \r
148 \r
149 HTML Slides: rst2s5\r
150 ====================\r
151 \r
152 rst2s5 is part of the standard docutils distribution.\r
153 \r
154 ::\r
155 \r
156 rst2s5 --theme=small-white slides.rst slides.html\r
157 \r
158 There is a useful introduction: http://docutils.sourceforge.net/docs/user/slide-shows.html\r
159 \r
160 \r
161 \r
162 rst2s5 Limitations\r
163 ==================\r
164 \r
165 - no sectioning.\r
166 - browser font resizing is disabled\r
167 - no math directive or role\r
168 \r
169 \r
170 rst2s5 Improvement Suggestions\r
171 ==============================\r
172 \r
173 - allow slides to be within sections and subsections\r
174 \r
175 - display these instead of the title at the bottom\r
176 \r
177 \r
178 PDF Slides: rst2pdf\r
179 ===================\r
180 \r
181 Solution: ``rst2pdf``\r
182 \r
183 - available on Pypi.\r
184 - available from http://code.google.com/p/rst2pdf/\r
185 \r
186 ::\r
187 \r
188 rst2pdf -b2 -s a4-landscape -o c:\temp\temp.pdf slides.rst \r
189 \r
190 There is a helpful `rst2pdf manual`_\r
191 You may also want to look Roberto Alsina's `slides.style`_.\r
192 \r
193 .. _rst2pdf manual: http://rst2pdf.googlecode.com/svn/trunk/doc/manual.txt\r
194 .. _slides.style: http://lateral.netmanagers.com.ar/static/rst2pdf-slides/slides.style\r
195 \r
196 \r
197 rst2pdf Limitations\r
198 ===================\r
199 \r
200 rst2pdf has\r
201 \r
202 - math directive and role\r
203 - great flexibility of style\r
204 \r
205 So with the right style file, there may be no limitations\r
206 relevant to this summary. But\r
207 \r
208 - images: upgrade to latest ReportLab to get PNG images to work;\r
209 there is no support for PDF 1.6 images\r
210 - I don't know how to do incremental revelation of slide material\r
211 - I like beamer's handling of sections and subsections\r
212 (i.e., display in headers or footers, not on separate slides)\r
213 but I don't know how to get that from rst2pdf\r
214 \r
215 \r
216 PDF Slides: rst2beamer\r
217 ======================\r
218 \r
219 Solution: ``rst2beamer``\r
220 \r
221 - old version available on Pypi (authors are Ryan Krauss and Paul-Michael) has some bugs.\r
222 - working version is in docutils sandbox has fewer bugs and more features\r
223 \r
224 ::\r
225 \r
226 rst2beamer slides.rst slides.tex\r
227 pdflatex slides.tex slides.pdf\r
228 \r
229 Quick notes: http://www.agapow.net/software/rst2beamer\r
230 \r
231 Comment: this solution produces very good looking output.\r
232 \r
233 .. Ryan Krauss rkrauss@siue.edu\r
234 .. Paul-Michael Agapow (pma@agapow.net)\r
235 \r
236 \r
237 rst2beamer Limitations\r
238 ======================\r
239 \r
240 - no math directive or role (but can add math as raw LaTeX)\r
241 - unlike rst2latex, Unicode characters are not translated\r
242 - literal text handling is partly broken; it should copy the\r
243 approach in rst2latex\r
244 - suppose you want a one row, two-column table with a figure\r
245 in one cell and a related list in the other (i.e., a standard\r
246 presentation slide style). rst2beamer will not be correctly format this.\r
247 (Nor will rst2latex, for that matter.)\r
248 \r
249 Unhappy defaults:\r
250 \r
251 - every slide is assigned ``fragile`` option -> amsmath is broken\r
252 - every slide is incremental by default (ugh!).\r
253 However, can turn off incremental for the whole set with ``--overlaybullets=False``.\r
254 Can then turn on on per-slide basis (with ``overlay`` class)\r
255 \r
256 \r
257 rst2beamer Improvement Suggestions\r
258 ==================================\r
259 \r
260 - Don’t make slides fragile and incremental by default.\r
261 - handle literal text like rst2latex does; the current\r
262 approach does not work correctly\r
263 - handle math like rst2latexmath does\r
264 \r
265 rst2beamer Improvement Suggestions\r
266 ==================================\r
267 \r
268 Here is a reason not to set the ``fragile`` option by default:\r
269 \r
270 12.9 Verbatim and Fragile Text\r
271 If you wish to use a {verbatim} environment in a frame,\r
272 you have to add the option [fragile] to the {frame}\r
273 environment. In this case, you really have to use the\r
274 {frame} environment (not the \frame command) and the\r
275 \end{frame} must be alone on a single line. Using this\r
276 option will cause the frame contents to be written to an\r
277 external file and then read back. See the description of\r
278 the {frame} environment for more details.\r
279 \r
280 \r
281 rst2beamer Improvement Suggestions (continued)\r
282 ==============================================\r
283 \r
284 An example implication: suppose you put in a slide::\r
285 \r
286 .. raw:: latex\r
287 \r
288 \[ a = b \]\r
289 \r
290 Then rst2beamer will write a document that won't compile\r
291 (because the fragile option is set, but ``\end{frame}``\r
292 will not be on its own line). However this can be fixed\r
293 by adding an reST comment line.\r
294 \r
295 \r
296 \r
297 ODP Slides\r
298 ==========\r
299 \r
300 Solution: rst2odp\r
301 \r
302 - available on PyPI\r
303 - development version in docutils sandbox\r
304 \r
305 ::\r
306 \r
307 rst2opd slides.rst slides.odp\r
308 \r
309 \r
310 \r
311 rst2odp Limitations\r
312 ======================\r
313 \r
314 - does not have a math directive or role\r
315 - does not handle subtitle\r
316 - does not handle citations\r
317 - I have not been able to get it to work\r
318 \r
319 \r
320 PowerPoint Slides\r
321 =================\r
322 \r
323 Solution: rst2outline http://docutils.sourceforge.net/sandbox/rst2outline/\r
324 \r
325 ::\r
326 \r
327 rst2outline slides.rst slides.txt\r
328 powerpnt.exe slides.txt\r
329 \r
330 This solution takes advantage of how PowerPoint reads plain text files\r
331 (as described at http://www.pptfaq.com/FAQ00246.htm).\r
332 \r
333 rst2outline Limitations\r
334 =======================\r
335 \r
336 - only handles text\r
337 - no title, subtitle, or sectioning\r
338 \r
339 \r