Libretto Research

Back in March of 2015, we did some libretto research. We were thinking of writing our first musical. While that didn’t happen that year, the research remained. Here’s the edited and updated notes regarding writing a libretto with reStructuredText.

We were pointed to http://kierenmacmillan.info/perfect-musical-libretto-format/ as a good example of a libretto. We liked it. It looked good. We can now produce something quite similar, from a completely text-based format.

We’re not 100% sold on all-caps for any use-case, but we understand the need for something. Unfortunately, there’s some inconsistency between the way the actors roles are formatted.

Which is to say, it led to some compromises. Our current design uses “small caps” and bold for the actor roles universally for the HTML-based output formats.

Between ePUB not supporting everything, and good “small caps” support being hard to find in many fonts, the ePUB styles change this to just upper-case. To us, it doesn’t look as good as it does with Small Caps, but it looks better than poor Small Caps support. (Bold, Italic small caps really showcases when they’re “fake” small caps.)

The Kieren MacMillan example had some novel wrapping for the speaking lines, and we opted for a simple hanging indent. We’re not sure how to do the novel method with reStructuredText without using a table, and that just gets ugly.

We use:

.. role:: actor
.. role:: action

.. default-role:: actor

This allows us to use simple `back-ticks` for actors and they can get formatted properly regardless of the context. The “action” is a block style which is italic. This allows additional character styles — such as “actor” — to work properly.

This also means that the setup paragraph is done like so:

.. container:: action

   (The stage is set like a police line-up. Three villains are in the
   line-up: the `Big Bad Wolf`, `Goldilocks`, and `Troll`. There is an unnamed
   detective -- who we refer to as '`Cop`' -- and three large uniformed
   `Constables`. `Jill` is viewing the police line-up and referring to her
   rather large fairy tale book.)


There wasn’t a lot of good alternatives to the use of “container”. The standard emphasis style is a character style and required special work to get actors to be properly styled. (They couldn’t really be properly styled inside *emphasis spans* but you could mostly fake it by breaking the spans up).

The empty comment (..) is needed to prevent the sung part that follows this from being seen as being within this container.

In any case, this is the only way to get the actor to have both the styles of “action” and “actor”. We’re loath to drop the `back-ticks` and just use capitalized letters for this. It really does produce nicer output this way.

We had some problems settling on how the song-text would be included. We needed to make sure that simple things would be simple. After messing with it for a bit, We settled on::


    | This is a fairy tale ending.
    | Where everything seems okay:
    | A lesson learned and life returned
    | To the way it was before.
    | When one door closes, another one opens,
    | And no one is sad anymore.
    | This is a fairy tale ending.

The actor becomes a “block-quote” and that’s set to center the text, while the rest is a “line-block”. This has the idiosyncrasy that a one-line sung part still needs to be marked as a line-block, or it will be formatted like an actor and not like a sung line.

We didn’t see an option for simultaneous parts other than tables. With the above solutions in place, this is as straight-forward as you might expect. Here’s two parts, one part, and three parts::

=============================  =======================================
`Jack & Jill`                  `Chorus`
=============================  =======================================
It's not a fairy tale ending.  | Something is wrong.
                               | Something has changed.
                               | Events have rearranged.
                               | And happy ends have been exchanged.
It's not a fairy tale ending.  | Something's amiss.
                               | Something's awry.
                               | The magic well is dry.
                               | and none can willingly supply a remedy!
=============================  =======================================


        | Rumpelstiltskin kidnaps babies,
        | Snow White choked on an apple core,
        | Little Red Riding Hood contracted rabies...

================================= ================================= ======================
`Sopranos`                        `Jill & Altos`                    `Men`
================================= ================================= ======================
| Once upon a time                | That's not a fairy tale ending, | A fairy tale ending,
| there was a happy ending, [...] | [...]                           | [...]
| there was a happy ending!       | not a fairy tale ending!        | ending!
================================= ================================= ======================

The “Chorus” part explicitly needed the line block characters (|) as otherwise the table looks like there are only two rows and the second column is multi-line. With the line block characters, the table itself can be processed like that, but it doesn’t phase the processing.

The three-part section had the line block characters added, but they don’t seem to make any difference. They’re needed when there are blank lines, but optional when every column has text.

At least, this works fine for normal HTML. The table won’t have a border, and the header row — with the actors — gets indented further. It renders very much like the Kieren MacMillan example.

This won’t work for ePUB, as <table> isn’t supported by ePUB readers. (And renders poorly on tiny screens.) However, Sphinx makes this easy enough to work-around, as you can use alternate formatting for the ePUB reader. Splitting each actor’s section out might be less than ideal for a written page, but it’s totally legible when reading it on a phone. This gives us the best-of-both. See::

.. only:: epub 

   .. rubric:: (Start simultaneous singing.)


        | Once upon a time                
        | there was a happy ending, [...] 
        | there was a happy ending!

        `Jill & Altos`

        | That's not a fairy tale ending, 
        | [...]                          
        | not a fairy tale ending!       


        | A fairy tale ending, 
        | [...] 
        | ending!

   .. rubric:: (End simultaneous singing.)


The “rubric” lines add a notice that what we’re seeing is parallel text instead of serial text. It isn’t ideal, and isn’t the most elegant, but it works really well. It’s also simple to write up and easy enough to read.

The last caveat is that while the paragraphs are set to a hanging-indent, this is purely presentation style. In the reStructuredText it is seen as a normal paragraph::

`Cop`: We'll find the one responsible, don't you worry, miss. This
whole business will be wrapped up in a neat little package of justice,
gift-wrapped in a simple moral to help you understand the human

Beyond that, the only thing left to mention is that the page header and footer are seen by ODT as part of the “style.xml” file and once specified there, you can’t override them via the command-line options. This isn’t a big deal, though, as there didn’t seem to be any way to style the header/footer.

If you’d like to check out the full sample.rst, it is available.

If you’d like to see the EPUB produced by this, please check it out: TheLibrettoExperiment.epub

If you’d like to see the HTML produced by this, please check out: index.html