The dot-commas ultimately aim to produce an .epub that is as cross-platform compatible as possible. Specifically, our final product will be legible and comfortably-designed for as many different e-readers as possible, although we will prioritize its functionality in more common and more up-to-date software.

Broadly, we want our .epub of What is Code? to be as accessible as possible to multiple audiences. We acknowledge that the original article, written for and published by Bloomberg Businessweek, is targeted to a more corporate or “executive” audience (Bloomberg’s typical readers, and evidenced by the “Man in the Taupe Blazer” narrative), for whom magazine or web formats are highly appropriate. In .epub form, we want What is Code? to reach a variety of casual readers in addition to those reading for information; this necessitates a final document that holds legibility as its primary goal. For example, we agreed that many of the interactive features of the web version of What is Code?, though interesting, were distracting, and were in any case highly inappropriate to an ebook format. We believe that prioritizing general ease of use and access complements Paul Ford’s aim in writing, which is to educate on a topic that often seems confusing or complicated.

Major Changes

The online version of What is Code? incorporates several unique interactive features and animations, such as the interactive keyboard or the questionably-charming blue robot character, but these can often be distracting to the reader. They are entirely inappropriate for e-readers, especially given the smaller screens; furthermore, most are non-functional in all but the most recent technology, breaking completely in older readers.

In-line pop-ups are also a feature of the website’s HTML, which we are using to build our .epub. They contain both notes, which supplement the text, and acknowledgements of corrections or help, usually from github users. Pop-ups will absolutely not work in the most widely-usable .epub format, and while they will not display, they should nevertheless be removed. We will attempt to reformat the notes, and will attach a page of acknowledgements at the end of the .epub as necessary.

ss_wic_3 ss_wic_4 ss_wic_5 ss_wic_6

Finally, when most of the necessary HTML has been written, we will rearrange objects remaining in the text (images, notes, &c) to better fit the .epub layout. This will have to be done on a case-by-case basis, but will particularly apply to the larger images found near the ends of sections, or to supplementary info, such as the “productivity” object, whose size can cause them to mess up formatting or not display properly.


Making our .epub widely usable as well as consistently attractive compels us to keep in mind the requirements of a range of popular devices, which differ not only in performance and compatibility (i.e. with specific EPUB3 features) but also in their displays, from low- to high-resolution and featuring a variety of e-ink, e-paper, and LCD screens. We questioned whether the document’s many colour images would render properly on monochrome devices, but this is unlikely to pose a significant problem. Taking this into consideration, however, we will try to avoid colour-coding aspects of the text.

Our goal of cross-compatibility requires a re-flowable layout (as opposed to a fixed-layout design, which does not allow text to be resized). This may present a challenge with respect to positioning non-body-text objects; ultimately, we seek to format the publication so that the design does not distract from the information.


Our focus on making What is Code?’s content as readable as possible in .epub form applies not only to legibility but also aesthetic – the resultant text should be engaging and visually pleasing.

We plan to embed specific fonts (particularly for section headers and side notes) into the .epub, with the understanding that, while these may not show up in all e-readers, they will nevertheless display on some. We can also designate alternatives to embedded fonts in CSS; for example, an alternative to Businessweek’s header fonts is Helvetica, followed by Arial, followed by a generic “sans-serif” designation. We can therefore create styles that, while not always applied in e-readers, are nevertheless consistent cross-platform.

In addition, we will assign font sizes proportionally rather than use absolute values, as per this guide, since many e-readers allow the reader to increase or decrease font sizes. Working in ems also allows us to size smaller images in proportion to the text, such as these graph icons in section 2.4: beforeaftericons

We want to explore the possibility of including the supplementary information (i.e. pop-ups) and small images from the original text as side notes or (as a last resort) foot-notes. This seems possible using the “float” CSS property. Since it is generally inadvisable to include text (i.e. captions) as image files, likely due to compression, we plan to apply this property to containers of text as well as to images.

