Chapter 1 Introduction

1.1 What is Canthology?

Canthology is a software application that makes it easy to create an anthology of, for example, poetry, short stories or recipes. The name Canthology is an abbreviation of create anthology.

Canthology has been developed and tested on Gnu/Linux and Microsoft Windows, but has a good chance of being able to work on other operating systems if you have LaTeX, Tcl and Java installed. (Installation instructions are provided in Chapter 6.)

1.2 Uses of Canthology

The following hypothetical case studies illustrate some of the uses of Canthology.

1.2.1 A Tailor-made Anthology of Poetry for Education

John teaches a one-semester poetry course at university. His course includes the study of twenty poems by eighteenth century poets. In previous years, he required his students to purchase a specific anthology of poems, because that was the only book he knew of that contained all the poems on his course. However, the book was unpopular with students for two reasons. First, the book was bulky and heavy: it contained hundreds of poems and was over 800 pages long. Second, the book was expensive; students did not like having to pay so much for a book when they made use of just a small fraction of its contents.

Canthology enabled John to eliminate the need for the expensive and bulky book for his course. He achieved this as follows:

All the poems on John’s course are old enough that the copyright on them has expired. John decided to use an Internet search engine to find the text of the poems online. He quickly found the text of all twenty poems and saved them onto his own computer, each poem in a separate file.
John spent a few minutes editing the text of each poem, putting it into the straightforward markup format required by Canthology.
Then, John wrote a configuration file that instructed Canthology to combine the twenty files containing poems into an anthology, complete with a table of contents.
By adding a particular markup command to each poem, John arranged for the name of each poem’s author to be displayed twice: once above the poem, and again in the table of contents (where it appeared underneath the poem’s title).
The only thing missing was a title page for the anthology. Rather than create one from scratch, John decided to use a template title page supplied with Canthology. He updated his configuration file to instruct Canthology to replace the template’s placeholders (for the book’s title and author/editor) with his desired text.
Having edited the configuration file, John executed the canthology command. Within a few seconds, his anthology of poetry was created in the form of a PDF file.

Now when John teaches his course, he gives the customised anthology of poems to his students as a PDF file. Some students read it on their laptop or tablet computers. Students who prefer physical books over electronic ones can print the anthology on a university laser printer and add the printed pages to a ring binder containing their handwritten course notes. The students are happy: printing the tailor-made anthology for the course is much cheaper than buying an 800-page book; and the tailor-made anthology is much slimmer too.

1.2.2 An Anthology of Personal Accounts

Mary is a member of a minority group that faces widespread discrimination. She wants to create an anthology of personal accounts written by other members of her minority group. She has two goals for the anthology: (1) to provide inspiration and hope for isolated members of the minority group; and (2) to educate readers from mainstream society about the prejudice faced by the minority group.

Mary finds people who are willing to contribute to the anthology. She asks each contributor to format their submissions using the simple markup format required by Canthology.

When Mary receives all the contributions, she writes a configuration file that instructs Canthology to combine the contributions into an anthology, complete with a title page and table of contents. Mary has a photograph she wants to use as a background image on the title page of the anthology. Canthology makes it easy to do this.

When the anthology of personal accounts is complete, Mary is faced with several possibilities. She could submit it to a publisher, in the hope of getting it published as a paperback book that could be stocked in shops. Alternatively, with the aid of a print-on-demand company (for example, www.lulu.com), she could self-publish the book and sell it though Amazon. Or she could instruct Canthology to convert the book into HTML format and host it on a website.

1.2.3 Showcasing the Expertise of Employees

Jane is the owner and manager of a consultancy company. Jane is confident that her employees are more highly skilled and provide better customer service than employees in most competing companies. However, she has been struggling to find a good way to communicate this message to customers, and she is slowly losing business to inferior competitors who have a larger advertising budget or who undercut her on price.

When Jane discovers Canthology, she develops a plan. Demand for consultancy services tends to be either feast or famine. So, whenever there is a lack of consultancy work to do, Jane gets her underutilised staff to document useful tips in the form of short articles. When a dozen useful tips have been written, Jane uses Canthology to create an anthology, Tips from the Experts, in both PDF and HTML formats.

Jane uses the PDF file to print a booklet that is distributed to customers on her company’s mailing list. Jane integrates the HTML version of the anthology into her company’s website, where it soon becomes indexed by Internet search engines, thus directing potential customers to her company.

1.2.4 Product Manuals

David coordinates the writing of product manuals at a software company. He knows that although Canthology can associate a different author with each chapter or section, that is an optional feature of Canthology. Because of this, Canthology can be used to write a “normal” book—such as a product manual—that has only one listed author. Several features of Canthology make David realise it is especially suited for writing product manuals.

