home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / emulate / crlf13.lha / crlf.doc < prev    next >
Text File  |  1991-10-15  |  14KB  |  382 lines
  1.  
  2.                         CRLF 1.3   by V. Gervasi
  3.  
  4.  
  5.         CRLF is a handy program to convert format of ASCII files between
  6.         different machines, and can be used to produce double- or
  7.         triple-spaced texts, too.
  8.  
  9.  
  10.  
  11.  1.     The Problem
  12.  
  13.      Even if ASCII is one of the few standards that are standard enough to
  14.      simplify the life of us poor users, different machines and different
  15.      OSs often use different convention to signify end-of-line.
  16.      As an example, the AmigaOS uses the "LF" code (decimal 10), the
  17.      Macintosh uses "CR" (decimal 13), MS-DOS uses "LF/CR" (waste of
  18.      space, even if more correct) and so on.
  19.  
  20.      Since I found myself often porting software and docs between these
  21.      machines (among other...), I decided to write a little utility to
  22.      solve the problem. I hope it will help you in some way !
  23.  
  24.  
  25.  
  26.  2.     The Solution
  27.  
  28.      CRLF will read any amount of input, in any end-of-line style (it will
  29.      decide by himself) and output the same text, in a convention of your
  30.      choice. Various options are available to determine the end-of-line
  31.      convention to use, the source and the destination of the work and
  32.      some other aspect. I beleive the I/O options are quite extensive.
  33.  
  34.  
  35.  
  36.  3.     What CRLF WON'T do
  37.  
  38.      CRLF is a very simple-minded program. You cannot feed it arbitrary
  39.      data (such as WP documents, graphics, executables...) to convert
  40.      to other systems... "we are still working on it".
  41.      CRLF will not attempt any formatting of the resulting data. So, no
  42.      80-column word-wrap around or other frills (I suggest you to use some
  43.      other filter-style program to do such things), nor will it transla-
  44.      te strange character (code >127), nor even normal ones, for this
  45.      matter.
  46.      All what CRLF do is to change the end-of-line style. Stop.
  47.  
  48.  
  49.  
  50.  4.     Options
  51.  
  52.      CRLF may be given very complex command lines. Here is a summary:
  53.  
  54.      The basic format of the command is
  55.  
  56.                 CRLF [options] [files]
  57.  
  58.      where [...] means that element is optional. However, options and
  59.      files may be mixed together without harm; CRLF will first scan the
  60.      arguments collecting options, then will work on the given files.
  61.  
  62.      At present release (1.3), these options are available:
  63.  
  64.         -cr     output will have a cr at end of line (*)
  65.         -lf     output will have a lf at end of line (*)
  66.         -A      output will be in Amiga format (lf)
  67.         -M      output will be in Macintosh format (cr)
  68.         -D      output will be in MS-DOS format (cr/lf)
  69.         -U      output will be in UNIX format (lf)
  70.  
  71.      (*) You can specify up to 16 of these options; cr's and lf's will
  72.          be outputted following the order of the parameters.
  73.  
  74.         -v      be verbose (prints the file names as it processes them)
  75.  
  76.         -b<n>   set I/O buffers size to <n>; default is 16384.
  77.                 If <n> is lower than 512, a value of 512 will be used.
  78.  
  79.         -s<s>   append <s> after the name of the input file to obtain
  80.                 the name of the output file
  81.         -p<s>   prepend <s> before the name of the input file to obtain
  82.                 the name of the output file
  83.         -!      overwrite the input file, convert "in place"
  84.  
  85.  
  86.      If no file is given, stdin & stdout will be used, so that CRLF
  87.      acts as a true "UNIX style" text filter.
  88.  
  89.      If no -s, -p or -! option is given, CRLF will regard the given file
  90.      names as <input,output> pairs, until the list is exhausted.
  91.  
  92.      If no -cr, -lf, -A, -M, -D or -U is given, the default is -A.
  93.  
  94.      If -s, -p or -! IS given, you can use AmigaDOS patterns as file names.
  95.  
  96.      If you give a -s or -p without any <string>, the default is to use
  97.      the empty string "", but CRLF will act as in "suffix" or "prefix"
  98.      mode (thus allowing patterns).
  99.  
  100.      "CRLF ?" will print an help page.
  101.  
  102.      Note: Some options are mutually exclusive:
  103.            * -A,-M,-D,-U are incompatible each other and with any -cr or -lf;
  104.            * -cr and -lf may be given together, but not in conjunction with
  105.              any other "style" option (-A,-M,-D or -U);
  106.            * -p and -s may be given together, but not with -! ;
  107.            * -! may not be given with a -p or -s;
  108.            * -v may be given with any other combination of options.
  109.  
  110.      Apart from -cr, -lf and -v, options may not be given more than one
  111.      time. Specifying multiple -v is a no-op, while specifying more -cr
  112.      and -lf describes the custom eol-style to use.
  113.  
  114.      Any other word not starting with a "-" is taken to be a file name.
  115.  
  116.  
  117.  
  118.  5.     CRLF behaviour
  119.  
  120.      After collecting options, CRLF start analyzing the given files.
  121.  
  122.      If no file is given, CRLF assumes stdin as input and stdout as output
  123.      and starts converting until End-Of-File is reached (from the keyboard,
  124.      this may be simulated with a CTRL-\).
  125.      Every -s, -p or -! is ignored, since there are no files involved.
  126.  
  127.      If -s or -p was specified (even with null strings as arguments),
  128.      CRLF goes to "suffix/prefix" mode. It will use the given file names
  129.      as input, and the <prefix><base name><suffix> strings as output file
  130.      names (<base name> is the name of the file, minus the path).
  131.      If verbose is active, these names will be printed to the standard
  132.      output.
  133.  
  134.      If -! was specified, CRLF goes to "overwrite" mode. It will use the
  135.      given file names as input, will put output in a temporary file that
  136.      will be created in the "T:" directory, if no volume or directory was
  137.      present in the original file name, otherwise in the same directory as
  138.      the original.
  139.      After the conversion, CRLF will REMOVE the original file and RENAME
  140.      the temporary file to the old name.
  141.      The RENAME operation will be performed via a DOS rename if possible,
  142.      via a copy/delete of the temporary file otherwise.
  143.      Note that there is always at least one copy of the file, so damage in
  144.      case of failure should be minimal.
  145.  
  146.      If no -s, -p or -! was specified, CRLF goes to "twin" mode.
  147.      Each couple of file given is taken to signify <input,output>.
  148.      CRLF will convert the FIRST file of the couple, leaving the result in
  149.      a file named as the SECOND file.
  150.      If you specify "::" as the name of the second file, it is taken to
  151.      mean "stdout" (since :: is not a valid file name).
  152.      Obviously, there must be an even number of file names...
  153.      In case of an ODD number of names, the last one is ignored silently.
  154.  
  155.  
  156.  
  157.  6.     CRLF Limits
  158.  
  159.      CRLF holds some internal buffer to do his work. Here are the limits:
  160.  
  161.         * max 16 -cr/-lf specifiers;
  162.         * max cumulative length of all file names resulting from a single
  163.           pattern expansion is 16384 chars;
  164.         * max lenght of a "base" name (file name without path) is limited
  165.           to 50. Note that current AmigaDOS has a limit of 30.
  166.         * min lenght of I/O buffers is 512; there is no max value.
  167.           CRLF will try to allocate 2 of this buffers; the bigger the
  168.           buffers, the faster the processing. However, the default of
  169.           16384 should work fine in every situation.
  170.  
  171.  
  172.  
  173.  7.     CRLF Messages
  174.  
  175.         "Warning: Cannot mix xxx and yyy, xxx ignored"
  176.  
  177.                 You have specified two incompatible options; the former
  178.                 will be retained and the latterd discarded.
  179.                 See above, section 4, for details.
  180.  
  181.         "Warning: Too many -cr/-lf options, xxx ignored"
  182.  
  183.                 You have exceeded the limit of 16 -cr/-lf specifiers.
  184.                 Any -cr/-lf in excess will be ignored.
  185.  
  186.         "ERROR: Unknown option xx, ignored"
  187.  
  188.                 You put an illegal option in the command line.
  189.                 If you have a file starting with a "-" you are in troubles.
  190.                 Try substituting the dash with a "?".
  191.                 See sections 4 and 5 for details.
  192.  
  193.         "PANIC: Out of memory - cannot build outfile name"
  194.  
  195.                 Your system is very low on memory. Execution is aborted.
  196.                 Try freeing some memory (closing windows, quitting other
  197.                 applications).
  198.  
  199.         " xxx -> yyy"
  200.  
  201.                 You have set verbose mode.
  202.                 CRLF is converting xxx's end-of-line style, result will
  203.                 be found in yyy.
  204.  
  205.         "ERROR: Cannot open output file xxx"
  206.  
  207.                 For some reason, file xxx cannot be opened for writing.
  208.                 Current conversion will be skipped.
  209.  
  210.         "WARNING: Cannot open input file xxx"
  211.  
  212.                 For some reason (usually a non-existing file or a file in
  213.                 exclusive use of some other program), file xxx cannot be
  214.                 opened for reading.
  215.                 Current conversion will be skipped.
  216.  
  217.         "WARNING: Buffers size too low, set to xxx"
  218.  
  219.                 You set an I/O buffers size too small. Minimum is 512.
  220.                 Just ignore the message, or remove the -b option, or simply
  221.                 set an higher value.
  222.  
  223.         "ERROR: Cannot allocate buffer to copy xxx"
  224.         
  225.                 CRLF could not allocate a buffer to copy xxx to his natural
  226.                 place (in overwrite mode). You are left with the converted
  227.                 file in xxx instead of having it overwrite the original.
  228.  
  229.         "WARNING: Cannot rename xxx"
  230.         "WARNING: Cannot copy it to yyy"
  231.  
  232.                 In overwrite mode, CRLF could not rename, nor copy the
  233.                 temporary file xxx to yyy. Maybe some file is protected,
  234.                 or a device is read/only, or T: has disappeared (!).
  235.  
  236.         "ERROR: Cannot re-open xxx"
  237.  
  238.                 This is a strange error, since the program just finished
  239.                 writing a file xxx and cannot re-open it. Maybe the
  240.                 temporary file was created on a write-only device ?
  241.  
  242.  
  243.  
  244.  8.     CRLF Bugs
  245.  
  246.      None known at the moment.
  247.  
  248.  
  249.  
  250.  9.     CRLF History
  251.  
  252.  
  253.      1.0        11-Mar-91
  254.  
  255.                 First release. Seems to work.
  256.  
  257.      1.1         5-Apr-91
  258.  
  259.                 Emended some minor bugs and refined documentation.
  260.  
  261.      1.2        30-May-91
  262.      
  263.                 Removed limit on max line lenght (to accomodate for
  264.                 HP-48 GROBs...)
  265.  
  266.  
  267.  
  268. 10.     Examples
  269.  
  270.      "crlf"
  271.  
  272.         Simplest form, convert from any input in stdin to Amiga format
  273.         in stdout. May be used with redirection or with pipes, if your
  274.         shell supports pipes.
  275.  
  276.      "cat #? | crlf >ser:"
  277.  
  278.         This will collect together all the files in the current directory
  279.         and send them (converted to Amiga format) to the serial port.
  280.  
  281.      "crlf <ser: >prt:"
  282.  
  283.         This will receive his input from the serial port (pheraphs
  284.         connected to some other machine) and print it to the system
  285.         printer, in Amiga format.
  286.  
  287.      "crlf <ser: >prt: -lf -lf"
  288.  
  289.         As above, but double-spaced.
  290.  
  291.      "crlf ms0:CRYPT.ASM Work:crypt.s"
  292.  
  293.         We work in twin-mode. File ms0:CRYPT.ASM (in MS-DOS format) will
  294.         get his way to Work:crypt.s in Amiga format.
  295.  
  296.      "crlf -D data.c1.print ms0:DATA.TXT"
  297.  
  298.         (Amiga ?) File data.c1.print will go to ms0:DATA.TXT in MS-DOS
  299.         format.
  300.  
  301.      "crlf -pram: -s.mac MACFILES:#?"
  302.  
  303.         All files in the MACFILES: volume will go to ram: in Amiga format,
  304.         with an extension of ".mac".
  305.         Note: MACFILES:xxx -> ram:xxx.mac
  306.  
  307.      "crlf -v -pram: -s.mac MACFILES:#?"
  308.  
  309.         As above, but file names will be printed during the conversion.
  310.  
  311.      "crlf -! -A #?.c"
  312.  
  313.         Each and every C source in the current directory (collected from
  314.         MS-DOS, Macintosh, Unix etc...) will be translated to Amiga
  315.         format. Files will be overwritten.
  316.  
  317.      "crlf -lf -cr -cr -lf -s.odd #?"
  318.  
  319.         Each file in the current directory will be translated to the (odd)
  320.         format
  321.                 xx xx xx xx xx lf cr cr lf
  322.                 yy yy yy yy yy lf cf cf lf
  323.                       . . . . . .
  324.  
  325.         The resulting files will have an extension of ".odd"
  326.  
  327.      "crlf -sqq -! #?"
  328.  
  329.         This is illegal. Only one of -s or -! may be given. In this
  330.         example, -! will be ignored and each file will go (in Amiga format)
  331.         to <file>qq
  332.  
  333.      "crlf -v -M -pWork:mac/ Work:msdos/#?"
  334.  
  335.         Each file in the Work:msdos directory will be duplicated, in Mac
  336.         format, in the Work:mac directory. File names will be printed at
  337.         the terminal during the process.
  338.  
  339.      "crlf -D >ram:log -v -! #?.c #?.pas #?.s"
  340.  
  341.         Every file in the current directory ending in .c, .pas or .s get
  342.         translated to MS-DOS format. A list of the conversions is leaved
  343.         in ram:log.
  344.         Note:   Using "#?.c|#?.pas" instead of "#?.c #?.pas" is more
  345.                 efficient and time-saving...
  346.  
  347.  
  348.  
  349. 11.     Final note
  350.  
  351.      I hope CRLF will be of some use to you. If you have any bug report,
  352.      suggestion or other, I can be reached at the following e-mail
  353.      addresses:
  354.  
  355.         UUCP:           {rutgers|pyramid}!cbmvax!cbmehq!cbmita!icarus!vigi
  356.         Internet:       mira6@dipisa.di.unipi.it
  357.         FidoNet:        Vincenzo Gervasi  2:332/602
  358.  
  359.      This program is public domain.
  360.      Only restriction is that the executable code and this document must
  361.      go together in their original, unmodified state.
  362.  
  363.      Enjoy !
  364.  
  365.  
  366.  
  367.  
  368.      Amiga and AmigaDOS are trademark of Commodore-Amiga, Inc.
  369.      MS-DOS is a trademark of Microsoft Corp.
  370.      Macintosh is a trademark of Apple Computer, Inc.
  371.      UNIX is a trademark of Bell Laboratories.
  372.      CRLF is not a trademark.
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.      V. Gervasi                                         Oct 15, 1991
  380.  
  381.  
  382.