home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 5 / ctrom5b.zip / ctrom5b / DOS / GRAFISCH / GIFCM133 / GC133.DOC < prev    next >
Text File  |  1994-11-16  |  23KB  |  516 lines
  1.         The GIF COMMENTOR v1.33
  2.  
  3.         INTRO
  4.  
  5.         As with many other utilities, this one was written because its
  6.         author could not find an existing one which would do what was
  7.         required: embed textual comments into GIF files. Most of the
  8.         more popular GIF viewers have a facility for viewing embedded
  9.         comments. A picture may be worth a thousand words, but often
  10.         some explanatory text is also very helpful. Many GIF files of a
  11.         technical nature have lengthy embedded comments, but if for some
  12.         reason one has to edit the graphic part of the file, say by
  13.         cropping, then save the resultant GIF, the comment part is
  14.         missing from the new GIF (and often replaced by an advertisement
  15.         for the cropping program!) GIF Commentor enables the comment to
  16.         be easily reembedded. It can also be useful to embed the
  17.         original GIF filename in the GIF particularly if it is abstract
  18.         (eg.  PB1147-A.GIF) and one wishes to rename it to something
  19.         more descriptive, or if the original GIF filename is longer than
  20.         DOS allows (eg.  EARTH_BY_NIGHT.GIF - many GIF sources are Unix
  21.         based).
  22.  
  23.  
  24.  
  25.         WHAT'S NEW from v1.2
  26.  
  27.         1. Scanning of the current directory and reporting the number of
  28.         existing comments in any GIF files found.
  29.  
  30.         2. Viewing of embedded comments: last comment, a specified
  31.         comment or all comments. An in-built scrolling text viewer with
  32.         Find and Repeat find features facilitates comment viewing (see
  33.         below for details). This saves having to view the GIF if you
  34.         merely want to read its comments; also most GIF viewers provide
  35.         only static comment display.
  36.  
  37.         3. Removal of any comment by erasure (overwriting the text with
  38.         spaces) where removing it by truncating the GIF file might
  39.         damage what remains.
  40.  
  41.  
  42.         Changes in Existing Features from v1.2
  43.  
  44.         The previous Remove, No prompt (/rn) mode has been renamed to
  45.         Remove, without (eX) prompting (/rx) mode to avoid confusion
  46.         with Remove nth comment (/r[n]). Also, previously the Remove
  47.         last comment operation aborted if the last comment was unsafe to
  48.         remove by truncating the GIF file. Now under equivalent circum-
  49.         stances, the operation would proceed and the comment would be
  50.         removed by erasure (overwriting the text with spaces).
  51.  
  52.  
  53.         Features of The Scrolling Text Viewer
  54.  
  55.         1. The viewer is designed to work with a screen which is 80
  56.         columns wide. A variable number of screen lines is accommodated
  57.         however (the usual number of screen lines is 25).
  58.  
  59.         2. The viewer activates automatically if the total number of
  60.         display lines (including titles which GIF Commentor adds) of the
  61.         comment or comments requested for viewing is more than about
  62.         half a screenful.
  63.  
  64.         3. A bottom status line indicates line numbers displayed, keys
  65.         to move through the display and keys to activate the  Find text
  66.         and  Repeat find  features, and  Quit .
  67.  
  68.         4. Trailing blank lines in comments are not displayed, though a
  69.         single blank line after the final displayed comment is added for
  70.         appearance sake, if the display exceeds a screenful.
  71.  
  72.         5. The  Find text  feature does a simple case-insensitive search
  73.         for the text entered, beginning at the top of the current screen
  74.         and proceeding through to the document's end.
  75.  
  76.         6. The  Repeat find  feature searches from the last  Find text
  77.         instance found through to the document's end. If  Repeat find
  78.         is activated when no  Find text  has been  specified, the  Find
  79.         text  dialogue box is displayed.
  80.  
  81.         7. The scrolling text viewer's capacity is limited but its 700
  82.         line maximum should be enough to accommodate even the most
  83.         verbosely commented GIF file. A banner line announces if the
  84.         viewer capacity has been reached.
  85.  
  86.         8. Pressing  q  or the  Esc  key exits the viewer.
  87.  
  88.  
  89.  
  90.         WHAT IT DOES
  91.  
  92.         GIF Commentor's major functions may be summarised:
  93.  
  94.         * Scans a specified GIF file and reports the number of existing
  95.           comments. Scans the current directory and reports the number
  96.           of existing comments in all GIF files found.
  97.  
  98.         * Embeds specified text at the end of a GIF file, with or
  99.           without leading and/or trailing carriage-returns/line-feeds.
  100.           Embedded text becomes an integral part of the GIF file
  101.           according to the CompuServe GIF89a specification.
  102.  
  103.         * Enables viewing of the last comment, a specified comment or
  104.           all comments.
  105.  
  106.         * Enables extraction of the last or a specified comment to a
  107.           series of text files.
  108.  
  109.         * Enables removal (if safe) of the last comment in a GIF file by
  110.           truncation, or removal by erasure of any comment otherwise.
  111.  
  112.         * Enables making of a series of backups of a GIF file.
  113.  
  114.  
  115.         These and other associated utility functions also available, are
  116.         described fully in the following sections.
  117.  
  118.  
  119.  
  120.         HOW TO USE
  121.  
  122.         Run GC.EXE without any command line parameters to see the Usage
  123.         screen.
  124.  
  125.         Run  gc [GIF name]  without any other parameters to see if the
  126.         specified GIF file contains existing embedded comments. The
  127.         maximum number of comments handled is nine.
  128.  
  129.         Note that multiple command line parameters when used may occur
  130.         in any order on the command line.
  131.  
  132.         TO EMBED A COMMENT, there must be at least two command line
  133.         parameters present, one (and one only) GIF filename or name (eg.
  134.         test.gif or test) and EITHER one (and one only) text filename or
  135.         name (eg. abc.txt or abc) OR text in double quotes (eg. "Jupiter
  136.         and moons"). Maximum ["text"] allowable will vary according to
  137.         the length of what else is on the command line, but a full line
  138.         of text (80 characters) should usually be possible (on the
  139.         command line, ["text"] would need to wrap to the next line to
  140.         achieve a full line of text).
  141.  
  142.         eg. At a DOS prompt (eg. C:\GIF>, where C:\GIF contains the
  143.         relevant files), type:
  144.  
  145.         gc test abc     (and press Enter)
  146.  
  147.         gc test abc.txt     (and press Enter)
  148.  
  149.         gc test.gif "NGC2001 via "fixed" H.S.T."     (and press Enter)
  150.  
  151.         gc test "Artist's impression of major asteroid impacting Earth's
  152.          northern hemisphere (meteor.gif from JPL)"    (and press Enter)
  153.  
  154.         Note that if more than 2 sets of quote marks (") occur in text
  155.         on the command line, everything between the first and last set
  156.         will be taken as ["text"].
  157.  
  158.         If just the name of a text file is given (eg. abc), GIF
  159.         Commentor will attempt to open the file ABC. (ie. no extension);
  160.         if this fails, it will attempt to open ABC.TXT. If that also
  161.         fails, all execution will halt with a PROBLEM message. In this
  162.         case, the complete filename of the text file must be specified:
  163.  
  164.         eg. To embed XYZ.DOC in TEST.GIF, type:
  165.  
  166.         gc test xyz.doc     (and press Enter)
  167.  
  168.         Pathnames may also be used if desired.
  169.  
  170.         eg. While in C:\, one could type:
  171.  
  172.         gc c:\gif\test d:\docs\abc     (and press Enter)
  173.  
  174.  
  175.  
  176.         COMMAND LINE SWITCHES
  177.  
  178.         A series of operations specified through the use of a mixture of
  179.         switches will occur in the following order, regardless of how
  180.         the switches are arranged on the command line:
  181.  
  182.         1. Backup the specified GIF file
  183.         2a. View the last comment, a specified comment or all comments
  184.         2b. Extract the last or a specified comment to a text file
  185.         3. Remove the last or a specified comment
  186.         4. Cleanup the specified GIF file
  187.         5. Set GIF type
  188.         6. Embed text as a comment
  189.  
  190.         Operations on the last comment take precedence over operations
  191.         on other comments, except in the case where a request for the
  192.         last comment to be removed has been given (/r  or  /rx), in
  193.         which case all operations on the last comment will occur after
  194.         those on specified comments. Because of this, the order in which
  195.         View and Extract operations will occur will vary and in the
  196.         listing above they are given equivalent rank.
  197.  
  198.         The Last Comment is defined as being the comment nearest the GIF
  199.         file's end. Note that the Last Comment may always be operated
  200.         on, even if the GIF file contains more than nine comments. Where
  201.         a GIF file contains several comments, Comment #1 is closest to
  202.         the beginning of the file.
  203.  
  204.         If a View, Extract or Remove operation is specified on a comment
  205.         whose number exceeds the actual number of comments present, when
  206.         that request is reached all operation will halt with a PROBLEM
  207.         message.
  208.  
  209.         The number of valid combinations of switches is large (though
  210.         the number one would WANT to use is limited) and so hopefully
  211.         this order preempts what might be requested. It's obviously good
  212.         sense to make the Backup first, and it would make no sense to
  213.         embed a comment only to remove it immediately. It might make
  214.         sense to remove an existing comment and replace it with a new
  215.         one however. If all else fails, operations can always be done
  216.         one at a time.
  217.  
  218.  
  219.         /a - scan All GIF files in the current or a specified directory
  220.         and report the number of existing comments in each. Note that
  221.         this may NOT be done in conjunction with any other operation.
  222.  
  223.  
  224.         /b - make a Backup. The original GIF (eg. test.gif) is renamed
  225.         to TEST.BK[n] (n = 1 through 9, according to which files already
  226.         exist). TEST.BK[n] is copied to TEST.GIF using the internal DOS
  227.         copy command, with the verify switch.
  228.  
  229.         If all 9 backups already exist, all execution will halt and a
  230.         PROBLEM message will suggest that you delete at least one backup
  231.         file.  NO BACKUP is the default so, as common sense suggests,
  232.         you should keep original copies of valuable GIFs elsewhere.
  233.  
  234.         eg. To make a backup of TEST.GIF, type:
  235.  
  236.         gc test /b     (and press Enter)
  237.  
  238.  
  239.         /c - Cleanup the specified GIF file by removing extraneous 00h
  240.         bytes or end-of-file (EOF) markers (1Ah) which occur after the
  241.         GIF terminator (3Bh). Note that "Cleanup" automatically occurs
  242.         before embedding of a comment, so that while the switch may also
  243.         be specified then it is ignored as a separate process.
  244.  
  245.         GIF files obtained by downloading from BBSs or networks such as
  246.         InterNet sometimes contain such superfluous bytes.
  247.  
  248.         eg. To cleanup TEST.GIF, type:
  249.  
  250.         gc test /c     (and press Enter)
  251.  
  252.  
  253.         /e-  - prevents any carriage-return/line-feeds (CR-LFs) or
  254.         end-of-file (EOF) markers (1Ah) already present at the very End
  255.         of the specified text from being included in the embedded
  256.         comment. Many editors such as MS-DOS's EDIT add invisible CR-LF
  257.         bytes (0Dh 0Ah) to the end of any text file they generate. This
  258.         switch is automatically in effect if  /e[n]  (see following) is
  259.         specified, to ensure the desired number of CR-LFs at the end of
  260.         a comment.
  261.  
  262.         eg. To ensure no CR-LFs or EOF markers at the end of embedded
  263.         text, type:
  264.  
  265.         gc test /e-     (and press Enter)
  266.  
  267.  
  268.         /m - Marks the comment position in bytes when viewing a comment
  269.         by displaying it in brackets (eg. (@123678) ) in the comment
  270.         announcer. This can be useful when tracking down apparent
  271.         comment anomalies.
  272.  
  273.         eg. to mark the position of the last comment in TEST.GIF, type:
  274.  
  275.         gc test /v/m     (and press Enter)
  276.  
  277.  
  278.         /s[n] - add [n] (n = 1 through 9) carriage-returns/line-feeds
  279.         (CR-LFs) at the Start of the specified text.  /s  acts the same
  280.         as  /s1 .
  281.  
  282.         This is useful if you want to add another comment to a GIF which
  283.         already contains a comment, so that the comments are properly
  284.         separated. Note that some GIF viewers automatically display
  285.         distinct comments separately regardless of CR-LFs, some do not
  286.         (GIF Commentor automatically display comments separately). Only
  287.         one instance of  /s[n]  may be specified on any one occasion.
  288.  
  289.  
  290.         /e[n] - add [n] (n = 1 through 9) carriage-returns/line-feeds
  291.         (CR-LFs) at the End of the specified text.  /e  acts the same as
  292.         /e1 . Only one instance of  /e[n]  may be specified on any one
  293.         occasion.
  294.  
  295.         eg. To place two CR-LFs at both the start and the end of text
  296.         (as ABC.TXT) to be embedded in TEST.GIF, type:
  297.  
  298.         gc test abc /s2/e2     (and press Enter)
  299.  
  300.  
  301.         /r - Remove the last comment in the GIF file if the option to
  302.         proceed is chosen and if it is "safe" to do so  ie. if the
  303.         comment is separated from the GIF terminator (3Bh) by 00h bytes
  304.         only. If this is not the case, the last comment will be erased
  305.         instead ie. the text of the comment is overwritten with spaces.
  306.         The reason for such caution is that when comments are removed,
  307.         the file is TRUNCATED from the beginning of the comment block
  308.         onwards. Removing a comment at the very end of the GIF file will
  309.         do no harm to the graphic part (though the converse will also
  310.         almost always apply).
  311.  
  312.         Up to 255 characters of the comment found are displayed,
  313.         execution pauses and the options to proceed with removal or to
  314.         abort are given.
  315.  
  316.         The reason for providing an option which displays at least the
  317.         beginning of the comment is that comments can occur anywhere in
  318.         the GIF file between control and data blocks, but it is beyond
  319.         the scope of GIF Commentor to identify such blocks. So in
  320.         identifying a comment, it looks for the byte sequence 21h FEh,
  321.         then proceeds to check the comment for internal consistency,
  322.         according to the GIF89a specification.  It's possible though
  323.         uncommon, for a non-comment series of bytes (which will display
  324.         as a meaningless sequence of symbols) to be identified as a
  325.         comment.
  326.  
  327.         eg. To remove the last comment, then add a new comment
  328.         immediately afterwards, type:
  329.  
  330.         gc test /r "archie.au: /images/earth7.gif"
  331.  
  332.         (and press Enter, then  y )
  333.  
  334.         Note that if  abort  is chosen, all execution halts and the new
  335.         comment is not embedded.
  336.  
  337.  
  338.         /r[n] - Remove the nth comment in a GIF file, where n is 1
  339.         through 9 and is the number of the comment, if the option to
  340.         proceed is chosen. If the nth comment happens to be the last
  341.         comment, it will be removed by truncating the GIF file if "safe"
  342.         to do so, or by erasure otherwise (see notes for  /r  above),
  343.         again only if the option to proceed is chosen. Comments which
  344.         are not the last comment will be removed by erasure.
  345.  
  346.         Note that  /r1  is NOT the same as  /r  unless there is only one
  347.         comment present. Only one instance of  /r[n]  may be specified
  348.         on any one occasion.
  349.  
  350.  
  351.         /rx - Remove the last comment in the GIF file by TRUNCATION
  352.         without (eX) prompting, if it is "safe" to do so (notes as for
  353.         /r  apply).  NO option to abort is given and GIF Commentor
  354.         removes what it identifies as the last comment in the GIF file.
  355.         This is useful when you want to quickly remove a known comment
  356.         at the end of a GIF file. See also notes as for  /r  above.
  357.  
  358.         eg. To remove all bytes in TEST.GIF beyond and including the
  359.         last comment, type:
  360.  
  361.         gc test /rx     (and press Enter)
  362.  
  363.  
  364.         /v - View the last comment. If the total number of display lines
  365.         (including titles which GIF Commentor adds) is about half a
  366.         screenful, a static display is given (note that trailing blank
  367.         lines are not displayed), otherwise the scrolling text viewer
  368.         activates (see WHATS NEW section for a description of features).
  369.  
  370.         Normally carriage-returns and line-feeds occurs as CR-LF pairs,
  371.         so GIF Commentor interprets a line-feed (LF or 0Ah) unpaired
  372.         with a carriage-return (CR or 0Dh), or a CR unpaired with a LF,
  373.         as a CR-LF pair, to obviate overwriting of an existing line with
  374.         a subsequent one or improperly formatted text.  Should a
  375.         preexisting comment still display in a garbled but
  376.         semi-intelligible fashion, an exact (byte for byte) copy of the
  377.         comment may be obtained using the extract switch (see  /x or
  378.         /x[n]). It should be possible to remove (see  /r /rx  or /r[n]),
  379.         reformat (using a suitable text or binary editor) and reembed
  380.         that particular comment.
  381.  
  382.         eg. To view the last comment in TEST.GIF, type:
  383.  
  384.         gc test /v     (and press Enter)
  385.  
  386.  
  387.         /v[n] - View the nth comment, where n is 1 through 9 and is the
  388.         number of the comment. Notes as for  /v  apply.
  389.  
  390.         Note that  /v1  is NOT the same as  /v  unless there is only one
  391.         comment present. Only one instance of  /v[n]  may be specified
  392.         on any one occasion.
  393.  
  394.         eg. To view the 2nd comment in TEST.GIF, type:
  395.  
  396.         gc test /v2     (and press Enter)
  397.  
  398.  
  399.         /va - View All comments (up to a maximum of nine comments).
  400.         Notes as for  /v  apply.
  401.  
  402.         eg. To view all comments in TEST.GIF, type:
  403.  
  404.         gc test /va     (and press Enter)
  405.  
  406.  
  407.         /x - eXtract the last comment in the GIF file to a text file
  408.         with filename X[m].TXT (where is m is 1 through 9, according to
  409.         which backup files already exist). This feature can be useful if
  410.         you want a text file/hardcopy of an existing comment or wish to
  411.         modify an existing comment.
  412.  
  413.  
  414.         /x[n] - eXtract the nth comment in the GIF file to a text file
  415.         with filename X[m]#n.TXT, where m is as before, and n is 1
  416.         through 9 and is the number of the comment, comment #1 being
  417.         closest to the front of the file.  Thus X3#2.TXT is the 3rd
  418.         backup of comment #2. If however, there are say only 3 comments
  419.         present, the 3rd comment will be recognized as the last comment
  420.         and  /x3  will extract the 3rd comment to X[m].TXT.
  421.  
  422.         Note that  /x1  is NOT the same as  /x  unless there is only one
  423.         comment present. Only one instance of  /x[n]  may be specified
  424.         on any one occasion.
  425.  
  426.         eg. To extract the last comment in TEST.GIF to a file, type:
  427.  
  428.         gc test /x     (and press Enter)
  429.  
  430.         If all of X1.TXT through X9.TXT already exist, all execution will
  431.         halt and a PROBLEM message will suggest that you delete at least
  432.         one extraction file.
  433.  
  434.         eg. To extract the 2nd comment in TEST.GIF to a file, type:
  435.  
  436.         gc test /x2     (and press Enter).
  437.  
  438.         Similarly, if all of X1#2 through X9#2 exist, all execution will
  439.         halt with a PROBLEM message.
  440.  
  441.  
  442.         /t±  - embed the comment one byte after (/t+) or one byte before
  443.         (/t-) the GIF Terminator.  Usually a GIF terminates with the
  444.         byte sequence 00h 3Bh.  GIF Commentor normally embeds the
  445.         comment starting at 3Bh by changing it to 21h, the comment
  446.         identifier.  However experience shows that some GIF viewers are
  447.         sensitive to where comments start and in this case won't display
  448.         the comment.  Starting the comment one byte position after or
  449.         before 3Bh often solves this problem.
  450.  
  451.         eg. To use this feature when embedding a comment, type:
  452.  
  453.         gc test /t+ "Sunset on Mars"     (and press Enter)
  454.         OR
  455.         gc test /t- "Sunset on Mars"     (and press Enter)
  456.  
  457.  
  458.         /87 - set the GIF type to GIF87a. Useful if you need to change
  459.         the type to this.
  460.  
  461.         One very good use of this is if you want to use Rob van
  462.         Helmond's excellent utility GIFPALET.EXE (part of 6GIFUTL2.ZIP,
  463.         shareware), which changes a GIF's background colour. GIFPALET
  464.         works on GIF87a but not on GIF89a files, though seems to work OK
  465.         on the latter if the identifier bytes in the GIF header are
  466.         changed to GIF87a (which is what  /87  does). If the specified
  467.         GIF contains any comments, be sure to restore the GIF type to
  468.         GIF89a so that GIF viewers will still display its comments.
  469.  
  470.         Note that as officially only the GIF89a type supports comments,
  471.         GIF Commentor won't allow this switch to be used with a text
  472.         name/filename, ["text"], /e-, /s[n], /e[n], /v, /v[n], /va, /x,
  473.         /x[n], /t± or /89  ie. anything to do with embedding, viewing or
  474.         extracting a comment. GIF Commentor will however, view comments
  475.         in GIF files of either GIF87a or GIF89a type.
  476.  
  477.         eg. typing:
  478.  
  479.         gc test /b/87/ru     (and press Enter), will execute
  480.         gc test /87 descript.doc     (and press Enter), will abort
  481.  
  482.  
  483.         /89 - set the GIF type to GIF89a. Useful if you need to change
  484.         the type to this. See notes for  /87 .
  485.  
  486.         Note that the GIF type is automatically set to GIF89a during
  487.         embedding of a comment, so while the switch may be specified
  488.         then, it is ignored as a separate process.
  489.  
  490.         eg. To set the GIF type to GIF89a, type:
  491.  
  492.         gc test /89     (and press Enter)
  493.  
  494.  
  495.  
  496.         DOGMA
  497.  
  498.         This program is distributed as Shareware. While all due care has
  499.         been taken in the construction of this program, if you choose to
  500.         use it, you do so entirely at your own risk and NO liability
  501.         will be accepted by the author for consequent loss or damage of
  502.         any kind.
  503.  
  504.         Individuals may use GIF Commentor for their own private (non-
  505.         commercial) purposes gratis  ie. for no charge. However, if you
  506.         use the program, please send an E-mail message with constructive
  507.         comments to:
  508.  
  509.         psjrl@wombat.newcastle.edu.au  (InterNet)
  510.  
  511.         Businesses or anyone anticipating any commercial use of GIF
  512.         Commentor MUST obtain prior written permission by contacting:
  513.  
  514.         SoftView, P.O. Box 35, Cooranbong 2265, N.S.W., Australia.
  515.  
  516.