Authoring Online Articles

Online articles should be delivered in a text file called page.src.txt. You can just store your article, together with your figures, in a .zip or .tar.gz article and send it directly to your editor. To make things simpler for our readers, listings are just embedded directly in the article's code; our system automatically reformat long listings so that they won't take up too much screen space.

Your article should be composed of two sections: the masthead and the body.

The Masthead

The masthead of your article must contain three elements:

• A title
• A byline, which indicates the name of the author
• A deck, which provides a brief “teaser” for the article

For example, suppose you're writing an article on connecting to a MySQL database; your masthead could look something like the following:

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, while =b= indicates the beginning and end of the byline, and =d= indicates the beginning and end of the deck.

The Body

Once you have completed the masthead, you can move on to the body of the article. 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 article into smaller units that the reader can use as reference points to navigate the text. Ceres only recognizes one level of headings, identified by the =h= 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).

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 article 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 can be embedded in your article by using the {{figure}} tag:

This will result in the following:

Images are floated on the current paragraph, and you can align them either to the left, right or center.

Note that you should never embed external images (we did here just to give you an idea of what the figure tag looks like). Instead, you should store your images in a folder and reference them by filename only. You can them archive the folder together with your article and send it to your editor.

For example, suppose you have two images: figure1.png and figure2.jpg. You can store both images in the img folder that you send together with your article to the editor, and then reference them as follows:

Callouts

A callout 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:

This will be rendered as follows:

Page Breaks

Page breaks can be inserted using the {{pagebreak}} tag on a line of its own:

An article can have an arbitrary number of page breaks; the system automatically maps the index to the appropriate page and regenerates any dynamic content required on a per-page basis (such as client scripts, for example).

Ceres Resources

• How Ceres Works—a basic introduction
• Authoring Magazine Articles—for authors who write articles for publication in php|architect or Python Magazine
• Authoring Book Chapters—for authors who write books for our NanoBook series

 

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