home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / m / makedrawf / Doc / Custom < prev    next >
Text File  |  1995-06-05  |  4KB  |  72 lines
  1.                     Customising and extending mkdrawf
  2.                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. All this applies to version 3.02 of mkdrawf. It probably also applies
  5. pretty well to any other version called 3.xx.
  6.  
  7. The simplest way to customise mkdrawf is to #define some of the symbols
  8. referenced in the source code, and recompile. (The best way to do this
  9. is with the -D option in the Makefile.) Here is a complete list of the
  10. symbols you can define:
  11. TAGS        enable the "tagfile" feature
  12. NO_JPEG        disable the JPEG object type
  13. DEBUG_TOKENS    describe each token as it is read
  14. DEBUG_XTOKENS    describe each expanded token that gets through
  15. DEBUG_MEMORY    indicate when memory is allocated or freed
  16. DEBUG_ALL    all the above debugging options
  17. SLOPPY        compute path bboxes naively. Gives bad results for
  18.         thick lines and curves, but faster and cheaper on memory
  19. VERBOSE_ERRORS    produces longer error messages
  20. ONLINE_MEDIA    define this if you are Online Media :-). Enables a
  21.         ghastly kludge which they need and you don't.
  22.  
  23. If you make any other changes, YOU MAY NOT DISTRIBUTE THE RESULTING PROGRAM
  24. IN ANY FORM without first checking with me. I am very anxious that there be
  25. coherence among versions of mkdrawf; I am also anxious that I should not
  26. get the credit for your clever code, nor the blame for your bad code. If
  27. you come up with improvements to mkdrawf, please let me know; they may well
  28. get into the standard distribution.
  29.  
  30. Both as a matter of good programming practice and to improve the chances
  31. of my being happy with your changes, you should arrange for any changes
  32. you make (apart from bugfixes!) to be selectable at compile time with #ifdef.
  33. If you're careful about how you arrange things, it should be possible to do
  34. this without mkdrawf becoming a solid mass of preprocessor directives.
  35.  
  36. To add a new operator, you need to:
  37.   - add an entry for it in the |enum| typedef'ed to |spec_type|. The
  38.     convention used for names should be clear.
  39.   - add an |insert_spec()| call to the |init_global_hash()| function,
  40.     to put the operator's name into the hash table. Remember to put
  41.     the name in lower case.
  42.   - add a case in |get_x_token()| to make it do the right thing.
  43.     It is safe to read more tokens here, using |get_token()| (if
  44.     you don't want expansion) or |get_x_token()| (if you do want
  45.     expansion, which you almost certainly do). When you're done,
  46.     you should fill in |curr_token| (both fields) if the expansion
  47.     is a single token; or |goto next;| if the expansion is empty;
  48.     or contruct a token list and start reading that, if the expansion
  49.     is several tokens. This last option is hairier than the others.
  50.  
  51. Please be careful about memory management. It is seldom possible
  52. to free anything; the point is that tokens can find their way into
  53. macro definitions and loops and things, so you can't free anything
  54. that might find its way into a token. This is a real mess, and
  55. eventually I might sort it out, with reference counts or something.
  56. Until then, don't free anything unless you know you're safe. Search
  57. the code for "free(" to get some idea of when it is safe to free
  58. things. Oh, and if you *do* free anything, call |xfree()| not |free()|;
  59. when memory-use debugging is compiled in this displays useful messages.
  60.  
  61. It would be helpful if you could adhere to my layout style (not much
  62. whitespace, substantial comments before blocks of code, short comments
  63. for obscure code); but I know how hard I find it conforming to others'
  64. conventions, and it wouldn't really be fair to insist that you conform
  65. to mine.
  66.  
  67. If you do make changes and they do make it into the "official" version
  68. of mkdrawf, you will be credited with the code that's yours. Copyright
  69. for the program as a whole, though, remains mine; I make no claims on
  70. anyone else's code, but the restrictions on what's done with my code
  71. remain.
  72.