Authoring Book Chapters

When authoring a book, you will be provided with an account into a CVS repository. Since all the source files for your book are text files, CVS provides us with a ready-made solution that makes it possible for all the people involved in your project to collaborate freely.

File Structure

Each chapter of the book should be stored in its own directory inside the root of the repository. The directory should be named according to the chapter title, so that it can be easily told apart from the other chapters in the book. For example, if your chapter's title is “Extending Web Services,” the directory could be called extending_web_services. Note that, at this stage, we do not assign a chapter number in any form—this is done automatically by our software when it generates the final PDF of the book, depending on how we order each chapters in the layout phase.

The chapter's source file should be stored inside the directory and given the name chapter.src.txt. This will make it readable to any text editor on your end, while on our end the system will recognize it and compile it.

The chapter's directory can also contain an optional figures sub-directory, which can be used to store figures for the chapter.

The Title

The title of your chapter should go at the very beginning of the source file. For example, if the chapter's title is “Extending Web Services,” its source file should start as follows:

As you can see, Ceres uses special tags to indicate the beginning and end of each element. For example, the =t= tag is used to indicate the beginning and end of the title.

The Body

Once you have completed the masthead, you can move on to the body of the chapter. Here, there are only a handful of rules to keep in mind.

First of all, for the most part you can type your text directly as if you were using a word processor; if you need to use characters outside the standard ASCII set, such as accented letters, em-dashes, and so forth, you can type them directly without having to worry about special encoding. On those operating systems that do not support extended character sets natively, most editors usually provide key combinations that make it possible to enter them anyway.

In any case, you need to ensure that, if you use non-ASCII character, your text editor is capable of saving files in UTF-8 format. This is very important, as our system may be unable to properly display your text otherwise.

Other than this particular precaution, there is very little that you need to worry about; paragraphs in your text are separated by two newline characters (in other words, press Enter twice and you've started a new paragraph), and there is no need to indent the first line of a new paragraph.

Formatting Text

Our system supports three types of inline text format:

• Bold text is created by enclosing the portion of text you want to format in double asterisks; for example, **some bold text** will be formatted as some bold text
• Italic text is enclosed by double forward slashes; for example, //some italic text// becomes some italic text
• Monospace text is enclosed by two single quote characters at each end. For example: ''monospace!'' becomes monospace

These three inline formats can, of course, be combined. For example: //**bold italic**// becomes bold italic. You can also escape the tag sequences by prefixing them with a backslash. For example, \ //not italic is printed as “//not italic”.

Headings

Headings (like the one above this line) are used to break up your chapter into smaller units that the reader can use as reference points to navigate the text. For book chapters, Ceres recognizes three levels of headings, identified by the =n= tag:

Note that the text of the heading must be all in one line (no line breaks!) and that it must be isolated from the previous and next paragraphs by an empty line.

Lists

Ceres only supports unordered lists. A list block is identified by a line that starts with a dash, followed by a space. For example:

The source code above will be rendered as follows:

This is normal text.

• This is the first element of a list
• This is the second

• This is the beginning of a new list
• And this is its second element

Note that a list must be preceded and followed by an empty line (which tells the parser to stop looking for list elements).

Floating Elements

“Floating elements” are elements outside the normal flow of your chapter's body. These include code listings, tables, figures and callouts.

In our design template, floating elements are actually anchored to the paragraph that precedes them. This makes the term “floating elements” a bit of a misnomer, since listings, tables and figures are rendered inline with the text. You should keep this in mind when writing your chapter, so that you can position these elements accordingly. For example, if you want to introduce a listing, you can reference it as “the listing below,” and then immediately follow that with the listing itself.

Code Listings

Code listings are encapsulated by a <code> tag, which must be on a line of its own:

The source code above becomes:

Note that you should not indent the first level of your code, as the system already provides the indentation for you. You should, however, indent any subsequent levels (using either tabs or spaces). For example:

This will result in the following:

As you noticed in this last example, Ceres supports syntax highlighting for PHP code. In fact, it supports highlighting a large number of different languages, which you can specify inside the <code> tag. The list is too long to include here, but chances are that any language you may need to highlight is actually supported by Ceres—including SQL, XML and HTML.

Tables

Tables can be inserted directly in the body of your chapters using a syntax that is very similar to HTML (but much simpler and stricter). Here's an example:

As you can see, the syntax is very similar to straight HTML. In fact, the only difference is that, instead of using align=“center” or valign=“top”, you simply specify one of left, right, center for horizontal alignment and top, bottom and middle for vertical alignment. As you can see above, the aligment parameters can be used to align both table cells and the table itself.

Here's what the table above will be rendered like:

Position Name	Level	Salary
CEO	Senior	€100,000
Vice President	Senior	€90,000
Senior Architect	Senior	€70,000
Developer	Intermediate	€50,000

Images

Images and figures can be embedded in your chapter by using the {{figure}} tag:

Note that you should never embed external images. Instead, you should store your images in the figures folder and reference them by filename only.

Sidebars

A sidebar is a section of text that the Ceres interpreter highlights for visibility; you can use it for warnings, notes, or to otherwise attract the reader's attention.

Here's an example:

As you can see, a sidebar is composed of the opening tag {{sidebar, followed by a space and the title of the sidebar. You can then press ENTER twice (as if you were starting a new paragraph), followed by the body of the sidebar, which can contain pretty much any other formatting element, with the exclusion of another sidebar.

Ceres Resources

• How Ceres Works—a basic introduction
• Authoring Online Articles—for authors who write articles for publication on our website
• Authoring Magazine Articles—for authors who write articles for publication in php|architect or Python Magazine

 

Copyright © 2002-2008 Marco Tabini & Associates, Inc. — All Rights Reserved — Contact Us
Terms and conditions — Privacy policy (updated 2008/08/20) — Refund policy — Shipping rates

USD and EUR prices are approximate unless paying with Paypal in the respective currency. All credit cards are charged in CAD