home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / sm099e.zip / readme.txt < prev    next >
Text File  |  1997-01-26  |  9KB  |  210 lines
  1. // -------------------------------------------------------------------------
  2. //       File: readme.txt
  3. //       Date: January 26. 1996.
  4. // Written by: Leif-Erik Larsen. Norway.
  5. // -------------------------------------------------------------------------
  6.  
  7.  
  8.  
  9. S O U R C E   M A P P E R   ( S M )
  10. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  11.  
  12.  
  13. General information
  14. ~~~~~~~~~~~~~~~~~~~
  15. This is the "read-me" file for the Source Mapper (SM) program. You should
  16. read this document before you start using SM.
  17.  
  18.  
  19. This is FREEWARE!
  20. ~~~~~~~~~~~~~~~~~
  21. Source Mapper has now turned to be freeware! There are several reasons
  22. for this. The first I would like to mention is the fact that no one
  23. has registered it! So you people hopefully get what you wants, - FREEWARE!
  24. The other reason is that I've bought IBM Visual Age C++ v.3.0 for OS/2.
  25. And guess what! - I am really impressed about this product. It has built
  26. in support for most of the things that Source Mapper can do, plus a lot
  27. more...
  28.  
  29. So please feel free to use and distribute this program. This is true
  30. only if you fully agree on the below points:
  31.  
  32. - Don't sell it.
  33. - Don't modify it.
  34. - Don't distribute it without this README-file.
  35.  
  36.  
  37. What is Source Mapper (SM) ?
  38. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39. With SM you can make a useful (human readable) map of your C-style source
  40. codes. You can generate a map of a single sourcefile, or you can have SM
  41. generate a map of a huge project that consists of many source files.
  42.  
  43. The map is espesially useful when you need to document the source(s)
  44. of your project. I've also found it helpful when digging into sources written
  45. by others.
  46.  
  47. The produced map is divided into sections. The main sections are:
  48.  
  49. * Total information and statistics.
  50.   This includes some statistical information about all the sources of your
  51.   project. How many lines are empty? How many lines are real code? How many
  52.   functions and comments are there? Etc. You will also find a sorted list
  53.   of all source files in the map, with easy-to-find line number references
  54.   of where each of the sources begin listening in the map. Each line in the
  55.   map will have two types of line numbering. Local (offset line number
  56.   within the given module) and global. Local line numbers are referenced
  57.   with "L-nnn" while global line numbers are referenced with "G-nnn".
  58.  
  59. * Function register.
  60.   Sorted list of all functions in your project. Each function in the
  61.   register will show you both the local and the global line number to let
  62.   you find the source of the functions quickly.
  63.  
  64. * List of function calls.
  65.   With information about by which function each of the functions in your
  66.   project is called. This section is not implemented to the map by default.
  67.   If you want it you must manually enable it using the ilf[+] option.
  68.  
  69. * Identifier list.
  70.   With information about which identifier is used where, and by which
  71.   function. This section is not implemented to the map by default. If you
  72.   want it you must manually enable it using the iil[+] option.
  73.  
  74. * List of calling sequences.
  75.   This is a hierarcial view of how all your functions are called. All top
  76.   level functions are listed within separate trees. By default this section is
  77.   generated as a compact list, but you may let SM generate it as a flow chart
  78.   if you like. To do this you must use the csf[2] option.
  79.  
  80. * Source lines map.
  81.   This section lists the source code of the modules in your project.
  82.   For each function you will se a list of which function(s) calling it.
  83.   You will also se every comment lines clearly marked, as well as a smart
  84.   block indentation level marking. Each line will be listed with its
  85.   global line number reference, as well as its local.
  86.  
  87. All this will (by default) be included within C-style comments. This let you
  88. actually compile the map as one-single-huge module.
  89.  
  90. In addition you have access to a number of other functions in Source Mapper:
  91.  
  92. * Automatically add a page-break-character above each function/module/section.
  93.   You can also put a string (e.g. "/*{Pagebreak}*/") at different locations
  94.   in your sources of which SM will automatically replace with a new-page-char
  95.   in the map. For more information, see the options NPs[] and NPS[]
  96.   (New-Page-String).
  97.  
  98. * Optional sorting methods.
  99.  
  100. * Optional level of display output during map generation (see option dis[n]).
  101.  
  102. * Make/Build/Link options to let you control if SM will delete .smo-files
  103.   or not. If you choose not to delete them, then the generation time may be
  104.   dramatically reduced the next time you generate a map of the same project.
  105.   If one of the source modules has changed, then SM will automatically
  106.   rebuild the corresponding .smo-file.
  107.  
  108. To get help about which functions are availible, just type "sm.exe hlp[]" at
  109. the command prompt, and you are on the road...
  110.  
  111.  
  112. Contacting the author
  113. ~~~~~~~~~~~~~~~~~~~~~
  114. Leif-Erik Larsen
  115. Aasenvegen 32b
  116. 1400 Ski
  117. Norway
  118.  
  119. E-mail: leilarse@sn.no
  120. WWW:    http://home.sn.no/~leilarse/
  121.  
  122. Feel free to give me any suggestions or comments. I will be happy to hear what
  123. you think about SM, either you like it or not.
  124.  
  125.  
  126. Technical information
  127. ~~~~~~~~~~~~~~~~~~~~~
  128. SM has been successfully compiled by the following compilers.
  129.  
  130. OS/2  : IBM Visual Age C++ v.3.0, and Borland C++ v.2.0 for OS/2.
  131. DOS   : Borland C++ v.3.1 for DOS.
  132. WIN32 : Borland C++ v.4.52 for Windows.
  133. DOS386: GNU C-Compiler v.2.6.3 for DOS (DJGPP).
  134. UNIX  : GNU C-Compiler v.2.6.3
  135.  
  136.  
  137. Known bugs and problems
  138. ~~~~~~~~~~~~~~~~~~~~~~~
  139. * The tree list of calling sequences may contain branches with dead ends.
  140.   This is not really a bug, but a problem due to the algorithm used by SM
  141.   to generate the tree. It will be fixed before the final 1.0 release of SM.
  142.  
  143. * The 'cse[]' (column separator) option doesn't work correctly.
  144.  
  145.  
  146. Hints and Tips
  147. ~~~~~~~~~~~~~~
  148. 1. Remember: SM isn't actually a compiler. It's just a stupid parser that has
  149.    the ability to reqognice most C style code. Therefore, try to write your
  150.    code as structured as possible, containing as few odd statements as
  151.    possible. This is true if you use much preprocessor code, which SM hasn't
  152.    the ability to reqognice as good as it reqognices the true C code.
  153.  
  154. 2. If you get some strange error messages (or map output) during the
  155.    generation of a source map: Try to delete all SM-object files (.smo-files)
  156.    of your project and make the map again. Optionally you can turn the
  157.    'dto[+]' option on (auto delete .smg-files after use) to make sure that
  158.    SM will always use fresh .smg-files.
  159.  
  160. 3. If you get some strange (or maybe even buggy) output from SM, then please
  161.    take a close look at the source code of where the error seems to occour.
  162.    SM has some problems on parse some rare types of syntax. (See paragraph #1.)
  163.  
  164.  
  165. Things to add or fix
  166. ~~~~~~~~~~~~~~~~~~~~
  167. * All language dependent information (except text strings) should be user
  168.   configurable. This is true for key words of the C language, graphical
  169.   characters of lines, etc.
  170.  
  171. * Support for redirected input/output (stdin/stdout).
  172.  
  173. * Improved security when creating files. Eventually asking user if it's ok to
  174.   write over an already existing file. This is true in case the file is of a
  175.   type other than the type that SM is about to create.
  176.  
  177. * Adjustable default extention of sources and maps (+ other files).
  178.  
  179. * All error messages should be written to stderr rather than stdout by default.
  180.  
  181. * Option: Automatic convert from tabulator characters to spaces (in sources).
  182.  
  183. * Option: Include/exclude external functions to/from list of calling sequences.
  184.  
  185. * A GUI-shell of where the user can adjust the project and its settings
  186.   simply by drag/drop and click using the mouse.
  187.  
  188.  
  189. Warranty
  190. ~~~~~~~~
  191. Use of this software for any purpose whatsoever constitutes your unqualified
  192. acceptance of the following statements.
  193.  
  194. The author makes no warranty or representation that the software will be
  195. error free. The author disclaims any warranties, either express or implied,
  196. including but not limited to any implied warranty of merchantability or
  197. fitness for any particular purpose.
  198.  
  199. The user agrees to take full responsibility for the selection of and any use
  200. whatsoever made of the software.
  201.  
  202. IN NO EVENT WILL THE AUTHOR BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING
  203. WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS
  204. INTERRUPTION, LOSS OF BUSINESS INFORMATION OR THE LIKE) ARISING OUT OF THE
  205. USE OF, INTERRUPTION IN THE USE OF, OR INABILITY TO USE THIS SOFTWARE, EVEN
  206. IF THE AUTHOR HAS BEEN ADVISED OF ANY POSSIBILITY OR LIKELIHOOD OF SUCH
  207. DAMAGES.
  208.  
  209.  
  210.