Overview of Canthology

Ciaran McHale
www.canthology.org



Contents

1  Introduction

Canthology (an abbreviation of create anthology) is software that makes it easy to create documents, particularly anthologies. I start this paper with a worked example to provide an overview of Canthology’s basic capabilities. Then, I briefly mention some of Canthology’s other features. I conclude this paper with some hypothetical case studies that show a variety of uses for Canthology.

2  A worked example

Let’s assume I want to create an anthology, entitled Seasonal Holidays, that contains short stories about how individuals spend their holidays at different times of the year. In the following subsections, I explain the simple steps that are required to create this anthology with Canthology.

2.1  An Example Story with Markup Commands

One short story for the anthology is shown in Figure 1.

Figure 1: The summer.tex file
\chapter{What I did During the Summer Holidays}
\chapterAuthorInfo{Anne Other}{Undergraduate student}
 
For the past few years, I had a summer job working at a local factory. Unfortunately, with the recession, the manager wasn’t hiring anyone this year. Most of my friends had summer jobs, so I got \emph{very} bored hanging out by myself.
 
To keep myself occupied, I decided to do some volunteer work at a local community centre. While there, I worked at a wide variety of tasks. I swept the floor. I made refreshments during coffee breaks. I proofread documents. I ordered new stationary supplies. Occasionally, I staffed the reception desk. I helped people with poor literacy skills to fill in forms. I repainted a corridor. And all that was during my \emph{first week} there!
 
The work was endlessly varied, which kept it interesting and made each day seem like a new adventure. And it meant that I picked up a wide variety of practical skills.
 
I volunteered at the centre five days a week, for most of the summer, taking just a two-week break to go on holidays. It was the most enjoyable job I’ve ever had.

The story is stored in a file that has a ".tex" extension, for example, "summer.tex". The story is written as plain text with embedded commands that specify how to markup, (that is, format) the text. For ease of reference, the markup commands are shown in a bold font. Although the example is very short, it illustrates some of the markup commands that are commonly used with Canthology:

Let’s assume I collect four short stories, and store these in files called "spring.tex", "summer.tex", "autumn.tex" and "winter.tex".

2.2  Creating a Starting-point Canthology.cfg File

The next step is to write a configuration file that tells Canthology how to combine those stories into a book. To do this, I run the following command, which instructs Canthology to create a starting-point configuration file called Canthology.cfg:

canthology -create Canthology.cfg

The contents of this file are shown in Figure 2. In the discussion that follows, I focus on the lines written in a bold font.

Figure 2: Starting-point configuration file 
@include getenv("CANTHOLOGY_HOME") + "/etc/defaults.cfg";
anthology1 {
    @copyFrom "book:a4";
    root_file {
        preamble = preamble + [
        ];
        base_name = "my-anthology" + macro.paperSizeSuffix;
        front_matter = [
            "\input{titlepage-template-1.tex}",
            macro.tableofcontents,
        ];
        main_matter = [
        ];
        back_matter = [
        ];
    }
    substitutions.search_replace_pairs = [
        # search string              replace string
        #---------------------------------------------
    ] + substitutions.search_replace_pairs;
}

Some lines in the configuration file contain name=value statements. Such statements can be grouped together inside a named scope. A scope takes the form of a name, an opening brace ("{"), the contents of the scope, and finally a closing brace ("}"). There are two scopes in Figure 2. The first is called anthology1, which extends down to the end of the configuration file. The second scope, root_file, is nested inside the anthology1 scope.

Keywords, such as @include and @copyFrom always start with "@". The @include statement at the start of the configuration file is used to access the contents of another file that contains default values. That included configuration file actually contains several sets of default values. Each set is in a separate scope within the file. The @copyFrom statement in Figure 2 copies the default values from the book:a4 scope. As its name suggests, that scope provides default configuration values suitable for creating a book (as opposed to, say, an article) that is formatted for A4 paper. If I want the book to be formatted for, say, US Letter paper, then I need only edit the configuration file to change "book:a4" to "book:letter". Likewise, using "book:a5" is appropriate if I want the document to be formatted for A5 paper (which is half the size of A4 paper, and is slightly larger than the paper used in a paperback novel).

2.3  Adding Chapters to the Anthology

A book can be composed of three parts: front matter (such as the title page and table of contents), main matter (the chapters of the book), and back matter (glossary, index, and so on). These are represented in the configuration file by variables called front_matter, main_matter, and back_matter. I will first add some contents to the main matter. I do this by adding strings of the form "\input{filename.tex}" to the main_matter variable. (The \input command specifies that the indicated file should be processed as part of the book.) I also take the opportunity to change the paper size to A5. The result is shown in Figure 3.

Figure 3: Adding chapters to the configuration file 
@include getenv("CANTHOLOGY_HOME") + "/etc/defaults.cfg";
anthology1 {
    @copyFrom "book:a5";
    root_file {
        preamble = preamble + [
        ];
        base_name = "my-anthology" + macro.paperSizeSuffix;
        front_matter = [
            "\input{titlepage-template-1.tex}",
            macro.tableofcontents,
        ];
        main_matter = [
            "\input{spring.tex}",
            "\input{summer.tex}",
            "\input{autumn.tex}",
            "\input{winter.tex}",
        ];
        back_matter = [
        ];
    }
    substitutions.search_replace_pairs = [
        # search string              replace string
        #---------------------------------------------
    ] + substitutions.search_replace_pairs;
}

