Art About – FAQ – Write for us – Contact Info – RSS Feed
Search A/R/T:
php|architect's Author Guide → Ceres, The php|a Authoring System → Authoring Magazine Articles

Authoring Magazine Articles
Click to rate:    
68 votes / avg. rating 22.94%

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:

Listing 1 – Toggle plain text mode – Select listing
  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:

Listing 2 – Toggle plain text mode – Select listing
  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:

  • 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:

Listing 3 – Toggle plain text mode – Select listing
  1. =t=Connecting to a MySQL Database=t=
  3. =b=Marco Tabini=b=
  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!
  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:

  • 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:

Listing 4 – Toggle plain text mode – Select listing
  1. This is the last paragraph of the previous section.
  3. =h=This is a heading=h=
  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:

Listing 5 – Toggle plain text mode – Select listing
  1. This is normal text.
  3. - This is the first element of a list
  4. - This is the second
  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.

  • 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:

Listing 6 – Toggle plain text mode – Select listing
  1. <code>
  2. $x = 10;
  3. $y = 20;
  4. echo $x * $y;
  5. </code>
The source code above becomes:

Listing 7 – Toggle plain text mode – Select listing
  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:

Listing 8 – Toggle plain text mode – Select listing
  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:

Listing 9 – Toggle plain text mode – Select listing
  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:

Listing 10 – Toggle plain text mode – Select listing
  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:

Listing 11 – Toggle plain text mode – Select listing
  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.

 Tags: 
 Add tag(s) (comma separated):
[Tags beta] — [Add New] — [Help]  

Tags Help

Tags are keywords associated with a web page that help classifying information. You can find a good explanation here.

To add one or more tags to this page, simply enter them below (separate them with a comma) and hit enter or click on the "Go" button.

New Comment
This form allows you to type in a new comment. Keep in mind the following:
  • The system accepts input in plain text format. Newlines will be converted to the HTML equivalent, and the system will try to catch most URLs and make them clickable.
  • Your e-mail address will never be displayed. We will use it only to notify you when new comments are posted to this page.
  • As a rule, we do not delete comments unless they are offensive, racist, spam or otherwise inappropriate.
  • Bold fields are required
Your Name:
Your e-mail:
Type this number:
Subject:
Comment:
Comments   New Comment
JSON and Pure AJAX (#503)
By DHIRAJ PATRA on 2007-03-23 03:02:06

JSON use the Ajax technology send request and get the result from server. But the main difference is it use only first time and then keep the result into the java script object so that from next time it can be called from it. Keep the request and result in client for faster process the pages. Downside need the library to be installed through PEAR or else. And then implement it in the php scripts. I want more article from friends. Regards.

[Reply to this]

Re: Authoring Magazine Articles (#511)
By Jim DeLaHunt on 2007-04-02 15:56:26

Your listings above omit blank lines, which makes them harder to understand.

For instance, Listing 4 above intends to make the point that headings need a blank line before and after them, but all I see are lines 1, 3, and 5. Lines 2 and 4, which are blank, aren't displayed. By carefully looking at the line numbers I can figure out that lines 2 and 4 were omitted, but including them would be better.

Hope this helps, --Jim

[Reply to this]

Re: Re: Authoring Magazine Articles (#512)
By williams koli on 2007-04-02 22:05:45

BARCLAYS BANK OF GHANA,
HIGH STREET BRANCH,
TAKORADI KANESHIE,GHANA,

ATT,
My Names are Williams Koli,Iam the regional Manager of Barclays Bank of Ghana of ke
Kaneshie branch in the western region of Takarodi.Iam writing you this proposal in Fiath,I'm 45 years Old,Married with two kids, I Packged this financial transaction that will benefit you and i,as the regional manager of the Barclays Bank of Ghana.
It is my duty to send in financial report to my head office in the capital city Accra,at the end of each business year.ON course of the last year business report i decovered the branch in which Iam the Manager made Three millions five hundred us dollars($3.5m),Which my head office are not aware of,and will never be aware of.I have placed this account on what called Escrow account with no beneficiary,as an officer of this Bank i can not be directly connected to this money,So my aim of contacting you to assist me to recieve this money in your Bank account,

Iam expecting your approval so that can send my documents ie International passport and Bank id card for proper identification of me.
Thanks for cooperation
Best Regards
Williams Koli

[Reply to this]

Index

Copyright © 2002-2007 Marco Tabini & Associates, Inc. — All Rights Reserved
Privacy Policy — Terms & Conditions