Editorial Guidelines

Last updated: February 21, 2012

Preparing Your Article

Magazine articles should be delivered in a plain-text UTF-8 file named page.src.txt. Your article should be formatted as follows:

=t=This is the Title of Your Article=t=

=b=This is the byline or author name=b=

=d=This is the deck or brief abstract of your article. This should be approximately 100 words long.=d=

Next is the content of your article. There should be a space between each paragraph, and paragraphs should not be indented.

Please Note:
There are 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. Please do not place any spaces before or after these tags. Line breaks are not allowed inside the title or byline. Line breaks are, however, allowed inside the deck and the body of the article.

Formatting Text

Our system supports the following formatting:

  • Headings or section titles should have =h= before and after, like this:
    =h=This is a heading=h=
    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.

  • 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!
  • 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.
  • Escaping characters is done with a backslash. For example, if you want to enter a URL as plain-text and do not want the double forward slashes interpreted as starting italics, place a backslash in front of the first forward slash, like this:
    http:\//localhost.com/mainDir/

These inline formats can, of course, be combined. For example: //**bold italic**// becomes bold italic.

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 if you are going to indent your code, please use a 3-space indent and be sure to wrap code at 60 characters per line.

If your code sample is longer than 10 lines (not include the opening and closing code tag lines), it should be put into an external file and referred to as Listing N. For example:

… for an example of this, see Listing 3.

Then save your code sample in a file called listing3.txt (even if it is a PHP script, please use the .txt extension) and place it in a folder called “Listings”, which you will submit along with your article file.

Figures

Figures, or images, should be at least 300dpi, and should be saved in a JPG, GIF, or PNG format.

Do not attempt to embed images at a specific place in your text. Instead, name each image file as “Figure1″, “Figure2″, etc., and place them in a folder called Figures. Then refer to them in your text like this:

The screen shot in Figure 2 demonstrates this.
or
You can see how the two charts differ (see Figure 4 and Figure 5).

It is important to use a capital F on Figure and list each figure individually preceded by the word “Figure”.

Additional Files

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 3-4 callouts in a separate file called callouts.txt.

Bio

Please include a short (50 words or so) bio in a separate file called bio.txt.

Requirements

Please include a file called requirements.txt that outlines what version(s) of PHP and other software you need to use in order to replicate the information in the article. If you have URLs that you would like to include, please place them in a Related URLs section in the requirements.txt. file. Example:

Requirements:

- PHP: 5.2+

Other Software:

- MySQL 5.0+

Related URLs:

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

Please list a text description for each URL in the Related URLs section.

Submitting Your Finished Article

You can just store your article (together with your figures, listings, bio, callouts, and requirements) in a .zip or .tar.gz file 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.