Editorial Guidelines

Preparing Your Magazine Article

Thanks for being interested in writing for PHP Architect magazine! Here you will find the guidelines for how to prepare your article for us. We use Markdown to prepare drafts of each article and then turn it all into PDF, ePub, and Mobi files as needed. As a starter, you might want to familiarize yourself with the Markdown standard, and specifically the Pandoc extended Markdown documentation:

• Markdown: http://daringfireball.net/projects/markdown/syntax
• Pandoc: http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown

However, we have some more strict guidelines on exactly how the Markdown is submitted to us, so read on for a primer here on some basics and specific formatting that our software expects to see.

General Rules of Thumb

Markdown as a general language supports the inclusion of raw HTML tags, but for our purposes we don't allow them. If there is anything you want to do that normally you'd use HTML for instead of a Markdown native, take a look back at this document and/or Pandoc's documents. There will be another way.

Also note that there are a number of ways to do the "same thing" in Markdown. Headers can be made in 3 different ways, lists in a couple of different ways, and highlighting & code blocks in other ways. It's OK for you to use whatever Markdown/Pandoc will parse, but we will give some examples below of the format that we prefer if you don't have your own preference, as it makes it cleaner on our copy-editors.

Finally, you should be able to render your article in any Markdown editors that you wish to check if what you are creating looks right. If you are having any issues with a character getting interpreted as Markdown that shouldn't be, you can escape it with a backslash (\).

Basic Markdown

Paragraphs

Paragraphs of text in Markdown are simply represented by a blank line:

My first paragraph

My second paragraph which
happens to run on for a few lines

My third paragraph

Headings

Headings are allowed at 5 separate levels (but please try to refrain from using that many; 2–3 should be plenty for a typical article). They should be formatted as such:

# Top level heading - Used for your article title only
## Second level heading
### Third level heading
#### You get the idea
##### That wraps it up.

Emphasis

There are a number of ways that you can show emphasis in text in Markdown by using bold or italics. These are created by surrounding the text in question with some symbols. While there are various options in Markdown for doing this, we prefer that you use _ for italics and ** for bold as it makes for very easy reading:

The following word is in _italics_; however,
**this whole phrase is bold**

Lists

There are multiple kinds of lists that you might want to create in your Markdown. The most common of these are ordered and unordered lists. Unordered lists are created by starting any number of lines with *, +, or -. Sub levels are created by indenting again by at least 4 spaces. Ordered lists work similarly, but you simply use 1. instead:

* This is an unordered list
* With multiple items
    * And a second level
        * And now a 3rd
* That's enough

1. This is an ordered list
2. You can enter the numbers in order
3. So that it visually looks good.
1. Or just keep entering 1 each time
1. Knowing it will do the right count for you.

Monospace (Inline Code)

If you have any code that you are including in the middle of your text (as opposed to as separate listings/examples), then you can just surround it with a backtick `:

So to count the number of characters in a string
the `strlen()` function should be employed.

Code Examples

Where you have code examples that you want to render inline as a separate paragraph—perhaps because you are going to directly reference them in the flow of your text—you can include them by surrounding the block of code above and below with ~~~~. Code entered as an example this way needs to be no longer than 60 characters long on each line and at most 8 lines long. If you need a longer code listing, see below.

~~~~{.php}
$function = function($x) use ($y) { return $x * $y; }
$result = $function($a);
~~~~

You can specify the language (for syntax highlighting) for a code snippet by including a {.php} when opening the code block. Pandoc recognizes a wide variety of languages, typically whatever extension you'd use to save a file will work.

Code Listings

If you need to provide longer code listings, they can be included as separate entries. These should be saved into a separate .php file unique to each code listing, such as listing1.php. You can use almost any file extension here to indicate the language, e.g., listing2.html, listing3.js, etc.

Code inside of this separate file should be formatted the same way (60 characters per line, indented consistently 3 spaces). These code listings should be approximately no more than 100 lines long. In the PDF magazine they will be rendered in a sidebar. In the ePub/Mobi versions, they will be rendered inline.

So as you can see in Listing 1, it's possible to generate an
entire webserver with only 12 lines of code.

[Listing 1](listings/listing1.txt)

Now moving on to our next topic ...

Links and URLs

You can link to online resources in one of two ways. You can use a regular Markdown link to indicate a title for a URL. This becomes a footnote in the print and PDF editions:

For more information, visit the [main PHP Site](http://php.net)

To show a URL as is, surround it with <>:

For more information on PHP see <http://php.net>

Images & Figures

Save these into a figures subdirectory, and name them figure1.png or accordingly. These should be in PNG, JPG, or GIF format, and of high enough resolution for display on any modern screen.

After the user enters their password they will be
presented a screen as shown in Figure 2.

![Figure 2: Terms of Use](figures/figure2.png)

Building Your Article

All files that you send to us should be saved as plain-text UTF-8 files. You should submit to us a .zip or .tar.gz file containing a full directory structure of files that together make up your article:

article.zip
  ├─ bio.markdown
  ├─ page.markdown
  ├─ requirements.markdown
  ├─ notes.txt
  ├─ figures
  │    ├─ figure1.png
  │    └─ figure2.png
  └─ listings
       ├─ listing1.txt
       └─ listing2.txt

bio.markdown

This should contain a one paragraph, short bio for you the author:

> ### Biography
> Jane Smith is a rolling stone, having worked with many
programming languages before finding her home in PHP.

page.markdown

This is the main file for your article. The beginning of the file should start with a level 1 heading with the title of your article, followed directly by a level 6 heading that is your byline (your name). After that the next paragraph should be offset as a block quote, and be a one paragraph (100 words max) abstract of your article:

# Using closures in PHP
###### by Jane Smith

> Closures are a fairly new feature built into PHP in
the most recent releases, and give amazing flexibility
in your coding. We will evaluate the benefits of
closures as well as how they can complicate your code
as well.

requirements.markdown

This is an optional file, but if it exists can have 3 separate sections, each with a level 3 heading and an unordered list of items. These sections are "Requirements," "Other Software," and "Related URLs":

### Requirements:
- PHP: 5.4+

### Other Software:
- Composer

### Related URLs:
- http://php.net

notes.txt

The notes file is optional, and simply should contain anything that you might want to call to our attention. Perhaps some specific formatting suggestions, or phrases from your article that would be good callouts:

Please make sure that Listing 2 shows up near all
3 paragraphs that refer to it.

For callouts consider using:
"...the beauty of these closures is their flexibility..."
"That's when I fell in love with PHP."

Submitting Your Finished Article

Once your article is complete, just zip it up into a single file for us and email it to your editor. If you aren't sure who you should contact, then editors@phparch.com always works.

Don't Panic!

If any of these guidelines seem too complex, or if you get mixed up on how the formatting should be handled, 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 and final layout, but we're much more concerned about getting informative text from you, the expert, than on having it formatted perfectly.

If you have any issues we'll be happy to help you out, and then share the final results back with you so that you can see how we'd like things submitted in future articles from you!