Editorial Guidelines

Last updated: February 10, 2010

Formatting Your Article

Magazine articles should be delivered in a text file called page.src.txt. 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 articleFor example, suppose you’re writing an article on connecting to a MySQL database; your masthead could look something like the following:

=t=Connecting to a MySQL Database=t=

=b=Marco Tabini=b=

=d=Ever wondered in how many ways you can connect to a MySQL database? Authors of online articles have been debating this very topic ever since MySQL was first developed! This article explores the many facets of database connections—from ”mysql_connect()” all the way to PDO.=d=

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.

Note that you cannot have any line breaks inside the title or byline. Line breaks are, however, allowed inside 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”.

URLs should be enclosed in double square brackets, like this:
You can download the installation file from [[http://www.phparch.com]], and save it to your desktop.

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:

This is the last paragraph of the previous

section.

=h=This is a heading=h=

This is the first paragraph of the next section.

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:

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

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:

<code>

$x = 10;

$y = 20;

echo $x * $y;

</code>

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

IMPORTANT: code listings (inline and external) should be wrapped at 60 characters for magazine articles.

Images

Due to layout concerns, magazine articles should simply refer to external figures, and not attempt to embed them at a specific place in your text. Example:

The screen shot in Figure 2 demonstrates this.

Then, you would place a file called Figure2.png in your article archive.

Callouts

Magazine callouts are placed within the article on an as-needed basis, to help layout. They may be omitted, completely, so don’t depend on their text. Callouts should generally be taken from the article’s main text.

Here’s an example:

{{callout You should never run while holding scissors; it can be bad for your health.}}

Please provide 2-3 callouts with your article. You can place these at the start or end of your text.

Code Listings

Code listings longer than 10 lines should be put into external files and referred to as Listing N. For example, you could write something like:

… for an example of this, see Listing 3.

and you would create a file called Listing3.txt (even if it is a PHP script, use the .txt extension) and place it in a folder called “Listings”, which you will submit along with your article file.

Bio

Please include a short (50 word) bio in a file called bio.txt.

Requirements

Please include a file called requirements.txt that outlines what versions of PHP and other software you have used. Related URLs or any other special requirements should be included in this file as well. Example:

Requirements

PHP: 5.1+

Other Software: MySQL 5.0+

Related URLs:

- [[http://www.mysql.com/]]
- [[http://pecl.php.net/pdo]]

You should always use a UTF-8-compliant text editor to create your text files. This will ensure that all special characters are encoded properly for our system to read.

Submitting Your Finished Article

You can just store your article, together with your figures, in a .zip or .tar.gz article and e-mail it directly to your editor.

Don’t Panic!

If any of these guidelines seem too complex, don’t panic! Your editor is here to help.

Don’t get too hung up on formatting; these guidelines are intended to smooth the editorial process, but we’re much more concerned about getting informative text from you, the expert, than on having it formatted perfectly.