Introduction
Writing a Proposal
Types of Content

Feature Articles
Reviews & Profiles
Interview
Soapbox
Postmortem
Cover Art

Writing Guidelines

Word Processor Format
Graphics and Illustrations
Formatting Code
Commenting Code
URLs and References
Spelling & Grammar
Writing REALbasic and Other Names
Abreviations and Acronyms
Versions of REALbasic

Writing Your Article

Structure
Style
Audience
Article Length

Sending Us Your Article
Payment
Copyright Information
Communicating With Us
Copyright Agreement

Purpose of Agreement
Agreement

Introduction

This guide will explain to you the procedures and requirements for writing for REALbasic Developer. It is advised you read this document thoroughly before beginning your writing project. Following the guidelines within will not only increase the chances of us publishing your work and the amount we pay, but it will save us time in editing and production.

Writing a Proposal

If we're interested, we'll let you know. Simply expressing an interest doesn't guarantee that we'll use your article, however. But you'll have a greater chance of us publishing it than if you simply submit an article unsolicited. You can also look at our Editorial Calendar to see what themes we are focusing on in future issues.

Types of Content

Feature Articles

Features don't necessarily have to conform to the theme; of the four to six features we publish each issue, two or three are centered around the cover theme.

The majority of our articles are of the "How To" nature. They should be focused and demonstrate a particular technique or concept and include plenty of sample code. Real world examples are most valuable. For instance, an article explaining how to use Sockets in REALbasic is not nearly as interesting as an article showing us how to write our own webserver.

General programming techniques and algorithm design are also hot topics. For instance, an article on how to add "undo" support to your application, or a feature comparing various search methods.

Articles about the business side of software writing are also needed. For example, how to distribute shareware, obtain publicity, copyright issues, collecting payments, serial number schemes, etc.

Features are 1,500-6,000 words and should include extensive screenshots and graphics and some source code. Extended amounts of source code and other resources may be placed on the REALbasic Developer website for readers to download.

Reviews & Profiles

