Menu
▾
▴
Re: [Docutils-users] reST -> slides: first thoughts
|
From: Alan G I. <ai...@am...> - 2010-10-08 03:06:23
|
On 10/7/2010 5:15 AM, Jean-Daniel wrote: > Please, where are the sources of the rst -> slides converter that is > being discussed if it already exists? ============================ Slides from reStructuredText ============================ :author: Alan Glen Isaac :date: 2010-09-06 :source: `rst2slides.rst`_ .. _rst2slides.rst: rst2slides.rst A Need ====== Slide writers need one or more test documents that all slide writers should be able to handle. (See below.) The present document has very low requirements. It does not include: - subtitle - sections and subsections - images and tables - overlays - math Therefore it is not an adequate test document. But certainly all writers should be able to handle the present document. Test Suite ========== Here is a test suite based on the discussion below. - http://subversion.american.edu/aisaac/misc/slides_test01.rst - http://subversion.american.edu/aisaac/misc/slides_test02.rst - http://subversion.american.edu/aisaac/misc/slides_test03.rst - http://subversion.american.edu/aisaac/misc/slides_test04.rst These are also in the slides_tests directory of the sandbox if you get it with Subversion, but for some reason this is not yet accessible via http://docutils.sourceforge.net/sandbox/slides_tests/ Some Problems ============= 1. There is no settled reST slide format, so writers do not offer consistent handling The test documents are intended to lead toward greater uniformity. 2. The lack of math support in the docutils core is pretty devastating. (Jens’s work should be moved to the docutils core, at least as an “experimental” feature.) However some writers implement math support independently. Core Goal ========= Implementing slides with standard reST sectioning - is easiest to write - looks a lot better as text Therefore sections should be the basic way to determine what is a slide. Sectioning ========== Proposal: the lowest section level present should always treated as a slides. What about sections within slides? That what the ``topic`` or ``rubric`` directives are for! Some writers must change to implement this. E.g., rst2beamer takes this approach, but rst2s5 does not. For backwards compatibility, this default could be overridden with an option: ``--slide-section-level=N`` Note that docutils imposes section-level consistency. So if you want any slide in a sections and a subsection, the first slides must be in a section and in a subsection. (Because slides are based on sectioning.) Other Objects as Slides ============================= Guenter Milde suggests that slide writers should recognize a ``slide`` class on objects. An object with the slide class always generates a new slide. This would be excellent and very flexible. In this setting, Milde proposed that the above-mentioned option ``--slide-section-level=N`` simply tag all sections at that level. If the default is ``--slide-section-level=-1`` and that means "tag the lowest subsection level". This has a good fit with the previous proposed solution. If two nested objects are both tagged with the ``slide`` class, the initial content of the first goes on a slide, the content of the second goes on a second slide, and any left-over content from the first then goes on a third slide. Additional Proposals for Slide Writers ====================================== Recognize the following special class arguments (proposed by G. Milde): overlay place object on a new "overlay" (which gives the appearance of incremental exposure of a given slide). notesonly do not place object on any slide (i.e. ignore when producing slides) (Achievable via docutils’ ``strip-elements-with-class`` setting). slidesonly do not place object in the notes (i.e. when generating standard HTML/LaTeX/PDF output for the handout or notes). (Achievable via docutils’ ``strip-elements-with-class`` setting). Additional Proposals for Slide Writers ====================================== Additionally: it is important to be able to tag lists (at least) as say ``incremental``, to signal to the writer to generate a sequence of overlays. rst2beamer currently allows users to tag any slides with ``overlay`` or ``nooverlay``, which override the default. As a LaTeX specific attribute, Ryan Krauss also added ``fragile`` and ``notfragile`` class attribute support for beamer slides. This is a good idea for any LaTeX slide writer. HTML Slides: rst2s5 ==================== rst2s5 is part of the standard docutils distribution. :: rst2s5 --theme=small-white slides.rst slides.html There is a useful introduction: http://docutils.sourceforge.net/docs/user/slide-shows.html rst2s5 Limitations ================== - no sectioning. - browser font resizing is disabled - no math directive or role rst2s5 Improvement Suggestions ============================== - allow slides to be within sections and subsections - display these instead of the title at the bottom PDF Slides: rst2pdf =================== Solution: ``rst2pdf`` - available on Pypi. - available from http://code.google.com/p/rst2pdf/ :: rst2pdf -b2 -s a4-landscape -o c:\temp\temp.pdf slides.rst There is a helpful `rst2pdf manual`_ You may also want to look Roberto Alsina's `slides.style`_. .. _rst2pdf manual: http://rst2pdf.googlecode.com/svn/trunk/doc/manual.txt .. _slides.style: http://lateral.netmanagers.com.ar/static/rst2pdf-slides/slides.style rst2pdf Limitations =================== rst2pdf has - math directive and role - great flexibility of style So with the right style file, there may be no limitations relevant to this summary. But - images: upgrade to latest ReportLab to get PNG images to work; there is no support for PDF 1.6 images - I don't know how to do incremental revelation of slide material - I like beamer's handling of sections and subsections (i.e., display in headers or footers, not on separate slides) but I don't know how to get that from rst2pdf PDF Slides: rst2beamer ====================== Solution: ``rst2beamer`` - old version available on Pypi (authors are Ryan Krauss and Paul-Michael) has some bugs. - working version is in docutils sandbox has fewer bugs and more features :: rst2beamer slides.rst slides.tex pdflatex slides.tex slides.pdf Quick notes: http://www.agapow.net/software/rst2beamer Comment: this solution produces very good looking output. .. Ryan Krauss rk...@si... .. Paul-Michael Agapow (pm...@ag...) rst2beamer Limitations ====================== - no math directive or role (but can add math as raw LaTeX) - unlike rst2latex, Unicode characters are not translated - literal text handling is partly broken; it should copy the approach in rst2latex - suppose you want a one row, two-column table with a figure in one cell and a related list in the other (i.e., a standard presentation slide style). rst2beamer will not be correctly format this. (Nor will rst2latex, for that matter.) Unhappy defaults: - every slide is assigned ``fragile`` option -> amsmath is broken - every slide is incremental by default (ugh!). However, can turn off incremental for the whole set with ``--overlaybullets=False``. Can then turn on on per-slide basis (with ``overlay`` class) rst2beamer Improvement Suggestions ================================== - Don’t make slides fragile and incremental by default. - handle literal text like rst2latex does; the current approach does not work correctly - handle math like rst2latexmath does rst2beamer Improvement Suggestions ================================== Here is a reason not to set the ``fragile`` option by default: 12.9 Verbatim and Fragile Text If you wish to use a {verbatim} environment in a frame, you have to add the option [fragile] to the {frame} environment. In this case, you really have to use the {frame} environment (not the \frame command) and the \end{frame} must be alone on a single line. Using this option will cause the frame contents to be written to an external file and then read back. See the description of the {frame} environment for more details. rst2beamer Improvement Suggestions (continued) ============================================== An example implication: suppose you put in a slide:: .. raw:: latex \[ a = b \] Then rst2beamer will write a document that won't compile (because the fragile option is set, but ``\end{frame}`` will not be on its own line). However this can be fixed by adding an reST comment line. ODP Slides ========== Solution: rst2odp - available on PyPI - development version in docutils sandbox :: rst2opd slides.rst slides.odp rst2odp Limitations ====================== - does not have a math directive or role - does not handle subtitle - does not handle citations - I have not been able to get it to work PowerPoint Slides ================= Solution: rst2outline http://docutils.sourceforge.net/sandbox/rst2outline/ :: rst2outline slides.rst slides.txt powerpnt.exe slides.txt This solution takes advantage of how PowerPoint reads plain text files (as described at http://www.pptfaq.com/FAQ00246.htm). rst2outline Limitations ======================= - only handles text - no title, subtitle, or sectioning |