═══ 1. Introduction ═══

Why this document? 

The purpose of this document is to explain the formatting conventions used by 
the editors to allow the authors to better format their articles before 
submission; this will hopefully eliminate a significant amount of work 
currently done by the editors, allowing them to concentrate on other important 
production-related issues. 

Who should read this? 

The intended audience for this document is new authors who are already somewhat 
familiar with the .IPF SGML language.  For those who do not possess this 
requisitory knowledge, it is highly recommended that you learn it first before 
writing an article; see "The Help Manager and Online Documentation" in issue 5 
of EDM/2. 

Select this to go to the next section 


═══ 2. Deadlines ═══

The following deadlines should be noted and adhered to whenever possible. 

Item                Send by 
Notification        As soon as you decide to write an article 
First draft (optional) The 20th of the month 
Final draft         The 30th of the month (28th in February) 

All items should be sent to one of the editors, obviously. 

Notification is intended to let us know that you will be writing an article so 
that we do not receive any surprises on the 30th.  Please include the subject 
matter of the article. 

First draft  is optional and should contain a rough outline of your article and 
may be in "straight ASCII".  This is intended to be an elaboration of the 
notification rather than a prelude to the final draft. Remember that more work 
writing this item means less work for the next. 

Final draft should contain the final text to be submitted for any necessary 
editing and/or reformatting.  On rare occassions, we will resubmit the text 
back to you if significant changes have been made; this is to verify that the 
original meaning of the text has been preserved. 

Select this to go to the next section 


═══ 3. Headings ═══

Any heading tags should be of the third level only (:h3.). Any further 
subdivisions should be written as in the following example: 

:h3.Introduction
:p.:hp2.Why this document?:ehp2.
:p.The purpose of this document is to explain the formatting conventions used
by the editors to allow the authors to better format their articles before
submission; this will hopefully eliminate a significant amount of work
currently done by the editors, allowing them to concentrate on other important
production-related issues.

"Why this document?" is a subdivision of the "Introduction".  Note the new 
paragraph on both the title and the following text, as well as the level 2 
highlight of the title. 

Select this to go to the next section 


═══ 4. Highlighting and Quoting ═══

In the past there has been quite a bit of confusion regarding the use of 
highlights versus single or double quotes.  This section will hopefully clarify 
our position on the matter. 

A highlight level of 2 (:hp2.) should be used to emphasize words or phrases and 
also to highlight the first occurance of a word or phrase that the average 
reader will not be familiar with.  To elaborate, highlight any words or phrases 
that you would put in a glossary, were you required to write one.  (You are 
not.) 

Quoting, when used, should be restricted to double quotes only (the codepoint 
for the &csq. character is unsightly, in our opinion.) and should surround 
references to other textual works, colloquialisms, and any other phrasings that 
you feel do not consist of standard, proper English.  With the exception of the 
first, these items are subjectively defined; use your judgement when deciding 
whether or not something should be quoted. 

Select this to go to the next section 


═══ 5. Using Fonts ═══

Sample Code 

Since sample code and examples surrounded by the :xmp. tag use the 12 point 
Courier font by default, we have decided that this is too large for most 
displays.  After much experimentation with different fonts, we feel that the 
following yields a much more pleasing result while preserving the required 
column alignable attribute: 

:font facename=Courier size=14x14.
:xmp.
   Blah blah blah
:exmp.
:font facename=default.

This yields the following: 

   Blah blah blah

Quoted Text 

For text quoted from other sources, we ask that everyone use the following, to 
provide a consistent look to the magazine: 

:p.John Doe (:hp2.deer@buck.com:ehp2.) writes:
:font facename='Tms Rmn' size=18x16.
:p.Blah blah blah
:font facename=default.

This yields the following: 

John Doe (deer@buck.com) writes: 

Blah blah blah 

Miscellaneous 

Any other required font changes (pseudocode, etc.) should use the Helvetica 
font: 

:font facename=Helv size=12x12.
:p.Figure captions
:font facename=Helv size=20x20.
:p.Pseudocode

This yields the following: 

Figure captions 

Pseudocode 

When a larger size is needed, feel free to use one, but we ask that the 
Helvetica font be preserved.  As with quoted text, there is no reason for this 
other than for maintaining a consistent look. 

As a final note, do not forget to reset the font to the default once you are 
finished using it! 

Select this to go to the next section 


═══ 6. Content ═══

This section deals with the text itself.  While everyone from you (the authors) 
to us (the editors) is doing this on a voluntary basis, we would lose readers 
if we did not strive for a high level of quality.  Since this magazine was 
formed with the intent of disseminating information to the multitude of 
programmers unsatisfied with the lacking documentation provided by IBM, it 
would only serve to defeat the purpose of the magazine if we did not do so. 

Thus, we humby request that the following checklist be performed before 
submission: 

All information is accurate 

No one expects you to know everything about the topic you are writing. However, 
what information you do write about should be accurate and precise. Use correct 
terminology; use clear, unconfusing sentence structure; use examples in the 
text that you know work (whether you can "eyeball" them or have compiled them); 
document any exceptions that you know about when making generalizations.  The 
list could go on forever, but you should understand what is spoken of here. 

Spelling 

We realize that many people do not have spell-checkers; however, if you do, 
please use it.  Or, if you know your spelling leaves something to be desired, 
get someone else to proofread your text.  We rarely have access to a 
spell-checker ourselves, and it is very time-consuming to manually check every 
article, especially when other production issues are on our minds. 

Compile your article .IPF source 

Included with this document is a skeletal magazine source file.  Change the 
name of the embedded file to match the name of your text and compile it using 
the IPFC compiler included with the 2.x toolkits.  View the results, check for 
problems and consistency, correct any problems and repeat until you are 
satisfied with what you read. 

Liberally comment your source code samples 

As it has been said many times, a well illustrated example will often make up 
for any vaguries in the text.  "Well illustrated" not only means well 
thought-out, but also well commented.  Do not forget these, or else your 
readers will not be able to figure out what the sample does.  An example of 
this would be the installation command file that comes with EDM/2. 

An addition to this would be that your source code samples compile and run 
properly. 

Select this to go to the next section 


═══ 7. Final Details ═══

Before your task is complete, make sure you write a short blurb about yourself 
in a separate file; this will go in the "Contributors to this Issue" section. 
Please include your electronic mail address and specify whether it is on the 
Internet or Compuserve. 

Zip the source file, the biography file, and any auxilliary files (bitmaps or 
metafiles for figures, etc.), uuencode the zipped file and mail it to one of 
the authors by the final draft deadline. 

Finally, we thank you for your cooperation with these guidelines. Remember, you 
are doing a great service to the OS/2 community by writing for EDM/2.  Be proud 
of it! 

Sincerely,
The EDM/2 Editors