2.4  Running Canthology

To get Canthology to process the contents of its configuration file, I can run the command:

canthology -f Canthology.cfg

The "-f" command-line option is used to specify the name of the configuration file. If this option is omitted, then Canthology defaults to using the file Canthology.cfg. So, if my configuration file is called Canthology.cfg, then I can tell Canthology to process it by running the (shorter) command:

canthology

2.5  A Formatted Short Story

When I run Canthology on the configuration file shown in Figure 3, it creates a PDF file containing a title page, table of contents, and four short stories. First, let’s focus on the short story that was previously shown in Figure 1. The PDF version of this short story is shown in Figure 4.

Figure 4: The formatted short story

You can see that the \chapter command has formatted its parameter (the title of the chapter) in a large font. The \chapterAuthorInfo command has placed its parameters (the name of the story’s author, and a personal detail about her) in the top-left corner of the page. Finally, the \emph command has emphasised its parameter by writing it in an italic font.

2.6  The Table of Contents

Now let’s turn our attention to the front_matter variable, which contains two strings:

front_matter = [
    "\input{titlepage-template-1.tex}",
    macro.tableofcontents,
];

You may think that macro.tableofcontents does not look like a string, because it is not surrounded by double quotes. Actually, it is the name of a variable that is defined in another file that was included at the very start of the configuration file. The value of that variable is a command that causes a table of contents, like that shown in Figure 5, to be generated.

Figure 5: The book’s table of contents

Notice that the table of contents lists the title of each chapter (specified as the parameter to the \chapter command) plus the chapter’s author (specified as the first parameter to the \chapterAuthorInfo command).

2.7  Creating a Title Page

The first string in the front_matter variable is:

"\input{titlepage-template-1.tex}"

When creating a book, I do not have to write the "titlepage-template-1.tex" file, because it is included in the distribution of Canthology. That file provides the layout of a title page for a book, but with placeholder text for the title and subtitle of the book, the name of the author or editor, publisher, and so on. Figure 6 shows the default appearance of this title page.

Figure 6: The template title page

My next step in preparing the book is to edit the Canthology.cfg file to specify some replacement text for the title page. You can see how I do this in Figure 7.

Figure 7: Specifying search-and-replace strings for the template title page 
@include getenv("CANTHOLOGY_HOME") + "/etc/defaults.cfg";
anthology1 {
    @copyFrom "book:a5";
    root_file {
        preamble = preamble + [
        ];
        base_name = "my-anthology" + macro.paperSizeSuffix;
        front_matter = [
            "\input{titlepage-template-1.tex}",
            macro.tableofcontents,
        ];
        main_matter = [
            "\input{spring.tex}",
            "\input{summer.tex}",
            "\input{autumn.tex}",
            "\input{winter.tex}",
        ];
        back_matter = [
        ];
    }
    substitutions.search_replace_pairs = [
        # search string              replace string
        #---------------------------------------------
        "(TITLE-PLACEHOLDER)",       "Seasonal Holidays",
        "(SUBTITLE-PLACEHOLDER)",    "",
        "(AUTHOR-PLACEHOLDER)",      "Edited by Ciaran McHale",
        "(DESCRIPTION-PLACEHOLDER)", "Inspirational stories",
        "(PUBLISHER-PLACEHOLDER)",   "Legendary Books Ltd",
    ] + substitutions.search_replace_pairs;
}

When I rerun canthology, the title page will look like that shown in Figure 8.

Figure 8: The title page

The anthology is now complete. With just a few markup commands and a configuration file, I have turned a collection of short stories into a professional-looking book, complete with a title page, and table of contents that lists the name of each story’s author underneath the story’s title. Although the example anthology is a short one, it illustrates the main benefit of Canthology: it takes care of the formatting issues involved in typesetting an anthology, so that editors and authors can focus on the contents.

3  Other Capabilities of Canthology

The worked example has shown that Canthology is easy to use for a small anthology. But you may be wondering if Canthology is flexible enough to be used for more ambitious writing projects. The answer is yes, as I briefly discuss in this section.

Canthology acts as a “simplification wrapper” around the LaTeX typesetting system. Thus, the full power of LaTeX—which has been used by professionals for over 25 years to typeset beautiful looking books—is available to users of Canthology.

Canthology provides default configuration scopes—such as book:a4, book:letter and book:a5—for producing PDF versions of an anthology, formatted for different sizes of paper. Canthology also provides other configuration scopes—such as book:html-one-page and book:html-many-pages—for producing HTML versions of an anthology that are suitable for hosting on a website. The book:html-one-page configuration scope produces a monolithic HTML page that contains the entire book, while book:html-many-pages creates a separate HTML page for each chapter of the book.

Canthology provides simple-to-use commands that can be used to place a graphic image in the background of a page. So, if you want the title page of your anthology to consist of text (the book’s title, author and so on) written on top of, say, a background photograph, then that can be achieved easily.

If you refrain from using the chapterAuthorInfo command, then the details of an author will not appear in the table of contents or at that start of a chapter. This enables you to use Canthology to write “normal” books, not just anthologies.

Canthology is free software and is provided with a comprehensive manual that explains how to install and use it.

4  Uses of Canthology

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

4.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:

  1. 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.
  2. John spent a few minutes editing the text of each poem, putting it into the straightforward markup format required by Canthology.
  3. 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.
  4. 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).
  5. 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.
  6. 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.

4.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.

4.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.

4.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.