home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilsm / mkdrawf / Doc / Custom next >
Text File  |  1995-04-26  |  3KB  |  58 lines
  1.                     Customising and extending mkdrawf
  2.                     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. The simplest way to customise mkdrawf is to #define some of the symbols
  5. described at the start of mkdrawf.c, and recompile. The consequences of
  6. these things are described at the start of that file, so I shan't go into
  7. details here.
  8.  
  9. If you make any other changes, YOU MAY NOT DISTRIBUTE THE RESULTING PROGRAM
  10. IN ANY FORM without first checking with me. I am very anxious that there be
  11. coherence among versions of mkdrawf; I am also anxious that I should not
  12. get the credit for your clever code, nor the blame for your bad code. If
  13. you come up with improvements to mkdrawf, please let me know; they may well
  14. get into the standard distribution.
  15.  
  16. Both as a matter of good programming practice and to improve the chances
  17. of my being happy with your changes, you should arrange for any changes
  18. you make (apart from bugfixes!) to be selectable at compile time with #ifdef.
  19. If you're careful about how you arrange things, it should be possible to do
  20. this without mkdrawf.c becoming a solid mass of preprocessor directives.
  21.  
  22. To add a new operator, you need to:
  23.   - add an entry for it in the |enum| typedef'ed to |spec_type|. The
  24.     convention used for names should be clear.
  25.   - add an |insert_spec()| call to the |init_global_hash()| function,
  26.     to put the operator's name into the hash table. Remember to put
  27.     the name in lower case.
  28.   - add a case in |read_x_token()| to make it do the right thing.
  29.     It is safe to read more tokens here, using |read_token()| (if
  30.     you don't want expansion) or |read_x_token()| (if you do want
  31.     expansion, which you almost certainly do). When you're done,
  32.     you should fill in |the_token| (both fields) if the expansion
  33.     is a single token; or |goto foo;| if the expansion is empty;
  34.     or contruct a token list and start reading that, if the expansion
  35.     is several tokens. This last option is hairier than the others.
  36.  
  37. Please be careful about memory management. It is seldom possible
  38. to free anything; the point is that tokens can find their way into
  39. macro definitions and loops and things, so you can't free anything
  40. that might find its way into a token. This is a real mess, and
  41. eventually I might sort it out, with reference counts or something.
  42. Until then, don't free anything unless you know you're safe. Search
  43. mkdrawf.c for "free(" to get some idea of when it is safe to free
  44. things. Oh, and if you *do* free anything, call |xfree()| not |free()|;
  45. when memory-use debugging is compiled in this displays useful messages.
  46.  
  47. It would be helpful if you could adhere to my layout style (very little
  48. whitespace, substantial comments before blocks of code, short comments
  49. for obscure code); but I know how hard I find it conforming to others'
  50. conventions, and it wouldn't really be fair to insist that you conform
  51. to mine.
  52.  
  53. If you do make changes and they do make it into the "official" version
  54. of mkdrawf, you will be credited with the code that's yours. Copyright
  55. for the program as a whole, though, remains mine; I make no claims on
  56. anyone else's code, but the restrictions on what's done with my code
  57. remain.
  58.