Writing your book

So you are interested a writing a book for php[architect]? Unsurprisingly the guidelines for our books are very similar to the magazine. Chances are that if you are writing a book for us, you might have already been a magazine author anyway and familiar with those standards.

Just in case you weren’t, or if you need a refresher, we recommend that you read our Magazine Editorial Guidelines, which cover all of the basics of our Markdown standards-based formatting. Then com back here to read up on the few differences that exist for the books.

Book Differences

Headings

Headings are still allowed at 5 separate levels; however while using them, note that the top level heading should only be used as Chapter titles. Plus they should be used hierarchically, as they are automatically used to build a Table of Contents for the book. Only the Chapter heads and 2nd level headings will be used in the Table of Contents.

# Top level heading - Used for Chapter Titles
## Second level heading - Shown in the Table of Contents
### Third level heading
#### You get the idea
##### That wraps it up.

URLs

Since our books are designed to be printed as well as used in potentially offline situations on an eReader, it’s important that URLs that are provided are able to be read & understood. For our books, there are two ways that we allow URLs to therefore be included. The first way is just like in the magazine, where the URL is important to the flow of the text, and it can be included directly, and surrounded by <> to denote it as a URL. The second option, best used if the URL is simply reference material that doesn’t flow with the text, is to use a link which is converted automatically into a footnote for print and PDF output. For EPUB and Mobi files, it’ll remain a link.

The website containing all things PHP is <http://php.net/>

If you need to explore all of parameters for this library you
can read the [php documentation](http://php.net/curl) on it.

Footnotes

Speaking of which, we allow footnotes to be included in our books. Whenever you need one just use the ^[] notation, and they will be automatically numbered and inserted.

For this book's examples we will be following 
the W3C^[World Wide Web Consortium] standards for HTML5

If you need a larger footnote, you can separate it with a unique identifier. Use the [^identifier] notation to indicate the footnote, and then on a new line use [^identifier]:

For this book's examples we will be following 
the W3C[^html5] standards for HTML5

[^html5]: For a complete view of the W3C standards, visit <https://www.w3.org/TR/html5/>.

Callouts

If you want to bring attention to any specific section of your book as a callout, you can do so via formatting it as a blockquote by prefacing it with >

> It's important to make sure that you've closed your 
method braces or your PHP will not compile.

Code

Really all the rules for code are the same for books as they are for the magazines. Please note that inline Code Samples and Code Listings must not have any lines that are more than 60 characters wide. The one difference is that we are far more flexible in the ‘6 line’ difference between a Code Sample versus a Code Listing. You as the author should choose to decide exactly how you want these to be rendered. If you are working through an iterative process of describing the development of code, then inline Code Samples are probably far better. However if you have a large block of code that you just want to reference, then including it as a Code Listing (which will format it differently, with line numbers, and a listing number that you can refer back to), may be a better choice for you. For the second listing file in chapter 3, you would refer to it as Listing 3.2, and would place the listing in a separate file (in the Listings folder) called listing3.2.txt. You would use the listing in the text like this:

The code does lots of things. As you can see in Listing 7.1, lines 15 - 20 are the important ones.

[Listing 7.1](Listings/listing7.1.txt)

Figures

Figures should be named for the chapter name and then the figure number within that chapter. For example, the first figure in Chapter 7 would be Figure 7.1, and the filename for that figure would be figure7.1.png. You would reference the figure like this:

The widget works very well. You can see in the output in Figure 7.1 that it is working well.

![Figure 7.1: The Output from the Widget](Figures/figure7.1.png)

If the figure is in an appendix instead of a chapter, you would name it by the appendix letter. For example, in Appendix B, the third figure would be named: figureB.3.png.

Assembling your Book

The file structure for books is actually a bit simpler than for magazines. Really you should just include one .markdown file for each chapter of your book. Also usually books will have an acknowledgements section and perhaps an optional foreward written by someone else. The naming of the files isn’t as important, as long as they all sort correctly in order. Prefacing the files with a two digit number can help with this. So for example a book you submit to us might look something like:

book.zip
  ├─ 00.0.acknowledgements.markdown 
  ├─ 00.1.forward.markdown 
  ├─ 01.chapter1.markdown 
  ├─ 02.chapter2.markdown 
  ├─ 03.chapter3.markdown 
  ├─ 04.chapter4.markdown 
  ├─ figures
  │    ├─ figure3.1.png
  │    └─ figure3.2.png
  └─ listings
       ├─ listing1.txt
       └─ listing2.txt

Submitting Your Book

Just like with the magazine articles, when your book is complete, just zip it up into a single file for us and email it to your editor or to . However your editor will be in contact with you during the whole process, and may provide different instructions or version control access to submit your book that way. But most importantly just keep remembering:

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 in an iterative process to help the book along.