Authoring Magazine Articles

Current Issue
Subscribe Now
Free Issue
Back Issues
Why Subscribe
Write for Us
Advertise

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

Magazine aricles are a little different from online articles. Code listings longer than 6 lines should be put into external files and referred to as Listing N. For example, you could write something like:

  1. ... for an example of this, see Listing 3.
... and you would create a file called Listing3.php for inclusion of your article archive.

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

If your article's content has any special requirements of the reader, be sure to include a file called requirements.txt that outlines these. Example:

  1. Requirements
  2. PHP: 5.1+
  3. Other Software: MySQL 5.0+
  4. 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.

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

The Masthead

The masthead of your article must contain three elements:

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

  1. =t=Connecting to a MySQL Database=t=
  2.  
  3. =b=Marco Tabini=b=
  4.  
  5. =d=Ever wondered in how many ways you can connect to a MySQL database?
  6. Authors of online articles have been debating this very topic ever
  7. since MySQL was first developed!
  8.  
  9. This article explores the many facets of database connections—from
  10. ''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:

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:

  1. This is the last paragraph of the previous section.
  2.  
  3. =h=This is a heading=h=
  4.  
  5. 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:

  1. This is normal text.
  2.  
  3. - This is the first element of a list
  4. - This is the second
  5.  
  6. - This is the beginning of a new list
  7. - And this is its second element
The source code above will be rendered as follows:

This is normal text.

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:

  1. <code>
  2. $x = 10;
  3. $y = 20;
  4. echo $x * $y;
  5. </code>
The source code above becomes:

  1. $x = 10;
  2. $y = 20;
  3. echo $x * $y;
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:

  1. <code php>
  2. $x = 10;
  3. $y = 20;
  4. if ($y > $x) {
  5.   echo $x * $y;
  6. }
  7. </code>
This will result in the following:

  1. $x = 10;
  2. $y = 20;
  3. if ($y > $x) {
  4.   echo $x * $y;
  5. }
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.

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:

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

  1. {{callout You should never run while holding scissors;
  2. 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.

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.

Please do read this document, and help us when possible, but formatting the article properly is ultimately your editor's job.

Ceres Resources