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

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
  3.  
  4. Why this document? 
  5.  
  6. The purpose of this document is to explain the formatting conventions used by 
  7. the editors to allow the authors to better format their articles before 
  8. submission; this will hopefully eliminate a significant amount of work 
  9. currently done by the editors, allowing them to concentrate on other important 
  10. production-related issues. 
  11.  
  12. Who should read this? 
  13.  
  14. The intended audience for this document is new authors who are already somewhat 
  15. familiar with the .IPF SGML language.  For those who do not possess this 
  16. requisitory knowledge, it is highly recommended that you learn it first before 
  17. writing an article; see "The Help Manager and Online Documentation" in issue 5 
  18. of EDM/2. 
  19.  
  20. Select this to go to the next section 
  21.  
  22.  
  23. ΓòÉΓòÉΓòÉ 2. Deadlines ΓòÉΓòÉΓòÉ
  24.  
  25. The following deadlines should be noted and adhered to whenever possible. 
  26.  
  27. Item                Send by 
  28. Notification        As soon as you decide to write an article 
  29. First draft (optional) The 20th of the month 
  30. Final draft         The 30th of the month (28th in February) 
  31.  
  32. All items should be sent to one of the editors, obviously. 
  33.  
  34. Notification is intended to let us know that you will be writing an article so 
  35. that we do not receive any surprises on the 30th.  Please include the subject 
  36. matter of the article. 
  37.  
  38. First draft  is optional and should contain a rough outline of your article and 
  39. may be in "straight ASCII".  This is intended to be an elaboration of the 
  40. notification rather than a prelude to the final draft. Remember that more work 
  41. writing this item means less work for the next. 
  42.  
  43. Final draft should contain the final text to be submitted for any necessary 
  44. editing and/or reformatting.  On rare occassions, we will resubmit the text 
  45. back to you if significant changes have been made; this is to verify that the 
  46. original meaning of the text has been preserved. 
  47.  
  48. Select this to go to the next section 
  49.  
  50.  
  51. ΓòÉΓòÉΓòÉ 3. Headings ΓòÉΓòÉΓòÉ
  52.  
  53. Any heading tags should be of the third level only (:h3.). Any further 
  54. subdivisions should be written as in the following example: 
  55.  
  56. :h3.Introduction
  57. :p.:hp2.Why this document?:ehp2.
  58. :p.The purpose of this document is to explain the formatting conventions used
  59. by the editors to allow the authors to better format their articles before
  60. submission; this will hopefully eliminate a significant amount of work
  61. currently done by the editors, allowing them to concentrate on other important
  62. production-related issues.
  63.  
  64. "Why this document?" is a subdivision of the "Introduction".  Note the new 
  65. paragraph on both the title and the following text, as well as the level 2 
  66. highlight of the title. 
  67.  
  68. Select this to go to the next section 
  69.  
  70.  
  71. ΓòÉΓòÉΓòÉ 4. Highlighting and Quoting ΓòÉΓòÉΓòÉ
  72.  
  73. In the past there has been quite a bit of confusion regarding the use of 
  74. highlights versus single or double quotes.  This section will hopefully clarify 
  75. our position on the matter. 
  76.  
  77. A highlight level of 2 (:hp2.) should be used to emphasize words or phrases and 
  78. also to highlight the first occurance of a word or phrase that the average 
  79. reader will not be familiar with.  To elaborate, highlight any words or phrases 
  80. that you would put in a glossary, were you required to write one.  (You are 
  81. not.) 
  82.  
  83. Quoting, when used, should be restricted to double quotes only (the codepoint 
  84. for the &csq. character is unsightly, in our opinion.) and should surround 
  85. references to other textual works, colloquialisms, and any other phrasings that 
  86. you feel do not consist of standard, proper English.  With the exception of the 
  87. first, these items are subjectively defined; use your judgement when deciding 
  88. whether or not something should be quoted. 
  89.  
  90. Select this to go to the next section 
  91.  
  92.  
  93. ΓòÉΓòÉΓòÉ 5. Using Fonts ΓòÉΓòÉΓòÉ
  94.  
  95. Sample Code 
  96.  
  97. Since sample code and examples surrounded by the :xmp. tag use the 12 point 
  98. Courier font by default, we have decided that this is too large for most 
  99. displays.  After much experimentation with different fonts, we feel that the 
  100. following yields a much more pleasing result while preserving the required 
  101. column alignable attribute: 
  102.  
  103. :font facename=Courier size=14x14.
  104. :xmp.
  105.    Blah blah blah
  106. :exmp.
  107. :font facename=default.
  108.  
  109. This yields the following: 
  110.  
  111.    Blah blah blah
  112.  
  113. Quoted Text 
  114.  
  115. For text quoted from other sources, we ask that everyone use the following, to 
  116. provide a consistent look to the magazine: 
  117.  
  118. :p.John Doe (:hp2.deer@buck.com:ehp2.) writes:
  119. :font facename='Tms Rmn' size=18x16.
  120. :p.Blah blah blah
  121. :font facename=default.
  122.  
  123. This yields the following: 
  124.  
  125. John Doe (deer@buck.com) writes: 
  126.  
  127. Blah blah blah 
  128.  
  129. Miscellaneous 
  130.  
  131. Any other required font changes (pseudocode, etc.) should use the Helvetica 
  132. font: 
  133.  
  134. :font facename=Helv size=12x12.
  135. :p.Figure captions
  136. :font facename=Helv size=20x20.
  137. :p.Pseudocode
  138.  
  139. This yields the following: 
  140.  
  141. Figure captions 
  142.  
  143. Pseudocode 
  144.  
  145. When a larger size is needed, feel free to use one, but we ask that the 
  146. Helvetica font be preserved.  As with quoted text, there is no reason for this 
  147. other than for maintaining a consistent look. 
  148.  
  149. As a final note, do not forget to reset the font to the default once you are 
  150. finished using it! 
  151.  
  152. Select this to go to the next section 
  153.  
  154.  
  155. ΓòÉΓòÉΓòÉ 6. Content ΓòÉΓòÉΓòÉ
  156.  
  157. This section deals with the text itself.  While everyone from you (the authors) 
  158. to us (the editors) is doing this on a voluntary basis, we would lose readers 
  159. if we did not strive for a high level of quality.  Since this magazine was 
  160. formed with the intent of disseminating information to the multitude of 
  161. programmers unsatisfied with the lacking documentation provided by IBM, it 
  162. would only serve to defeat the purpose of the magazine if we did not do so. 
  163.  
  164. Thus, we humby request that the following checklist be performed before 
  165. submission: 
  166.  
  167. All information is accurate 
  168.  
  169. No one expects you to know everything about the topic you are writing. However, 
  170. what information you do write about should be accurate and precise. Use correct 
  171. terminology; use clear, unconfusing sentence structure; use examples in the 
  172. text that you know work (whether you can "eyeball" them or have compiled them); 
  173. document any exceptions that you know about when making generalizations.  The 
  174. list could go on forever, but you should understand what is spoken of here. 
  175.  
  176. Spelling 
  177.  
  178. We realize that many people do not have spell-checkers; however, if you do, 
  179. please use it.  Or, if you know your spelling leaves something to be desired, 
  180. get someone else to proofread your text.  We rarely have access to a 
  181. spell-checker ourselves, and it is very time-consuming to manually check every 
  182. article, especially when other production issues are on our minds. 
  183.  
  184. Compile your article .IPF source 
  185.  
  186. Included with this document is a skeletal magazine source file.  Change the 
  187. name of the embedded file to match the name of your text and compile it using 
  188. the IPFC compiler included with the 2.x toolkits.  View the results, check for 
  189. problems and consistency, correct any problems and repeat until you are 
  190. satisfied with what you read. 
  191.  
  192. Liberally comment your source code samples 
  193.  
  194. As it has been said many times, a well illustrated example will often make up 
  195. for any vaguries in the text.  "Well illustrated" not only means well 
  196. thought-out, but also well commented.  Do not forget these, or else your 
  197. readers will not be able to figure out what the sample does.  An example of 
  198. this would be the installation command file that comes with EDM/2. 
  199.  
  200. An addition to this would be that your source code samples compile and run 
  201. properly. 
  202.  
  203. Select this to go to the next section 
  204.  
  205.  
  206. ΓòÉΓòÉΓòÉ 7. Final Details ΓòÉΓòÉΓòÉ
  207.  
  208. Before your task is complete, make sure you write a short blurb about yourself 
  209. in a separate file; this will go in the "Contributors to this Issue" section. 
  210. Please include your electronic mail address and specify whether it is on the 
  211. Internet or Compuserve. 
  212.  
  213. Zip the source file, the biography file, and any auxilliary files (bitmaps or 
  214. metafiles for figures, etc.), uuencode the zipped file and mail it to one of 
  215. the authors by the final draft deadline. 
  216.  
  217. Finally, we thank you for your cooperation with these guidelines. Remember, you 
  218. are doing a great service to the OS/2 community by writing for EDM/2.  Be proud 
  219. of it! 
  220.  
  221. Sincerely,
  222. The EDM/2 Editors
  223.