First, because Canthology-based documents are written as plain text with markup commands, his technical writers can use text-oriented tools for working with Canthology. These include: their favourite text editors; utilities such as diff and grep, and a source-code control system, such as SourceSafe, CVS, Subversion, Git or ClearCase.

Second, it is trivially easy for Canthology to produce a document in multiple output formats, including PDF files formatted for different paper sizes, and HTML. Furthermore, it is possible to write a shell script, Makefile or Ant rule to automate this process. His team now produces PDF product manuals formatted for: A4 paper for European customers, US Letter paper for American customers, A5 paper for easier viewing on a computer screen or tablet computer, and HTML for browsing on his company’s website.

While David was evaluating Canthology, he discovered that the Canthology User Guide is itself written as a Canthology-based document. He was able to play around with the source of this 200-page document to experiment with the ergonomics of using Canthology and verify how easy it is to produce a product manual in HTML and PDF formats, even for multiple paper sizes.

1.3 How Canthology Works

Canthology is a simplification wrapper for LaTeX (pronounced “lay-tech” or “lah-tech”), so I will start by providing a brief overview of LaTeX, and afterwards explain how Canthology simplifies the use of LaTeX.

1.3.1 A Brief Overview of LaTeX

LaTeX is a markup language for writing documents. This means a LaTeX document consists of plain text with embedded commands that specify how to markup (that is, format) the text. As an example, Figure 1.1 shows the start of the LaTeX file that I used for writing this chapter. I have used a bold font to highlight the markup commands.

Figure 1.1: LaTeX source for the start of this chapter

\chapter{Introduction} \section{What is Canthology?} Canthology is a software application that makes it easy to create an anthology of, for example, poetry, short stories or recipes. The name \emph{Canthology} is an abbreviation of \emph{create anthology}. Canthology has been developed and tested on Gnu/Linux and Microsoft Windows, but has a good chance of being able to work on other operating systems if you have \LaTeX{}, Tcl and Java installed.

As you can see, the \chapter command starts a chapter, \section starts a section, \emph uses italics to emphasise a word or phrase, and \LaTeX produces the LaTeX logo. Parameters, if any, to those commands are enclosed in braces.

One benefit of LaTeX is that it enables authors to focus on the content and logical structure of what they are writing, rather than be distracted by formatting issues, such as font sizes and the amount of vertical space to leave after a chapter or sectional title.

When using LaTeX to write a book, it is common practice to write each chapter in a separate file, and then write a “root” file that uses an \input command for each of those chapter files. When the book is complete, LaTeX can process the root file (and all the files it inputs) to convert the book into a nicely-formatted document in, say, PDF, PostScript or HTML formats.

It is common for the start of a LaTeX document to contain many markup commands (for example, to specify the page dimensions and fonts to be used, and to format a nice looking title page), which can make it difficult to read and edit. However, once that initial hurdle of markup commands has been passed, the rest of the document tends to have only occasional markup commands, and thus is easy to read and edit.

1.3.2 Canthology’s Approach to Simplifying LaTeX

Canthology uses a combination of techniques to put a simplification wrapper around LaTeX.

The first simplification technique employed by Canthology is to support the following clear division of labour:

A contributor to an anthology is a person who writes a chapter (or perhaps a section within a chapter). Contributors have to learn how to use just a tiny subset of the markup commands provided by LaTeX. Thus, the LaTeX learning curve for contributors is minimal—typically, less than 30 minutes.
The editor of an anthology needs to learn a slightly larger subset of LaTeX markup commands, and must also learn how to use Canthology.
A typographer knows how to customise LaTeX to modify the “look and feel” of the output it produces.

Most anthologies contain material from, say, ten or twenty contributors and are organised by just one editor. Thus, simplifying the LaTeX learning curve for the many contributors has a far bigger impact in simplifying the overall project than does simplifying the LaTeX learning curve for one editor. Part I of this manual discusses the very few LaTeX markup commands that will be sufficient for the needs of most contributors.

Another simplification technique relies on the 80/20 Principle, which is also known as the Pareto Principle. Put simply: 80% of the markup commands in a LaTeX document are concentrated in 20% of the document’s content. Rather than try to simplify an entire LaTeX document, Canthology simplifies just the 20% that contains the most markup. These simplifications benefit the editor of an anthology.

The final simplification technique is that the default settings and template files supplied with Canthology are likely to provide “good enough” typography for most uses. This eliminates the need for a dedicated typographer. However, if an editor is not satisfied with the range of typographical choices provided by Canthology, then she can read books about LaTeX (such as those suggested in Section 9.2) to learn more about how to make the typographical customisations herself. Alternatively, the editor could find somebody with a good knowledge of LaTeX to make the customisations for her.