We’d like to keep the “letter from Josh,” a pop-up in the original web text, as an introduction/preface to the essay itself. It would be included as pseudo-frontmatter and formatted so as to distinguish it from the body of the text. We can achieve this either by breaking the text into multiple HTML files or by using the CSS selector “page-break-before: avoid.” This section would, of course, not be included in our table of contents. Other data pertinent to the epub, which in a traditional book would be found in the front matter, can be written into its metadata, since it is rarely relevant to the overall reading experience.

While importing the CSS from the web version of the article will allow us to keep many aspects of the original design, we must also be wary of constraining ourselves design-wise, and make choices specific to our format.


Our overall style will be derived from the Businessweek-original CSS, downloadable along with the HTML. It can be applied when using pandoc to create our .epub, or otherwise by simply cutting and pasting the code into the automatically-generated empty stylesheet. It is worth noting that this cut-and-paste method cannot be used for HTML, since the .epub uses XHTML, which is slightly different, and which pandoc converts.

Using this received CSS, though convenient on the whole, will require us to carefully check for unused classes or styles, especially if those styles don’t apply in .epub. Overlooking some residual broken code could have a disastrous and frustrating effect on our .epub, so it is vital that we understand what we are leaving in as well as taking out.

A well-formatted stylesheet will be instrumental to our .epub. To ensure consistency, we will try to apply styles using CSS rather than HTML as often as possible. This does not preclude a need for formatting in HTML, however, as we have found that some objects do not retain all of their designated styles in the actual .epub. It seems that some large images, for example, despite having a designated “max-width: 100%”, will still display too large unless the ‘width=”100%”‘ is applied within their individual HTML tag.


We plan to include as many of the original pictures from BBW as possible; this includes the more “artistic” photographs as well as informative graphs and maps. We will also consider producing additional informative images (e.g. explanatory screenshots), to further supplement and break up the text, and finding alternative images for the animated .gifs and videos that we wish to remove. It is important that all our images be formatted correctly; we can resize each images as needed using  “width=%.”

Much of the image formatting will have to be applied on a case-by-case basis, although this is something CSS and RegEx can thankfully help with. Some of the document’s more unique visual elements, such as the array of conference photos or the “productivity” list, may benefit from being formatted as tables to better fit the page.

Both pandoc and Calibre allow us to create our own cover for the .epub and to identify it specifically as such. We found the website’s animated header far too gaudy, so we will create an original cover that is simple, attractive, and representative of the material. The image itself simply needs to be created in InDesign and exported as a .jpg.

cover option: incorporates major colours from web article

cover option: incorporates major colours from web article

cover option: simplified version fashioned after print magazine

cover option: simplified version fashioned after print magazine



To ensure usability on as many devices as possible, we will repeatedly test our .epub throughout the design process, using tools such as Calibre, Adobe Digital Editions, Amazon’s Kindle viewer, Kobo Desktop App, and iBooks, as well as the EpubCheck online validator.

After using pandoc to convert the web article’s HTML into a rough .epub, we will use Calibre to further refine the document. We can use Calibre to edit every aspect of our .epub, and to work backward from the original document rather than starting from scratch. Calibre shows a live preview of the .epub as we code, which gives us the ability to check for major errors while we work. In particular, it will allow us to view every file contained in the .epub, such as image files, font files, navigation files, and each .xhtml file in the spine. This feature will be key to our work, since we can divide the HTML into individual chapters in order to work simultaneously and together.


In the final stages of .epub construction, we encountered a serious problem caused by floated objects, which are supplementary notes and images in the document itself. In some readers, floated text or images, if their container is too big to fit on the page, will cut to the next page, taking all following text with it and leaving large, awkward gaps in the main text.

The CSS selector “page-break-inside: auto” remedies the problem in some readers, such as Calibre and iBooks, but does not seem to be supported in others.

One option would be to cut down on supplementary material, slashing most floated objects to maintain continuity of style across readers and throughout the document. Part 2.4 in particular is full of notes that interfere not only with the text arrangement but also with lines of code, which don’t always wrap around them properly; it could benefit from some pruning. Elsewhere, however, the notes add some levity to an otherwise-dense text.

