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