Reviews are brief articles summarizing the good and bad points of a tool of interest to REALbasic programmers. Tools are anything that helps the RB developer. They can be REALbasic plug-ins, RB classes or modules, programming books (they don't have to be RB-specific), or even a graphics program, such as an icon editor. They can be commercial, shareware, or freeware. Reviews of tools are rated on a 1-5 scale calculated via the following formula:

• 20% - Appearance/Interface (Does it look professional? Does it follow Apple's UI guidelines?)
• 20% - Usability (Does it do what it promises? Is it useful?)
• 20% - Stability (Does it crash?)
• 20% - Value (Is the pricing attractive or prohibitive?)
• 20% - Innovation (It is a unique or innovative product?)

Profiles are unrated reviews of software developed with REALbasic. These are designed to promote and demonstrate the high quality and variety of software being developed with REALbasic. We are especially interested in unique and innovative solutions. These reviews are not rated, but the review may be critical if the product is not of high quality.

Reviews and Profiles have a maximum length of 500 words plus one graphic (screenshot, product photo, or company logo); must include the manufacturer's contact information (website, email, etc.); the price of the product; and any unusual system requirements (for instance, doesn't work under Mac OS X).

Interview

Soapbox

Postmortem

For instance, if you wrote a popular shareware program, you could write about your troubles and trials and successes in creating the program. This wouldn't necessarily mean you have to release the source code of your project, but some code snippets would be helpful in explaining what you learned during the process.

Your project does not necessarily have to have been a success. You could explain, for example, how you tried to rewrite a C++ program in REALbasic but failed, because of limitations within REALbasic. (Obviously, the tone of the article should be positive, even if the experience was not.) The point is to emphasize what you learned through the process, and what you'd do differently if you were to do a similar project again.

Postmortems are 1,500-3,000 words and should include extensive screenshots and graphics and perhaps some source code. All postmortems are assigned by a REALbasic Developer editor, so you should first write a proposal before submitting an article. Postmortems should also include a "Developer's Toolbox" table like this (from RBD 1.3):

Cover Art

We don't use much artwork inside the publication (other than photos, screenshots, and diagrams), but if you have an illustration you'd like us to use (perhaps as part of an article you've written), we may consider it.

Our artwork needs are fairly specific, so it's best to contact us regarding your idea before you spend a lot of time creating it. We may have revisions to your concept. You can look at our Editorial Calendar to see the themes selected for future issues. Covers generally reflect these themes.

Writing Guidelines

Word Processor Format

XML tagging is similar to HTML tagging, but far more powerful. By using the tags we specify, we can easily format your article for publication as well as repurpose it for the web and other uses. Note that different types of articles will require different sets of tags.

For example, a typical article might be tagged like this:

<Feature>
<MainHeadline>Star Trek's Future is Here</MainHeadline>
<SecondaryHeadline>Creating a Matter Transporter in REALbasic in Six Easy Steps</SecondaryHeadline>
<Byline>by Marc Zeedar</Byline>
<GlanceBox><GlanceHead>At a Glance</GlanceHead>
<GlanceText><RBDNumber>RBD#0000</RBDNumber>
Target Reader:
<GlanceSubhead>Beginner</GlanceSubhead>
Source Code:
<GlanceSubhead>Yes</GlanceSubhead>
RB Version Required:
<GlanceSubhead>2006+</GlanceSubhead>
Platform(s) Supported:
<GlanceSubhead>Mac OS X</GlanceSubhead>
Platform(s) Untested:
<GlanceSubhead>Windows XP, Linux, Mac Classic</GlanceSubhead>
About the Author:
<GlanceBio>Marc is a world famous writer and programmer. If you haven't heard of him, 
obviously you're an idiot.</GlanceBio></GlanceText></GlanceBox>
<Article>
<Subhead1>Getting Started<Subhead1>
To build you own matter transporter in REALbasic, you will need a copy of
REALbasic version 27. I got my copy via time traveler I met during a visit to New
Orleans, but I'm under an NDA so I can't share my copy.</Article></Feature>

To make it easier for you tag your articles, we've written a detailed explanation on how to do it: you may download the PDF manual here.

We've also created a program, RBD XML Tagger, which will let you quickly tag your articles after you've written them. You may download the program here. The instructions for using RBD XML Tagger are within the RBD XML Guide.

Graphics and Illustrations

Bitmap graphics like photos or screenshots should be saved in Photoshop (PSD), PICT, PNG, EPS, or TIFF formats. Stay away from GIF (which is only 256 colors) or JPEG (which is lossy compression). Photos should have a resolution of at least 300 dpi at 100% size. Never resize screen captures -- let us do that if required. Also, capture only the information necessary to convey your point. If possible, use a screen capture utility that lets you grab just the active object you need (window, menu, etc.). Rarely is a full screen capture required, but if you need it, it's best to set your screen resolution to a smaller size so there's less wasted space, and set your desktop to a light, plain, less destracting pattern.

Capture screens in full 24-bit color. However, please remember that REALbasic Developer is printed black ink on the inside pages, so your graphic will be converted to grayscale for printing. It is advisable you preview your screenshots in grayscale to be sure that all text is readable. We prefer to receive screen captures in color as we may wish to repurpose them for other mediums, such as the web.

If you don't have screen capture software adequate for the task you need (such as a capture of a pulldown menu), please describe the capture you'd like in words and we'll attempt it.

Do not include figure numbers or labels within your illustration or screenshot. Instead, write a separate caption and label it "Figure X" where X is the number of the figure. Figures should be numbered consecutively from the beginning of your article. Don't assume that a figure will appear adjacent to the text that refers to it: always refer to a graphic by number (i.e. write "See Figure 4." not "See graphic below." or "See graphic at left.").

If you have ideas for graphics you'd like to include but aren't an artist, please do a rough sketch and include a written description and we'll see about having the drawing created. Note: try not to request too many of these, as we have limited artistic resources.

Formatting Code

• Use spaces between all symbols and punctuation (except for parenthesis), so i+1 becomes i + 1.
• Put comments on their own line (inline comments add to line length).
• Break up your code with blank lines to group related sections together and make it more readable.
• Use consistent capitalization of variable names and reserved words. Our preferred approach is to use all lowercase for reserved words and to capitalize only the first letter of words inside variable names. So theList is correct and TheList is incorrect.
• Use a consistent scheme for naming variables. It'd be too difficult for us to force you to name variables our way, but as long as you're consistent, it shouldn't be confusing for readers. Our preferred approach is the following: use a lowercase c or k for beginning constants, a lowercase g for globals, and appending Class to the end of Classes. So kMaxScore would be valid for a constant, gPlayerScore for a global, and gridCellClass would be good for a class type.
• You may use either tabs or spaces to indent code, but be consistent! (Don't do some code with spaces and some with tabs.) This is very important to preserving the structure of your code. Copying or exporting code from the RB IDE will usually work fine.
• Try to keep lines at less than 60 characters, as longer lines will wrap in listings, making them more difficult to follow. (One tip when you are concatenating a long string is to create a short-named variable to use instead of writing out a long bit of quoted text several times.)
• All comments should use the dual-slash form (//) not the apostrophe (').

Here's an example of a well formatted code snippet:

Function returnColumnWidth(colNum as integer) As integer
    dim i, n as integer
    
    // This function adds up the widths of columns up
    // to colNum and returns it. It is used to calculate
    // the starting position of column colNum.
    
    n = 0
    for i = 0 to colNum
        n = n + val(nthField(theList.columnWidths, ",", i + 1))
    next // i
    
    return n
End Function

If you aren't including the entire routine in your snippet, begin or finish it with three dots to signal that more code precedes or follows. For example:

    ...
    // Be certain column width is at least the minimum size
    
    n = returnColumnMinimum(theColumn)
    if cWidths(theColumn) < n then
        cWidths(theColumn) = n
    end if
    ...

Note that RBD publishes source code in two methods: within the body of the text (embedded code), and in a separate code listing. Code within the text must be pertinent to the subject at hand and generally consists of shorter snippets. It is ideal for a tutorial as the structure is text, code, text, code, etc. However, embedded code must fit within the narrower three-column format for articles, and thus the maxmimum non-wrap length of any line is about 45 characters. Embedded code listings are not labeled with a Code Listing number, but if you publish a full subroutine (not a snippet), you should precede it with the full path of the subroutine like this: Code for Window1.PublishButton.Action:.

Here's a sample of embedded code as it appears in the magazine (the body text is just dummy copy used for a mockup):

Code listings are longer portions of code labeled by number and referenced in your text (i.e. "See Code Listing #1"). They may be included as separate text files when you submit your article. Please number them beginning with #1 as they appear in your article. The maxmimum non-wrap length of any line is about 80 characters.

Here's a sample of a separate (non-embedded) Code Listing as it appears in the magazine (the line on the right represents the maximum non-wrapping width):

Commenting Code

    // First we make sure the folderitem isn't bad
    if theFile <> nil then
    ...

Use the text of your article for explaining your algorithm and general methodology. Comments shouldn't duplicate your article -- they are there to remind the reader what's happening in that section. If your article has suggestions for improving the code or alternate algorithms, don't include comments to that effect in your code -- keep the code as complete and professional as possible.

URLs and References

For other URLs, do not include HTML markup ("href") to hotlink some text. Instead, simply include the full URL enclosed within <URL>http://myurl.net</URL> tags and we will take care of making it "hot." (Be sure to include the http:// or ftp:// text.)

If you are referring to material on your own website, please note that if this is something the user will need to understand or use your article, then we require that it be made available via the RBD website. You're free to mirror it on your own site, of course (you can include a URL to your site in the Reference section at the end of the article), and you keep the copyright on any copyrighted material, but RBD should have distribution rights. As a general policy we want our readers to know that if something is required for an article it is freely available on the RBD website.

If the item isn't required for the article but merely referenced, you may simply include the URL within your article. However, if the item is a product that you sell, you need to mention that within your text. For example, "...a similar product is this author's own rkRocketClass, which sells for $10 with a free 30-day trial." We don't want to give readers the impression that authors are simply pumping their own products for sale. (It's fine to refer to your own products, just make sure it's clear if it's a free product or if it's a sale product.)

Here's a sample bibliography entry:

Jenson, William and Mary Foil (editors). "Compression Algorithms Revisted," HighTech Weekly, No. 86 (July 4, 1999), pp. 73-94. DVU Press.

Spelling & Grammar

Writing REALbasic and Other Names

Abreviations and Acronyms

This is an article about writing your own File Transfer Protocol (FTP) server in REALbasic (RB). This was originally printed on the REALbasic University (RBU) website. The original RBU article did not cover Mac OS X, but we've updated our RB code to support Carbon compiling.

Creating your own FTP server isn't difficult, but you must read the many RFC (Request For Comment) docs that explain the FTP standard....

Versions of REALbasic

* If your code is such that it greatly depends on features of a pre-release version of REALbasic, we might make an exception, if we feel the features are at the core of your article. But you must make it very clear that your program requires a pre-release version, specify which version it requires, and explain why you had to use that version. Because of the lead time required for publication, it may be that the pre-release version used is officially released by the time that issue of the magazine is published, but there's no guarantee that REAL Software hasn't changed something from the pre-release version that renders your project incompatible.

Writing Your Article

Structure

This article will explain how to launch the REALbasic application.

First, you find your REALbasic folder. Then you double-click the REALbasic icon. You're done!

Now you know how to launch REALbasic on your own.

Obviously you want to expand on this a bit (and pick a more challenging subject ;-), but this is the basic idea behind any article. Your introduction could include a story or some background on how you came up with the idea or need for whatever it is you are going to explain, followed by the actual implementation of a solution. Your conclusion wraps things up and perhaps indicates future directions the reader could take to make the program better, or do further research on the subject.

Style

Audience

Article Length

Certain types of articles have specific length requirements: columns, for instance, need to be consistently the same length. Reviews must fit into a pre-defined amount of space and must all be about the same length (500 words).

Also, keep in mind that the length of an article includes source code published as part of your article. For large projects, we can't print the entire source, but we definitely want excerpts. Depending on your audience, you may omit "obvious" portions of the code and allow the reader to download the complete project from the RBD website. For some features, half the article can be source code, so keep that in mind if you're intimidated at having to write a 3,000 word article! (Just be sure you explain any source code you use in the text.)

Finally, for most articles we pay by the word: but that's words actually printed in the magazine. If you submit a 5,000 word article and we trim it to 3,127, you get paid for 3,127 words.

Sending Us Your Article

Be sure to include all necessary resources for your project, and include plenty of folders to organize everything appropriately. For example, include an "article illustrations" folder for all screen captures and graphics, an "ABC project folder" for your source code, etc. If we get everything all lumped together in one folder, we may have to return it to you as we may not be able to make sense of all the parts!

At the end of this document is a copyright release and an author information form. Be sure you complete these and fax or email them with your submission. If you are a U.S. citizen, your social security number is vital, as otherwise we cannot pay you.

Payment

Payment amounts vary according to article type, length, significance, quality, and the amount of editing/rewriting required. Below are our current rates. As our subscriber base increases, these amounts will be adjusted accordingly.

• Soapbox: n/a
• Review: $25
• Regular Column: $50
• Feature Article: $0.03 per word (typically $60-$150)
• Postmortem: $0.03 per word (typically $50-$100)
• Cover Art: $50-$75

If you'd prefer to receive credit towards an REALbasic Developer subscription, we can do that instead of sending you a check. We can also apply credit towards an advertisement in the magazine or on the REALbasic Developer website. If you plan to write for REALbasic Developer frequently, we can also save your payments on account until the total reaches a more substantial amount. (This might be appropriate for writers from foreign countries where the fees to translate currencies can be excessive.)

Copyright Information

In submitting an article, you are granting REALbasic Developer magazine the worldwide right to publish and re-publish your article in any medium, in any language, in whole or in part. In the event that copyright is retained by the author (or author's employer), the publishing rights are granted to REALbasic Developer. This allows for copyrighted code to be submitted in an article without its use being restricted for REALbasic Developer or the author.

For authors this means that your work, when published, becomes property of REALbasic Developer. This is what we pay you for when your article is published.

All articles must be original works and may not appear in any other publication without prior consent of REALbasic Developer for a period of one year from publication by REALbasic Developer. This restriction includes distribution in any form, such as bulletin boards or on-line services. If you want to escape the restriction, you can do so by making substantive changes first; that way, what you now publish is not the same article we published. If you wish to have the article itself reprinted elsewhere, you must first receive written (or email) permission from REALbasic Developer. We grant you the right to use the article text, pictures or related source code either personally or commercially without restriction, though; and during the restriction period, we will in fact usually grant authors the right to republish their work, but you have to get our permisssion first. If we grant permission we will request that the author state that the article was originally published in REALbasic Developer. For example, "This article was originally published in REALbasic Developer 1:2 (Oct./Nov. 2002)." For precise wording on this copyright information, see the Copyright Agreement at the end of this document. Again, all information in that agreement supersedes the text here. After the limitation period of one year is up, you can of course reprint the article without limitation. Note that if all you want to do is distribute copies, we'll be happy to provide a reprint master of an article.

REALbasic Developer also grants to those who receive the magazine or other materials, in either printed or electronic form, the right to use parts of the source code in their own project, be it personal or commercial, provided they duly credit the the appropriate issue of REALbasic Developer. For example:

XYZ Program by R. B. Programmer.
Portions Copyrighted by REALbasic Developer Magazine as seen in the Sept./Oct. 2002 issue.

Communicating With Us

REALbasic Developer Magazine
P.O. Box 872
Lafayette, OR 97127

General email Addresses:

Editorial:
Article Submissions:
Press Releases:
Tips:
Letters to the Editor:
"Ask the Expert" Questions:
Circulation, Customer Service, Accounting:
Ad Sales:

If you prefer, a high quality PDF version of this contract is available here (89K).

Copyright Agreement

Purpose of Agreement

Agreement

Author desires REALbasic Developer to publish the Article in a future edition of REALbasic Developer, and hereby submits the Article for pre-publication review via electronic mail.

REALbasic Developer will review the Article at its convenience, and shall notify Author of its acceptance or rejection. Such notification shall be in writing or by telephone or fax or electronic mail, but in no event shall such notification occur later than 90 days after submission. If REALbasic Developer fails to notify Author within the 90 day period, Author may seek publication elsewhere and may withdraw the Article from consideration upon 30 days notice in writing, email, or by fax to REALbasic Developer.

Author shall make any and all revisions and modifications to the Article requested by REALbasic Developer. Further, REALbasic Developer reserves the right to make whatever editorial changes it sees fit, in its sole and absolute discretion. Author shall also submit machine-readable copies of any relevant computer code or software, and copies of any and all resource material necessary for REALbasic Developer to verify the technical or factual aspects of the Article at the time of article submission.

Once the Article is accepted for publication, REALbasic Developer shall publish the Article in REALbasic Developer magazine within 365 days of such acceptance. If REALbasic Developer fails to publish within this period, Author may withdraw the Article upon 30 days written notice to REALbasic Developer. Upon such withdrawal, REALbasic Developer shall have no further obligation to Author of any kind, and shall have no rights of any kind in the Article.

From the time of acceptance for publication, unless timely withdrawn by Author, Author hereby irrevocably assigns and conveys to REALbasic Developer all rights to publication, display, transmission, and any and all other exploitation of the Article in all media, in any language, worldwide. These rights shall be exclusive to REALbasic Developer from acceptance through one year from the date of publication. The date of publication is the first day of the month on the cover of the magazine the Article first appears in. These rights shall include rights to publish reprints or to include the Article in any future collections of REALbasic Developer material including, but not limited to, an annual REALbasic Developer CD-ROM. These rights shall also include the right to authorize republication of the Article in other media and periodicals, and the right to use the Article for all commercial and merchandising purposes that pertain to REALbasic Developer magazine or to DesignWrite. DesignWrite shall have no rights of any kind to any computer code or software contained in the Article, whether used as example, or otherwise, but may make such use of such code, concepts or software as any reader of the magazine would be expected to do. Author is entitled to use the article text, pictures or related source code either personally or commercially without restriction. Furthermore, if indicated at the time of article submission, Author may retain the copyright of said computer code.

After one year from the date of publication, all of the rights mentioned in paragraph 5 above shall continue but shall be non-exclusive to the extent that Author may utilize and display the Article for any non-profit purpose, and for any other purpose in which the primary source of revenue is not sales of copies of the Article. Author may not utilize, display, reprint or republish the article for profit without prior written permission. For example, Author may distribute copies of the Article without charge to attendees of a symposium or conference in which Author is paid a fee to speak, but Author may not sell copies of the Article, whether Author speaks or not. Whenever the article is reprinted or republished by the author, such reprint or republication shall state that the article is reprinted from REALbasic Developer Magazine specifying REALbasic Developer's date of publication. Author may substantially rework an article for publication elsewhere without any restrictions by DesignWrite.

REALbasic Developer shall pay author its usual fee for articles of the same, quality, length and type. Such payment shall be due 30 days after the first day of the month of publication. REALbasic Developer's usual fees are described in the version of its "Writer's Kit" that is current at the time of submission. Judgment as to the quality, and type of article shall be in the sole and absolute discretion of REALbasic Developer. Author warrants that the Article is entirely Author's original work, (except quoted items which must be correctly attributed) and has not been previously published. Author also warrants that the Article and its publication violate no laws and no rights of any individual, group, association, corporation, governmental agency, or other entity.

Both Author and REALbasic Developer acknowledge that the Article was written at the Author's own direction and not at REALbasic Developer's direction and that the Author's only relationship to REALbasic Developer is that of an independent contractor.

This agreement shall be governed by the laws of the State of California. Any provision found to invalid or unenforceable by operation of law or public policy or for any other reason by any court shall be severed and the remaining provisions shall be treated and construed so as to most nearly achieve the purposes set forth above.

Any and all notices required under this agreement shall be deemed made three working days after placement in regular US mail, or one working day after fax or email transmission. Addresses for all such notices for Author appear below and for REALbasic Developer below.

By causing a facsimile or electronic mail copy of the Article to be received by DesignWrite (submission), author accepts and agrees to the terms and conditions of this contract. The act of submission shall be all that is required to evidence author's acceptance of all of the terms and conditions of this agreement. Lack of signature execution by author shall have no legal significance whatever. Any changes or alterations made by Author in copy derived from this Agreement shall be null and void and the submitted Agreement shall be interpreted and enforced as if such changes had not been made.

DesignWrite accepts and agrees to the terms and conditions of this contract at any time it accepts delivery of a submitted Article. The lack of a signature execution by DesignWrite shall have no legal significance whatever, providing that no modifications have been made by Author to this Agreement.

Understood, agreed, and accepted this _____________ day of ____________________, 20_____:

Author: _______________________________________  _______________________________________
                 (Signature)                                     (Print name)

Street Address: ________________________________________________________________________

City: __________________________________________________________________________________

State/Zip: ______________________ Country: _____________________________________________

Social Security #: _____________________________________________________________________

Phone: ___________________________________________ Fax: ________________________________

Email: _________________________________________________________________________________

REALbasic Developer Magazine
PO Box 872
Lafayette, OR 97127
email: