Hieroglyph 0.5

During the last week of 2012 I pushed out a new release of Hieroglyph. I realized later that I haven’t really been talking about it here, so I wanted to mention some of the new features and functionality I’ve been working on. When I published the 0.3 release, I said I was planning to work on hooking analytics into the slide viewing so that creators could get a better sense of how their slide decks were being used. I have done some work to that end, but would up getting side tracking.

The 0.4 release consisted primarily of internal cleanups in preparation for adding analytics support. There were some places where the Javascript or styles were duplicated, so I put some effort into cleaning that up. I also split up the Javascript to separate slide control from user interaction. This was done to support both analytics and the initial implementation of the Presenter’s Console: a separate window that displays the previous, current, and next slides, and allows the presenter to control the primary display window. With Hieroglyph 0.4 and later you can open by pressing c within a slide document.

Hieroglyph 0.4 also added support for slide numbering and for applying a theme to individual documents inside of a project using the slideconf direction. For example:

.. slideconf::
   :theme: single-level

In December I put together some training for other engineers at Eventbrite around Python byte and unicode strings, and how to safely work with them both in our codebase. While I was putting that together, I realized that there was a lot of text and code samples in the documentation that I wanted to go through interactively, and not include in slides. I wound up going without slides, and found that presenting from the Python interactive interpreter was very effective for this sort of hands on training. That said, it would have been nice to have had a few key slides: an introduction, a summary of key points, and maybe where to go next. That’s the sort of content I’d like to keep with the main document so it doesn’t drift too far out of sync, but Hieroglyph didn’t really support that approach: it assumed that you wanted to generate a slide per section, unless you explicitly marked things as notslides.

Hieroglyph 0.5 adds a couple of features to support these different work modes. First, it adds an autoslides configuration parameter, that allows you to disable automatic slide generation of a project or document level. If autoslides is True (the default), you’ll see the previous Hieroglyph behavior, one slide per section. If it’s set to False, you’ll need to write slides using the second new feature, the slide directive.

The slide directive describes a single slide, including the title, level (which may be used for styling), and content. An example from the Hieroglyph smoketest document:

.. slide:: The ``slide`` Directive
   :level: 2

   In addition to headings, you can use the ``..slide::`` directive to
   define a slide.

Because the conditional slides directive differed by only one letter, Hieroglyph 0.5 also renamed the conditional directives to ifslides and ifnotslides. The previous names will continue to work (at least for a couple releases), but I’m using the new names myself to make it easier to understand what’s going on.

Thanks to bug reports filed in the Hieroglyph github project, the 0.5 release also includes fixes for styling nested lists and compatibility with the latex-pdf builder.

At this point Hieroglyph seems to be working pretty well for me and others. There are a few things I’d like to add yet, but for the next couple of months my focus is going to be more on using it rather than developing it. I’m working on more training for new engineers at Eventbrite, and I’ll be giving a tutorial of Effective Django at PyCon this year. I think both of those are going to be good opportunities use Hieroglyph in different contexts and hopefully get some more data on what’s working or not. If you’re using it (or just trying it out) and have comments or feedback, filing a bug is something I find really helpful.

author:Nathan Yergler
tags:hieroglpyh, sphinx, rst, slides

Hieroglyph 0.3.2: Slide Table and Interlinking

Since PyCon I’ve continued to think about how I can make slides from ReStructured Text documents and vice versa. I tend to write a lot of notes and text while I’m putting together a talk, and I like the idea of being able to keep slides and text output in sync. I’ve just a batch of changes to Hieroglyph, my tool for doing that. There’s some clean-up there — better handling of output paths when using things like blockdiag, code clean-up, etc — but there are two things I’m really excited about. First, two pull requests (one for Python 3 support, another for some documentation bugs), and second some new features that I think make Hieroglyph much more powerful.