A final solution might be to consign our notes to the end of each section, where they won’t interfere with the overall flow of the text; this would be achievable through creative use of hyperlinks, but would be distracting to the reader, and is thus a last resort.

Table of Contents

Tables of contents in .epub seem to be created in two different file formats: nav.xhtml and .ncx. Both will be relatively simple to create. Calibre will even automatically generate a .ncx file from designated headings; though the nav file must be created manually, it consists of a simple ordered list, properly linked. The table of contents will be a final step, to be done once most other work is complete. We are unsure whether the inclusion of sub-headings will improve readability or make the text seem overwhelming; a possible solution to this is creating multiple levels within our table of contents, and thereby enabling readers to hide sub-headings as desired.


To complete our .epub, we plan to work together in the same space, so that we can get things done efficiently and help each other when needed.

All group members will install and become familiar with Calibre, working with the .epub document created in pandoc (to be completed by Sept 20).

Alanna will investigate the matter of the title page, including both design and file format requirements (to be completed by Sept 25th). She will revise the book cover we made in InDesign to use the fonts we embedded into the .epub file (in the titles) which are the same fonts that were used in the online magazine article (to be completed by Sept 30). She will attempt the coding for implementing the ‘letter from Josh’ pdf she has made into the ebook as front matter (to be completed by Oct 1). This pdf may or may not be used in the final product because it might be easier to code the existing ‘letter from Josh’ in the text of the document to look like the rest of the .epub and exist as front matter.

To convert the existing footnotes into side notes, we will go through and input the footnote text directly into the ebook (to be completed by Sept 25, by Alanna, Zoë and Sarah). From here we will experiment on how to convert these into side notes using CSS formatting (to be completed by October 1, by Katherine). We believe that to do this we will have to remove the existing footnote formatting and put footnotes into separate containers (divs).

Katherine will look into creating the table of contents and how to create an .ncx document (to be completed by Sept 28), compatibility issues, and how to include such a file in an .epub (to be completed by Sept 30). She will also embed title fonts, split the main text into separate HTML documents (to be completed by Sept 23), and research image formatting (to be completed by Sept 28). Katherine will also be responsible for re-doing the CSS style sheets and uploading them to Slack so the rest of the group can apply them to our copies of the .epub (to be completed by Sept 25). As our team member in charge of CSS, Katherine will code the page breaks and flowing text using CSS (to be completed by Sept 25).

Alanna and Zoë will search for remaining Javascript left in the document and deleting it (to be completed by October 1). They, along with Sarah, will delete the presumptuous blue robot .gif (to be completed by Sept 25).

Once the HTML is converted to .epub using pandoc, Zoë will comb through it to remove remnants of interactive elements and animations (To be completed by Sept 25).

David will look specifically into how to format and size grids for images (with the intention of creating relatively unobtrusive sidenotes) (to be completed by Sept 25). He will also compile list of potentially-useful HTML tags for resizing images and document elements (to be completed by October 1).

Sarah will look into colour compatibility issues as well as different methods of testing the completed (or in-progress) .epub (to be completed by Oct 1). She will investigate using Adobe digital editions, iBooks and other e-reading platforms to test our .epub (to be completed by Oct 5). These tests will provide us with information on whether or not colour pictures will show up in grayscale on e-readers using e-ink or whether they will show up as errors.

All team members will work on sections of HTML, which we will divide into chapters. We have shared these chapters using Slack and once we have updated a chapter, we will post the current chapter on Slack and delete the previous, outdated chapters.

Week One Week Two Week Three Week Four
Install and become familiar with Calibre using .epub of What is Code?
Investigate title page, including both design and file format requirements
Revise title page with fonts used by BBW
Look into implementing the ‘note from Josh’ as front matter
Convert existing footnotes to sidenotes using CSS styling
Create table of contents and investigate creating a .ncx file
Research responsive images
Redo CSS style sheet
Remove interactive elements and animations
Apply styles to images
Test cross platform compatibility
Modify and correct metadata
Rearrange text and image content to better suit epub format