Here is my first attempt to explain how to make slideshows the "new" way.
All questions welcome now. They will guide further explanations. ===== Section 1. Background A. The screenshots plugin started with Terry's inkcall code: http://groups.google.com/group/leo-editor/browse_thread/thread/be5401b424a022a7 Terry announced it on Aug 31. This code invoked Inkscape to render a .png from a list of inputs, including an original screenshot and a list of callouts. B. On September 7 I announced my intention to move the inkscape code into Leo's core. Ville convinced me to make create the screenshots plugin instead. C. The original idea of the screenshots plugin was to completely automate the process of creating slideshows. The idea was that @screenshot trees would specify the basics of the screenshot. The make- slide or make-slide-show command could create a Leo file containing the (children of) the @screenshot tree and launch that .leo file and take a screenshot of it. If the user wanted to adjust the screenshot, an @pause node (as a child of the @slide node) would cause the plugin **not** to take the screenshot automatically. Rather the user would set up for the screenshot, and take the screenshot by hand. (The plugin would then pull the screenshot from the clipboard). Furthermore, an @edit node would cause the screenshots plugin to invoke Inkscape interactively so the user could edit the screenshot. @callout and @marker nodes caused various graphics items to be passed to Inkscape. ===== Section 2. A complete rethink re screenshots Basically the entire scheme just discussed was a dead end. The problem is that taking screenshots really can **not** be automated as just described. There are several reasons for this: A. It is extremely tedious to specify the contents of screenshots using @screenshot trees. B. Worse, @screenshot trees do not allow for many kinds of screenshots. They don't specify focus, and can not show menus or dialogs. Instead, it makes a lot more sense to use Wink to generate batches of screenshots. ===== Section 3. (re) Using @slideshow trees. Even after rethinking how the actual screenshots will be taken, @slideshow trees containing @slide nodes (and their children) remain useful. Indeed, they now act as **screenplays** for a "movie" consisting of slides. **Important**: I use the term "screenplay" instead of "script" to avoid confusion with python scripts. So @slideshow trees no longer *create* screenshots. Instead, they create **slides** (html files). As before, the input to the slide is rST text. The rST text may contain .. image:: directives that link to a screenshot. (Actually, @slide nodes always created slides, but they also were supposed to create screenshots as well.) Perhaps the best part of the screenshots plugin is how it uses @url nodes to control the sphinx build process. As described in the docstring, the presence or absence of various @url nodes determines, on an @slide-node-...@slide-node basis, what the make-slide and make- slide-show commands do. The new scheme takes *full* advantage of the flexibility that these @url nodes provide. In particular, the new scheme uses "@url final output file" nodes to **prevent** the make-slide and make-slide-show commands from changing the slides that Wink creates. ===== Section 4. The meld script In the new screenshot world, the user lets Wink take all the screenshots. The "interesting" challenge becomes "linking" these screenshots into the (sphinx) slides that the @slide nodes specify. This is a very picky process, and it really must be automated. This is the task of the meld script. Let's review the new process of creating a slideshow. Step 1. Create the screenplay. This is absolutely crucial. Without a final, **accurate** screenplay, it is literally impossible to know what screenshots to take. Wink does allow the user to add or delete screenshots after the initial set has been taken, but a moment's thought should be enough to convince you that it will not, in general, be easy to ensure continuity of slides without a proper script. The screenplay consists of an @slideshow node and its child @slide nodes. **Important**: In the new world, we do **not** run the make-slide or make-slide-show commands at this point! Step 2. Create the screenshots with Wink. Using Wink is straightforward with a bit of practice. However, this is still a tricky step, because it is **absolutely essential** that the number of screenshots **eventually** matches the number of screenshots implied by the screenplay. In the **old** world, an @slide node linked to a screenshot (.png file) if and only if the @slide node contained an @screenshot child. In the **new** world, an @slide node links to a screenshot **unless** the @slide node contains an @no-screenshot child. **Important**: the screenshots plugin has **not** changed in this regard. What *has* changed is that the meld script inserts "@url final output file" nodes to *suppress* the (now unwanted) actions of the screenshots plugin. Step 3: Run the meld script The meld script does a lot of dirty work and a lot of checks. If the meld script succeeds, we can be pretty sure that the @slideshow tree and all the @slide nodes are ready (at last!!) for the make-slide-show or make-slide commands. The meld scripts does the following: - Copies slides from the "wink" folder to the "slides" folder. - Renames the slides so their (numerical) names match the slide number of the corresponding @slide node. - Checks that the number of @slide nodes, minus the number of @no- screenshot nodes, matches the number of wink slides. - Inserts proper .. image:: directives linking the (newly renamed and moved) screenshots to the proper slides and deletes all other .. image:: directives. - Inserts @url final output file nodes. - Deletes any @url built slide nodes. **Important** At present, the meld script uses hard-code paths to specify the "wink" and "slides" folders. As I write this, I realize this is not necessary. See Section 5 below. Step 4. Run the make-slide-show or make-slide command. This will create the slide sources (slide-nnn.html.txt) and then run 'make clean' and 'make html' from the sphinx directory (leo/doc/html) ===== Section 5: Further work At present, the meld script is not part of the screenshots plugin. It would simplify matters if it were. We can eliminate the hard paths used by the @meld script using yet more "options nodes". Like this: @meld-wink-folder <path> We probably don't need an @meld-slides-folder node: we can just use one of the paths computed by the screenshots plugin. Anyway, with this addition we can define an meld-slides command in the screenshots plugin. ===== Section 6: Summary To summarize the steps of creating a slideshow with Wink and Meld: 1. Write a screenplay consisting of an @slideshow node and @slide nodes. 2. Take screenshots in Wink. Add an @meld-wink-folder to the @slideshow tree. 3. Run the meld script (or soon, the meld-slides command). Adjust the number of slides if this step fails. 4. Run the make-slide-show command. This will run a full sphinx build of all slides. 5. (Optional) Run the make-slide command to edit any slide. 6. Copy the built slides from the leo/doc/html/<slideshow>/_build/html folder to the server. That's all ;-) To repeat, the screenshots plugin and its commands have hardly changed at all. What has changed is that meld uses @url nodes to inhibit the screenshots plugin from creating slides. That is now up to Wink and meld. Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/leo-editor?hl=en.
