home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / languages / northc_384 / translate / readme < prev    next >
Text File  |  1990-09-08  |  4KB  |  88 lines
  1.  
  2.   This is a program to translate text files between different formats, the 
  3. program is not complete or fully tested but it has never been published 
  4. before and does a job that I find useful.
  5.  
  6.   To explain what the program does I will first outline the problem that 
  7. it solves, this has to do with the documentation files in NorthC.
  8.  
  9.   The files have to be stored on the disk in a format that "MuchMore" can 
  10. deal with, I happen to have decided to store all my documents in pure 
  11. ASCII.  So the next obvious question is how to create the documents, well 
  12. this is quite easy, I happen to know Richard Stallman's "Emacs" editor 
  13. quite well so I use "memacs".  The problem is that "memacs" while being 
  14. great for quickly moving blocks of text around and general editing, 
  15. suffers from a couple of problems, first there is no easy way to set up 
  16. the justification I want, and more importantly there is no way to check 
  17. that the spelling is correct.  The justification I could write a special 
  18. program for, the spelling is more of a problem, there are plenty of spell 
  19. checking programs unfortunately most of them are for American rather than 
  20. English.  Well the solution is that I have a program that will do English 
  21. spelling, and justification, a "proper" word processor that I use to type 
  22. documents and letters, so what I need is a program to translate a text 
  23. file from "normal" ASCII to the format the program requires, and of course 
  24. a program to translate back to ASCII.
  25.  
  26.   Well rather than write two special programs to translate into document 
  27. form and from document for I thought I would just write the one program to 
  28. translate a text file based on a data file.
  29.  
  30.   The data file describes the way that the translation is to be done, the 
  31. first thing to note is that any line starting with a '#' will be treated 
  32. as a comment, any line starting with a '$' will set a variable, so for 
  33. example
  34.  
  35.     # This is a comment
  36.     $line 75
  37.  
  38. sets the line length to 75 characters.  The first "real" data in the file 
  39. tells the program how to translate between the formats, the '\' character 
  40. has a special meaning
  41.  
  42.     "\\"    becomes '\'
  43.     "\n"    becomes a <newline> character
  44.     "\t"    becomes a <tab> character
  45.     "\_"    becomes a <translates to> character
  46.     "\ "    becomes a <space> character
  47.  
  48. so for example
  49.  
  50.     \n\t\_\t
  51.  
  52. says that any <newline> character followed by a <tab> will translate to a 
  53. single <tab> character.  The next interesting question occurs when we have 
  54. two translations such as,
  55.  
  56.     \n\_\t
  57.     \n\t\_\ ?
  58.  
  59. the question is if we see a <newline> character in the file should we replace 
  60. it with a tab or should we wait to see if the next character is a <tab>.  The 
  61. answer is of course that we must wait, but this does restrict the translations 
  62. we can put in the data file.  In general if you put the short translations 
  63. first then things will work out about right.
  64.  
  65.   Each translation sequence appears on a separate line, the last translation 
  66. sequence has a blank line after it.  After the translations there is a list 
  67. of the files to do the translations on, for example
  68.  
  69.     Changes    "NorthC:CHANGES"              "t:Changes"
  70.     Contents   "NorthC:CONTENTS"             "t:Contents"
  71.     NthCREADME "NorthC:README"               "t:NthCREADME"
  72.  
  73. this give three entries for each file, first a name by which the file can 
  74. be reffered, second the source file name and finally the destination file 
  75. name.
  76.  
  77.   If you specify an object to transfer with the "-o" flag, for example
  78.  
  79.     translate -oChan "NorthC to doc"
  80.  
  81. then the program will translate all the files whose names start with "Chan", 
  82. this allows you to deal with small sets of file at a time.
  83.  
  84.   As the program currently stands it has not been tested, it does what I want 
  85. it to do and I could not be bothered to take it much further.  If you find 
  86. any bugs, or manage to improve the program please send me a copy, and tell 
  87. me if I can include it on the NorthC disk.
  88.