home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / games / spl / src / spl.ipf < prev    next >
Text File  |  1993-08-10  |  11KB  |  317 lines
  1. :userdoc.
  2. :title.spl documentation
  3. :h1.Introduction and Copyright
  4. :p.
  5. :lines align=center.
  6. :font facename='Tms Rmn' size=36x24.
  7. :hp4.
  8. Spellbook Control Program
  9. :font facename=default size=0x0.
  10. :ehp4.
  11.  
  12. :hp1.spl.exe:ehp1.
  13.  
  14. :hp2.Version 1.0:ehp2.
  15.  
  16. :hp2.8/10/93:ehp2.
  17.  
  18. :hp2.Copyright (C) 1993 John-Marc Chandonia:ehp2.
  19.  
  20. :elines.
  21. :p.
  22. For suggested enhancements and bug reports, please mail
  23. :font facename=Courier size=13x8.
  24. chandoni@husc8.harvard.edu
  25. :font facename=default size=0x0.
  26. or write:
  27.  
  28. :lines align=center.
  29. John-Marc Chandonia
  30. 7 Divinity Avenue, #121
  31. Cambridge, Ma. 02138
  32. :elines.
  33. :p.
  34. This is spl, a program for handling spells and spellbooks
  35. from various fantasy role-playing (FRP) games.  It can handle
  36. both mage and priest spells for TSR's AD&.D (a trademark of TSR, Inc)
  37. game, and can easily be expanded to handle other systems as well.
  38. In addition to possibly being useful to FRP players and
  39. GM's, the source may be useful to OS/2 2.x programmers learning
  40. about containers, MLE's, and PM programming in general.
  41. :p.
  42. This program is free software; you can redistribute it and/or modify
  43. it under the terms of the GNU General Public License as published by
  44. the Free Software Foundation; either version 2 of the License, or
  45. (at your option) any later version.
  46. :p.
  47. This program is distributed in the hope that it will be useful,
  48. but WITHOUT ANY WARRANTY; without even the implied warranty of
  49. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  50. GNU General Public License for more details.
  51. :p.
  52. You should have received a copy of the GNU General Public License
  53. along with this program; if not, write to the Free Software
  54. Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  55. :p.
  56. :h1.Release Notes
  57. :p.
  58. This is the first public release of the program, and therefore
  59. probably has many more bugs than I know about!  Known bugs are
  60. listed in the file 
  61. :font facename=Courier size=13x8.
  62. bugs.txt.
  63. :font facename=default size=0x0.
  64. If you find any more, please either fix them yourself and send
  65. me the patch (sure!) or report the bug to the address given
  66. above.
  67. :p.
  68. I will put all future versions of this program on the OS/2
  69. anonymous ftp site, currently
  70. :font facename=Courier size=13x8.
  71. ftp-os2.cdrom.com.
  72. :font facename=default size=0x0.
  73. If you distribute any enhanced versions of this program, please
  74. do the same.  Also, please comment any changes in the source
  75. code, and describe them in the file 
  76. :font facename=Courier size=13x8.
  77. changes.txt.
  78. :font facename=default size=0x0.
  79.  
  80. :h1.Using the program
  81. This section describes how to install and use the program.
  82.  
  83. :h2.Installation
  84. Unzip the zip file in some directory.  If you want, create a program
  85. object for the file
  86. :font facename=Courier size=13x8.
  87. spl.exe,
  88. :font facename=default size=0x0.
  89. If you don't plan to look at the source code, you can delete the
  90. src directory... this is not needed to run the program.
  91. :p.
  92. Check out the file
  93. :font facename=Courier size=13x8.
  94. splbook.all,
  95. :font facename=default size=0x0.
  96. which contains pointers to all spellbooks which will comprise the
  97. master spell list.  
  98. :link reftype=hd res=0.Click here:elink. for more information.
  99. :p.
  100. Also, look at the file
  101. :font facename=Courier size=13x8.
  102. splicon.res
  103. :font facename=default size=0x0.
  104. which contains a mapping of sphell spheres and schools to icons.
  105. :link reftype=hd res=1.Click here:elink. for more information.
  106. :p.
  107. You already know how to view the docs; to run the program, just
  108. run 
  109. :font facename=Courier size=13x8.
  110. spl.exe.
  111. :font facename=default size=0x0.
  112.  
  113. :h2 res=0.Master spell list
  114. :p.
  115. The file
  116. :font facename=Courier size=13x8.
  117. splbook.all
  118. :font facename=default size=0x0.
  119. contains a list of spellbooks which make up the master spell list.
  120. These spellbooks should contain full spell listings.   This is
  121. important because other spellbooks are by default saved only
  122. as lists of titles, which are then looked up in the master spell
  123. list as the spells are loaded in.
  124. :p.
  125. The format of this file is just a list of other files.  To place a
  126. comment in this list, start the line with a semicolon.
  127. :p.
  128.  
  129. :h2 res=1.Icon mapping
  130. :p.
  131. The file
  132. :font facename=Courier size=13x8.
  133. splicon.def
  134. :font facename=default size=0x0.
  135. contains a mapping of spell schools and spheres to icons.
  136. :p.
  137. Spells in a book are shown with an icon which corresponds to their sphere
  138. (if given) or school (if no sphere is available).  This file contains
  139. a list of text strings to look for in the schools and spheres, and
  140. a list of icons they correspond to.  If a spell matches two or more
  141. text strings, the first one found is used.
  142. :p.
  143. The format of the file is a text string (containing no spaces), then
  144. a space, then the path name of an icon file to use.  Comments are
  145. allowed, as long as they begin with a semicolon.
  146. :p.
  147.  
  148. :h2.File menu
  149. :p.
  150. From this menu, you can load and save spellbooks, or create new
  151. spellbooks.  Loading a spellbook will create a new window.
  152. :p.
  153. Spellbooks can be loaded and saved in two ways.  The menu options
  154. "Load Spellbook" and "Save Spellbook" only save lists of spells, which
  155. are looked up in the master list.  The options referring to the
  156. "full" spellbook save the entire text of spells.
  157. :p.
  158.  
  159. :h2.Spell menu
  160. :p.
  161. These options are only available if the book is writeable
  162. (i.e. not the master spell list).  These options allow you to
  163. add new spells (use
  164. :link reftype=hd res=2.Drag and Drop:elink.
  165. instead) or delete spells from a book.
  166.  
  167. :h2.Book menu
  168. These are more detailed descriptions of options under the book menu.
  169.  
  170. :h3.Find subset
  171. :p.
  172. This brings up a dialog which allows you to search through the
  173. spells in the book (window) and bring up a new book (window)
  174. which contains the results of the search.
  175. :p.
  176. Spells can be sorted on several fields, with the results
  177. OR'ed or AND'ed together depending on the buttons in the
  178. lower left corner of the dialog.  Case sensitivity is also
  179. optional.  Most of the fields just want you to enter text.
  180. :p.
  181. The "level" field allows you to enter a number for the spell
  182. level, such as "5" to select all 5th level spells.  It also
  183. allows you to enter things like ">5" or "<5" to select all
  184. spells higher or lower than a certain level.
  185. :p.
  186. The "description" field allows you to enter several lines of
  187. text instead of only one.  All lines entered are searched
  188. for in the spell descriptions, with the results OR'ed or 
  189. AND'ed together according to the button pushed on the right.
  190. :p.
  191. Searches go faster with case sensitivity enabled.  Also,
  192. searches go faster if the program doesn't have to search through
  193. entire spell descriptions... limit using the other fields if possible.
  194. :p.
  195. :h3.Sort spellbook
  196. :p.
  197. This sorts the spellbook, priest spells before mage spells, then
  198. in alphabetical order.
  199.  
  200. :h3.Rename spellbook
  201. :p.
  202. This renames the spellbook... it does not change the actual name of
  203. the file the spellbook is saved in, only the name which appears
  204. at the top of the window.
  205.  
  206. :h2 res=2.Drag and Drop
  207. :p.
  208. To copy spells between windows (spellbooks), drag them with the right mouse
  209. button.  You can select several spells with the left button.  Dragging
  210. can also be used to reposition spells within a window.
  211.  
  212. :h2.Looking at a spell
  213. :p.
  214. To look at one spell in detail, double click on it.  This brings
  215. up a window which is pretty self-explanatory.  Use ALT-N or ALT-P
  216. as a shortcut to go to the next or previous spell in the book.
  217. :p.
  218. You can copy text from spells onto the clipboard using the
  219. usual methods.  You can even edit and change spells, although
  220. this doesn't work very well and will probably require you to
  221. go in and fix the saved text file with an editor.
  222. :p.
  223. Any file you change and save is saved in the file
  224. :font facename=Courier size=13x8.
  225. splbook.chg.
  226. :font facename=default size=0x0.
  227.  
  228. :h1.Source information
  229. This is information on the source code.
  230. :h2.Miscellaneous
  231. :p.
  232. The source is written in C++ for the IBM C++ compiler; it will
  233. probably work with other compilers, although I haven't tested
  234. this.  You need a C++ compiler and a resource compiler to compile
  235. the dialogs and menus.
  236. :p.
  237. The makefile is compatible with GNU's make.
  238. :p.
  239. You need an IPF compiler (IPFC) to compile the documentation.
  240.  
  241. :h2.general.cpp
  242. This file contains some generally useful functions which are
  243. called from the rest of the code.
  244. :p.
  245. There are 3 error functions, "fatal", "error", and "warning",
  246. indicating various levels of severity.  These are pretty useless
  247. in a PM program.
  248. :p.
  249. There is a memory allocation function, which is pretty useless
  250. for a C++ program.  (Just use "new" instead)
  251. :p.
  252. There are 2 string functions to capitalize and uncapitalize a
  253. string... these are rarely found in C libraries, so they're
  254. included here.  These actually get used in the code.
  255. :p.
  256.  
  257. :h2.splbook.cpp, .hpp
  258. These files contain the C++ classes for handling spells and
  259. spellbooks, and contain no OS/2-specific or PM-specific
  260. information.  Routines for reading and writing spells out
  261. of files are given.
  262. :p.
  263. Note that the classes are set up to allow later addition of
  264. psionic disciplines as a subclass of the general spell.  This
  265. is why the "magespell" class contains things like "school" and
  266. so forth that you would normally associate with all spells.
  267. :p.
  268. If you want to change this program to change the format of
  269. how spells are read in and out (for example to use this
  270. program with another FRP system) this is the file to change.
  271. It is also the most portable to other systems besides OS/2.
  272. :p.
  273.  
  274. :h2.spl.cpp, .hpp
  275. This is the main file that puts up menus and windows, allows
  276. direct manipulation and so forth... all functions are commented
  277. so experienced programmers should be able to find their way
  278. around.
  279. :p.
  280. There is a class called "spellwindow" which is the window that
  281. shows a list of spells and their icons.  This window uses a
  282. container to display the icons.  A double-linked list of all
  283. active spellwindows is pointed to by the variable "first".
  284. :p.
  285. There is also a class called "slwindow" (clever, huh?) which
  286. shows one individual spell when you double-click on it.  This
  287. window uses a multi-line entry field (MLE) to display the
  288. spell.  A linked list of these is pointed to by "firstspell".
  289. :p.
  290. Naturally, this is really confusing and I'll try to clean
  291. things up in a later version of the program!
  292. :p.
  293. :h1.Planned enhancements
  294. :p.
  295. These are things I plan to add to the program in the future, both
  296. in order to give it more functionality, and in order to learn more
  297. about PM programming myself.  If you would like to help me out
  298. with any of these, please let me know what you're working on.
  299. :p.
  300. Better error handling.
  301. :p.
  302. On-line help from within the program.
  303. :p.
  304. More views of the main container window... text view, details view,
  305. and large icon view should all be options.
  306. :p.
  307. More ways to sort spellbooks.
  308. :p.
  309. Allowing users to edit spells in a way that actually works.
  310. :p.
  311. More drag and drop stuff... should allow you to drop a text file
  312. into a spell window and read it in.  Also, should allow you to
  313. drag a spell onto the printer and print it.  Drag and drop
  314. icon assignment would also be cool.
  315. :p.
  316. :euserdoc.
  317.