home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Professional
/
OS2PRO194.ISO
/
os2
/
info
/
prgramer
/
edmi
/
artsub
/
artsub.inf
(
.txt
)
next >
Wrap
OS/2 Help File
|
1993-12-08
|
10KB
|
223 lines
ΓòÉΓòÉΓòÉ 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