Thinking about keeping slides and text (HTML) output in sync, it occurred to me there were probably times you’d want to easily switch between slides that provide an overview, and the HTML document for more details and context. Much of the work for 0.3.2 focused on enabling this interlinking. When enabled, Hieroglyph will add links to your HTML and Slide output that links to the other format. For HTML this can be enabled in the sidebar, as well as at the section level. For slides, the link is added next to each slide’s header, and shows up when you hover over the header. Check it out on the Hieroglyph documentation — just hover over any header and click the § link for the corresponding slides.

When I was working on my PyCon talk, I had anywhere from 50 to 70 slides in the deck at any given time (NB: yes, this is too many for a talk of that length). Navigating between them was challenging at times. The second feature I’ve added to Hieroglyph is designed to address this. When viewing a Hieroglyph presentation, you can now press the Escape key to see the Slide Table.

An example of the slide table in use for the Hieroglyph documentation (full size).

Press Escape again to return to the slide you were on, or click a slide to jump directly to it. You can try this with the Hieroglyph documentation slides.

Finally, what should really be considered the third new feature: expanded documentation. You can find expanded documentation on configuring Hieroglyph, styling your slides, etc in the docs online.

There are several additional things I’m working on for Hieroglyph. As Ilya points out in “All Presentation Software Is Broken”, web analytics are your “free lunch” if you use HTML-based slides. I plan to bake support for that directly into Hieroglyph. As I’m using Hieroglyph, I’m also realizing that slides don’t always correspond directly to sections in a document — sometimes (but not always) they’re a paragraph, list, or something else. Some way to indicate this may be helpful. If you find Hieroglyph useful (or interesting), let me know what you’d like to see.

date:2012-06-05 13:22:29
tags:hieroglyph, rst, slides

hieroglyph: Easy, Beautiful Slides with Restructured Text

I was happy to have my talk proposal accepted for PyCon this year, and happy with the feedback I received on my talk (Django Forms Deep Dive). But as I was putting my talk together the distracting question was not, “what should I say”, but “what should I say it with”. As a mentor once pointed out, “it’s more fun to write programs to help you write programs than it is to write programs.” The corollary I found over the past couple weeks: “it’s more fun to write programs to help you write slides than it is to write slides.”

I was putting together notes using reStructured Text and kept thinking that it’d be nice to generate both slides and longer written documentation from the same source. I’ve used docutils’ S5 generator in the past, but was looking for something a little more polished looking. Something like the HTML5 Slides.

So I wrote a Hieroglyph, a Sphinx builder for generating HTML5 Slides. I presented hieroglyph at the Sunday morning lightning talks at PyCon: you can see the slides, the reStructured Text source, as well as the HTML documentation generated from the same source.

I’m really happy with the output — it looks great in the browser, projects well, and because I’m using the html5slides CSS, looks great on mobile devices, too. I’m even happier that I’m able to work on my content in plain text. You can find the source on github.

date:2012-03-13 22:31:16
category:projects, hieroglyph
tags:python, rst, slides, sphinx

Slides For All Audiences

Tufte tells us that filling our slides with reading material is bad form. I try to keep this in mind when putting together talks (with varying degrees of success), and am reminded of it when I attend a conference. Usually there’s at least one presenter who has really compelling material, but terrible slides. The thing is, they’re probably great slides for certain audiences; namely, the audience not in the room. If you’re reading them after the fact, text heavy slides can give you the full picture, where arguably Lessig-style slides (on their own) can not.

Slideshare, an online site for publishing your slides, has a feature that’s new to me: “slidecasting”.

Slidecasting 101

Slidecasting involves taking an audio track and syncing it with your slides, giving you the best of both worlds. Right now it requires uploading an separate MP3 file and manually syncing it with your slides. Extra effort on the presenter’s part, but arguably worth it if you’re trying to reach the broadest possible audience with the greatest efficacy.

It’d be great if Slideshare supported some standard [“SMIL?” he asks with no real insight into the specification] that allowed you to upload the synchronization information without using their web-based tool. You can imagine an application or plugin that records during a presentation, noting timestamps for slide changes, and generates a set of files immediately suitable for upload.

date:2009-02-18 10:13:34
tags:presentation, slides, spoken word