home *** CD-ROM | disk | FTP | other *** search
/ Software Recommendations - 1998 Season 1 / DNBCD4.iso / develop / tool / zip / SRCMRG10.ZIP / SRCMERGE.TXT < prev    next >
Encoding:
PGP Message  |  1997-06-16  |  9.6 KB  |  260 lines
  1. -----BEGIN PGP SIGNED MESSAGE-----
  2.  
  3.  
  4.                            SourceMerge version 1.0
  5.  
  6.                         by Simone Zanella Productions
  7.  
  8. Contents
  9.  
  10.      * Introduction
  11.      * Installation
  12.      * Usage
  13.      * If you want to report a problem...
  14.  
  15.    This documentation, along with the most recent version of the
  16.    software, is available via the World-Wide Web at
  17.    <http://www.dsi.unive.it/~szanella/index.htm> or
  18.    <http://members.tripod.com/~szanella/index.htm>.
  19.  
  20. Introduction
  21.  
  22.    This program can be used to maintain different versions of the same
  23.    source code. It is especially useful for producing programs in different
  24.    languages. Since it is very configurable, it can be adopted for many
  25.    different languages: C, C++, Html, Assembly, Clipper.
  26.  
  27.    SourceMerge can be used on text files for Dos/Windows, Macintosh and
  28.    Unix, even mixed (i.e. library file in one format, source file in
  29.    another). Text files created have always the same format as the
  30.    corresponding source file.
  31.  
  32.    Files included:
  33.  
  34.    SRCMERGE.EXE     SourceMerge program
  35.    SRCMERGE.TXT     this file
  36.    TEST.HTM         test file, to be used with TEST.LIB
  37.    TEST.LIB         library file to be used with TEST.HTM
  38.  
  39. Installation
  40.  
  41.    Just copy SRCMERGE.EXE to a directory in your path.
  42.  
  43. Usage
  44.  
  45.    As usual, an example is the easiest way to demonstrate SourceMerge's use.
  46.    The command line for it is as follow:
  47.  
  48.    SRCMERGE spec /Llib /Vver [/Sxy] [/Ddest] [/Brem_begin] [/Erem_end] [/X]
  49.  
  50.    "spec" is the pathname of the files to process, including wild cards.
  51.    SourceMerge supports long file names under Windows 95; it also supports
  52.    multiple wild cards '*' and '?' both under real Ms-Dos and Windows 95.
  53.    Use parameter /X to avoid long file name matching.
  54.  
  55.    "lib" is the name of the library file to be used; it can have any
  56.    extension, even though I use ".LIB" in these examples.
  57.    The library file is a text file formatted like an .INI file for Windows.
  58.  
  59.    Each section starts with:
  60.  
  61.    [id:ver]
  62.  
  63.    and ends with the next section or the end of file.
  64.    The characters '[' and ']' enclosing id:ver can be changed by using
  65.    parameter /Sxy - x stands for prefix and y for suffix (each one is 1
  66.    character long): this can be useful if the text to be replaced can
  67.    contain a line similar to a section start.
  68.  
  69.    For example, suppose that you have this C fragment that defines two
  70.    strings into the file SAMPLE.C:
  71.  
  72.    #define WELCOME  "Benvenuto"
  73.    #define BYE      "Arrivederci"
  74.  
  75.    The strings are in Italian; if you want to produce two versions of
  76.    the same program, one in Italian and the other in English, replace
  77.    the text above with:
  78.  
  79.    /* SRCM:welc_bye. */
  80.    /* /SRCM:welc_bye. */
  81.  
  82.    and create the library file MYTEST.LIB with this text:
  83.  
  84.    [welc_bye:italian]
  85.    #define WELCOME  "Benvenuto"
  86.    #define BYE      "Arrivederci"
  87.    [welc_bye:english]
  88.    #define WELCOME  "Welcome"
  89.    #define BYE      "Goodbye"
  90.  
  91.    Now, to create a version in one language or the other use:
  92.  
  93.    SRCMERGE sample.c /lmytest.lib /vitalian
  94.    SRCMERGE sample.c /lmytest.lib /venglish
  95.  
  96.    Of course, in this case it would be easier to put all definitions into
  97.    the source code and select one version or the other with #ifdef;
  98.    but there are languages in which this is impossible to do, and cases more
  99.    sophisticated in which the same thing is not so easy (e.g. when you
  100.    actually must ADD code for specific versions). Moreover, the source code
  101.    is cleaner and more comprehensible to read by using this method.
  102.    Take a look at TEST.HTM and TEST.LIB; to produce different versions,
  103.    you can use:
  104.  
  105.    SRCMERGE test.htm /ltest.lib /vSimone
  106.    SRCMERGE test.htm /ltest.lib /vPaolo
  107.    SRCMERGE test.htm /ltest.lib /vFranco
  108.    SRCMERGE test.htm /ltest.lib /vMassimo
  109.  
  110.    As you should have noticed, each section in the source code is a block of
  111.    text starting with:
  112.  
  113.    b SRCM:id. e
  114.  
  115.    and ending with:
  116.  
  117.    b /SRCM:id. e
  118.  
  119.    Optional text can be inserted between the '.' and 'e'; it is simply ignored.
  120.  
  121.    The characters 'b' and 'e' are remark strings which can be specified with
  122.    parameters /B and /E; if not specified, they are guessed according to
  123.    source file extension, as in this table:
  124.  
  125.                      Extension      'b' string     'e' string
  126.                         .C               /*            */
  127.                         .H               /*            */
  128.                        .CPP              //
  129.                        .HPP              //
  130.                        .HTM             <!--           -->
  131.                        .PRG               *
  132.                         .CH               *
  133.                        .INI              rem
  134.                        .SYS              rem
  135.                        .BAT              rem
  136.                        .MNU               ;
  137.                        .ASM               #
  138.                        other              #
  139.  
  140.    As you can see, 'e' strings can be empty; in this case, the tag ends
  141.    at the end of line:
  142.  
  143.    printf("this is a test\n");  // SRCM:id. <-- tag ends at the end of line
  144.  
  145.    There must be EXACTLY one space between the remark string 'b' and "SRCM:".
  146.  
  147.    The parameters /L and /V must always be specified: the first defines the
  148.    library file to be used, the second the version with which update on
  149.    source files will take place.
  150.    Remember that both version tags and section IDs are case sensitive:
  151.    italian and Italian are two different version tags, just like welc_bye
  152.    and Welc_Bye are two different section IDs.
  153.  
  154.    On command line, strings for version/remarks and characters to be used
  155.    for prefix/suffix of section (parameter /S) can include C-like constants;
  156.    for example, if you have an HTML file with the extension ".DOS" (which is
  157.    unknown to SourceMerge) and you want to use the string "<!--" for 'b' and
  158.    "-->" for 'e', type:
  159.  
  160.    SRCMERGE test.dos /Ltest.lib /Vtest /B\x3c!-- /E--\x3e
  161.  
  162.    This is necessary since the characters "<" and ">" are preprocessed by Dos
  163.    and are used to redirect standard input/output from/to a file; their
  164.    corresponding C-like strings are:
  165.  
  166.       <     \x3c = \074 = \d60 (Ascii 60)
  167.       >     \x3e = \076 = \d62 (Ascii 62)
  168.  
  169.    Likewise, if you want to use the characters '|' for section prefix and '^'
  170.    for section suffix, on the command line you could use:
  171.  
  172.    /S\x7c^   /S\d124^   /S\174^    (character '^' can safely appear as it is)
  173.  
  174.    The following escape sequences are supported:
  175.  
  176.    \a \b \f \n \r \t \v \\ \? \' \"
  177.  
  178.    and octal, hexadecimal and decimal constants thus specified:
  179.  
  180.    \...  where ... are 1 to 3 octal digits (0-7)
  181.    \x... where ... are 1 to 3 hexadecimal digits (0-9, a-f, A-F)
  182.    \d... where ... are 1 to 3 decimal digits (0-9)
  183.  
  184.    Characters ':' and '.' must be avoided in version strings, just like
  185.    Ascii characters below ' ' (32) in both remark and version strings.
  186.  
  187.    By default, SourceMerge modifies source files 'in place', i.e. the
  188.    files are overwritten with the updated version. If you want to create the
  189.    new version in a different directory, use the parameter /D to set
  190.    destination; in this case, source files won't be touched.
  191.    Remember that all files existing in destination directory are overwritten
  192.    without notice.
  193.  
  194.    Error level is set on exit to:
  195.              0  no errors
  196.              1  missing/wrong command line parameters, empty library
  197.              2  read/write/open error
  198.              3  id not found/syntax error
  199.              4  string too long
  200.              5  insufficient memory
  201.  
  202.    Source files (when parameter /D is NOT specified) are overwritten ONLY if
  203.    the update is succesfull; if /D is used and SourceMerge exits with error
  204.    level 3 or above, the last file created in the destination directory
  205.    will be truncated at the point in which the error happened.
  206.  
  207.    Run SRCMERGE without parameters to have a short summary of its usage.
  208.  
  209. If you want to report a problem...
  210.  
  211.    If you think you've found a genuine problem with SRCMERGE, I'll most
  212.    effectively be able to help you if you give me the following
  213.    information. The more of this you leave out, the less likely I'll be
  214.    able to do anything useful.
  215.      * Your library and source files. Either include it in your mail or
  216.        include a URL so I can fetch it.
  217.      * The exact command line used to process the files.
  218.  
  219.    I won't guarantee to fix every problem, but if you give me a complete
  220.    report, I'll often be able to help.
  221.  
  222.    Send mail if you have comments or suggestions.
  223.  
  224. - ---
  225.  
  226. (C) 1997 Simone Zanella Productions.
  227.  
  228. E-mail: szanella@dsi.unive.it
  229.         zanella@prometeo.it
  230.  
  231. Web:    http://www.dsi.unive.it/~szanella/index.htm
  232.         http://members.tripod.com/~szanella/index.htm
  233.  
  234. Last modified: June 16th, 1997
  235.  
  236. - -----BEGIN PGP PUBLIC KEY BLOCK-----
  237. Version: 2.6.2i
  238.  
  239. mQCNAzARNUQAAAEEAMTn+IgTuJ5Ei99lzFa6D6GCDYPUimdSQ2I2keFCVG2sCVfB
  240. uejwgdPp+u/mlwJDE2wZpAUfgHe8E3N/vmfO6bl0RxOc1Hkl0mc/np5/F4wZoeOB
  241. GcaEpwJLkKlFoE93p8Bh/UwUNo9UaKjfwx0mqP9G+XgiVowo7NEsAHa/+Bl9AAUR
  242. tCpTaW1vbmUgWmFuZWxsYSA8c3phbmVsbGFAbW9vLmRzaS51bml2ZS5pdD6JAJUD
  243. BRAwETVz0SwAdr/4GX0BAXjLA/9IZD5mT/BHdRfDvH6AnFwaxqAuluhCcycchW0A
  244. /SOUJPsmFnFjGUoCFrur603rEUJpR/JsZpVOXaQHcNSuitB2msDu8YZyrVPgcV86
  245. vGptHkX31GrfIK8RR4hHRtt0suUBWZBDJRfLNbq7KMKxfNF3h4wRjC1NBzzU0orM
  246. mj9d2A==
  247. =HOga
  248. - -----END PGP PUBLIC KEY BLOCK-----
  249.  
  250. -----BEGIN PGP SIGNATURE-----
  251. Version: 2.6.3ia
  252. Charset: cp850
  253.  
  254. iQCVAwUBM6bOV9EsAHa/+Bl9AQG3IwP+LwR9FZbavqrGqXp4BgC4WPj4tY4tsRGW
  255. j9QejO94CFwK+tYsyb/biChP24tMnUxzmDZ0YJXToIEt42jJStHapKepnkyhyx65
  256. 8PltWNbOEgd/vmGZ1lE89zwFZ39099vy/FAJjSRCOpnAswGVG3IbrTfPyPGvTl6Z
  257. Uplq/mZ0YsM=
  258. =hfQj
  259. -----END PGP SIGNATURE-----
  260.