1. Introduction

1.1. Abstract

Creating Open Courseware Using Free and Open Source (FOSS) Publishing Tools

George K. Thiruvathukal, Andrew Harrington, and Konstantin Läufer: Department of Computer Science

The presenters will provide a hands-on tutorial for how to organize course materials using the methods created by the FOSS community. We will cover an emerging class of documentation tools that are based entirely on simple plaintext authoring and look at simple authoring languages. We’ll demonstrate that although these tools were created for software developers, they in fact are general enough to support writing across all disciplines (e.g. humanities, arts, social sciences, life/physical sciences, and mathematics) and are straightforward to learn. These tools also facilitate version control and shared repositories for works in progress with multiple authors.

1.2. Topics

• Plain text authoring
  • Rationale for using plain text authoring tools
  • The tool we use: Sphinx
  • Example (this talk!)
• Collaboration tools
  • Version control (Mercurial is our example)
  • Free online repositories for joint work (Bitbucket)

1.3. History of Plaintext Authoring

Plaintext authoring has a long history. Before there were word processors, there were much simpler systems that were focused only on text, and formatted as a second step. These systems are very much still with us today.

• text formatting programs such as nroff (and groff)
• generalized markup (HTML, XML, and SGML)
• typesetting software: TeX, LaTeX
• emerging alternatives to markup: reStructuredText and Markdown

The emerging alternatives are the subject of this demo and tutorial.

1.4. Rationale

Plaintext editing represents a rather ironic direction for text editing.

Word processors were supposed to simplify writing. There are a couple of issues with them that have developed over time:

• Word processors (e.g. Word et al) became more about features than the core task of writing.
• “Simple” editing is generally interpreted as WYSIWYG (What you see is what you get).

WYSIWYG may be OK if you are only looking to generate a document in a single format, but if you want to generate multiple formats simultaneously (html, pdf, epub for ereaders, ...), it is important to separate

• the content and the classifications of parts
• the way they end up being displayed in (one of several) final products

For instance with a WYSIWYG editor you do not necessarily use the right abstractions: you may use concrete styles (e.g., italics, large bold) instead of abstract uses (e.g., emphasis, section heading).

In the end, we’re not proposing that folks don’t use word processors, but we will focus on what is gained by keeping the final product in plain text.

For us, there are many advantages:

• lightweight
• easy to keep in a version control system and collaborate
• no licensing fees
• automated indexing and cross-referencing
• supports transformation to a myriad of formats–including Microsoft .docx itself!
• supports proper targeting of different devices (desktop, web, mobile, e-readers) with nearly zero effort!

The list goes on...