home *** CD-ROM | disk | FTP | other *** search
/ HTML - Publishing on the Internet / html_cdrom.iso / tools / html / linux / check / htmlsrpl.man < prev    next >
Text File  |  1995-02-21  |  11KB  |  218 lines
  1. htmlsrpl version 1.11, January 22 1995
  2.  
  3. Name:
  4.  
  5.      htmlsrpl.pl - HTML-aware search-and-replace program, with
  6.      either literal strings or regular expressions.  Acts either
  7.      only outside HTML/SGML tags, or only within tags; can be
  8.      restricted to operate only within and/or only outside
  9.      specified elements; can also upper-case tag names.  Runs
  10.      under perl.
  11.  
  12.  
  13. Typical use:
  14.  
  15.    perl htmlsrpl.pl [options] infile.html > outfile.html
  16.  
  17.   Where command-line options have the form "option=value" (without whitespace
  18.   on either side of the `=' character), and all options should precede
  19.   filename arguments on the command line.
  20.  
  21.  
  22. Basic command-line options:
  23.  
  24.   old="..."         String or expression to be replaced.  Must be defined and
  25.                 non-null (unless the upcase=1 option is specified).
  26.  
  27.   new="..."         The new replacement string or expression.  If ``new='' is
  28.                 absent or null, the old="..." string is deleted.
  29.  
  30.   intags=1          If this option is specified on the command line, strings
  31.                 within tags are changed, but not text outside of tags.  (The
  32.                 default action, if this option is absent, is to only replace
  33.                 text outside of tags.)
  34.  
  35.  
  36. Element inclusion/exclusion command-line options:
  37.  
  38.   inside=...        The value of this option is a tagname or a comma-separated
  39.                 list of tagnames (e.g. inside=A or inside=b,i).  Search and
  40.                 replace operations will only take place in material that is
  41.                 contained within all the specified elements.  So if inside=b,i
  42.                 has been specified on the command line, only "Text3" in the
  43.                 following input file would be subject to search and replace:
  44.                 "Text1<B>Text2<I>Text3</I></B>".  The order of inclusion makes
  45.                 no difference (so that <B> nested inside <I> would be treated
  46.                 exactly the same as <I> nested inside <B>).
  47.  
  48.  
  49.   outside=...       Search and replace will only take place outside the tag or
  50.                 (comma-separated) list of tags specified with this option.  So
  51.                 if outside=b,i is specified, nothing contained within a
  52.                 <B>...</B> or <I>...</I> element will be subject to search and
  53.                 replace.
  54.  
  55.   inmost=...        The same as inside=, except that search and replace only
  56.                 occurs _immediately_ within the element specified (i.e.
  57.                 inmost=b would mean that only "Text2" would be subject to
  58.                 search and replace in "Text1<B>Text2<I>Text3</I></B>").
  59.  
  60.    If more than one of these options is specified, search-and-replace only
  61.   takes place when all the conditions specified in the options are satisfied.
  62.  
  63.    This program uses a rather simple-minded algorithm for determining what
  64.   is contained within an element.  There is a small list of known non-pairing
  65.   tags (such as <IMG>, <BR>, etc.).  When any opening tag not on this list is
  66.   encountered, it is pushed onto a stack of presently-containing elements.
  67.   When any closing tag is encountered, the most-recently occurring matching
  68.   tagname is removed from the stack, along with everything above it in the
  69.   stack (if no matching opening tag has been encountered, htmlsrpl.pl exits
  70.   with an error -- use the htmlchek program in this package to help find the
  71.   HTML error).  This means, for example, that a <P> element unclosed by a </P>
  72.   will often be considered to extend much farther than it should according
  73.   to the HTML DTD; also, in a list such as "<DL><DT>Text1<DD>Text2</DL>",
  74.   "Text2" is actually considered to be contained within a <DT> element.
  75.  
  76.    Note that when the inside=, inmost=, or outside= options are used
  77.   together with the intags=1 option, a tag is never considered to be
  78.   contained within the element which it itself delimits (i.e. the inclusion
  79.   and exclusion relationships established by a tag come into force at the end
  80.   of the tag if it is an opening tag, and at the beginning of the tag if it
  81.   is a closing tag).  Also, inclusions and exclusions are always calculated
  82.   from the unprocessed input, before any search and replace has taken place.
  83.  
  84.  
  85. Regexp command-line options:
  86.  
  87.   regexp=1          If this option is specified, old="..." is used as a Perl
  88.                  regular expression, rather than as a simple literal string
  89.                  (the default is that both old="..." and new="..." are handled
  90.                  as simple literal strings).  See the Perl documentation for
  91.                  information on regular expressions.  Special characters that
  92.                  are shell metacharacters will have to be quoted on the
  93.                  command line, to protect them from interpretation by the
  94.                  shell.  The `/' character should be escaped by a preceding
  95.                  backslash, or should be written as "\057", since this
  96.                  character is used as the delimiter in the Perl s/.../.../
  97.                  construct.
  98.  
  99.   regeval=1         If this option is specified, old="..." is used as a
  100.                  regular expression, and new="..." is a statement to be
  101.                  evaluated, as in the Perl s/.../statement/e construct.
  102.                  Special variables such as $`, $&, $', $1 etc. can be used as
  103.                  part of such a statement (remember that the "." operator is
  104.                  used to concatenate string values).  If you use an erroneous
  105.                  expression, you will get a Perl errormessage (not a htmlsrpl
  106.                  errormessage), which you will have to interpret using the Perl
  107.                  manual.
  108.  
  109.   case=1            If this option is specified along with the regexp=1,
  110.                  regeval=1, or delete=1 options, then they operate without
  111.                  caring about alphabetic case.
  112.  
  113.  
  114. Command-line options that affect what is matched against:
  115.  
  116.  
  117.   lines=1           If this option is specified, the chunks of the input file
  118.                  that will be individually searched and replaced are those
  119.                  that result when tag beginnings (`<') and tag endings (`>')
  120.                  are boundaries; these chunks can contain embedded newlines.
  121.                  (Remember that in Perl the regexp /./ does not match newline
  122.                  ("\n"); you can use [^\000] instead.)
  123.                      If the lines=1 option is not specified, then the default
  124.                  behavior is that linebreaks are also boundaries; the chunks
  125.                  then do not contain newlines.  The `<' and `>' characters
  126.                  themselves are never part of the chunks matched against (they
  127.                  can only be altered by use of the delete=1 option), except
  128.                  for `>' characters outside of tags, which are treated as
  129.                  ordinary text.
  130.  
  131.   slash=1           If this option is specified, then the `/' slash character
  132.                  immediately following the `<' character of a closing tag is
  133.                  not matched against, and is not affected by any search-and-
  134.                  replace operation (except, of course, tag deletion with
  135.                  delete=1).  Implies intags=1.
  136.  
  137.   delete=1          If this option is specified, old="..." is treated as a
  138.                 regexp and is matched against tagnames (not against the entire
  139.                 contents of tags); where tagnames match, the entire tag,
  140.                 including the surrounding `<' and `>' characters, is deleted.
  141.                 This option implies intags=1 and slash=1, and is incompatible
  142.                 with regexp=1, regeval=1, or a non-null value of new=.
  143.  
  144.  
  145. Uppercasing option:
  146.  
  147.   upcase=1          If this option is present, then tag names (the sequence of
  148.                  non-whitespace immediately following a `<' character) are
  149.                  upper-cased.  Does not upper-case tag options (attributes).
  150.                  If old= is null or absent, then this is the only thing that
  151.                  htmlsrpl.pl does, and any other command-line options are
  152.                  ignored.  Otherwise, uppercasing is done first, before any
  153.                  specified search-and-replace operation (and the intags=1
  154.                  option is assumed).  Note that qualifiers like `inmost=' will
  155.                  govern the scope of any search-and-replace operation that
  156.                  accompanies uppercasing, but uppercasing itself always
  157.                  affects all tags.
  158.  
  159.  
  160. Final status message:
  161.  
  162.   At the end of processing, if no errors occurred, htmlsrpl.pl outputs a
  163.   message to STDERR (either "Changed!" or "Unchanged"), informing whether
  164.   or not any substitutions were actually performed on the output.
  165.  
  166.  
  167. Summary:
  168.  
  169.   You can do some cute things by playing around with these options.  For
  170.   example, ``perl htmlsrpl.pl regexp=1 old=".*"'' deletes all text (except
  171.   newlines) outside tags, while adding ``intags=1'' to this command line means
  172.   that all text inside tags is deleted instead (leaving ghostly ``<>'' markers
  173.   behind).  The command line ``perl htmlsrpl.pl delete=1 case=1 old="blink"''
  174.   nukes any <BLINK> tags (yay!), while ``perl htmlsrpl.pl slash=1 case=1
  175.   lines=1 regexp=1 old="^blink[^\000]*" new="I"'' will change all BLINK tags,
  176.   with accompanying attributes (possibly on multiple lines), and replace them
  177.   with the appropriate opening <I> and closing </I> tags.  A command like ``perl
  178.   htmlsrpl.pl outside=cite,h1,h2,h3,h4,h5,h6,title old="Pride and Prejudice"
  179.   new="<cite>Pride and Prejudice</cite>"'' can be used to add mark-up in the
  180.   appropriate places.
  181.  
  182.  
  183. Limitations:
  184.  
  185.   A limitation of this program is that it always treats `<' and `>' in the
  186.   input file as tag-beginning and tag-ending characters (even in comments),
  187.   and terminates prematurely if `<' and `>' are found in inappropriate places
  188.   (except that loose `>' characters outside tags are harmless).  In this case
  189.   a "die" message will be output to STDERR, and the last line of the output
  190.   will be "ERROR!".
  191.  
  192.   If you misspell an option name, then you'll either get an error when Perl
  193.   tries to open a file with that name, or you'll get an indiscriminate
  194.   "No `old=' string was specified" errormessage.
  195.  
  196.   The program processes all files on the command line to STDOUT; to process a
  197.   number of files individually, use the iteration mechanism of your shell; for
  198.   example:
  199.  
  200.  for a in *.html ; do perl htmlsrpl.pl old=ABC new=XYZ $a > otherdir/$a ; done
  201.  
  202.   in Unix sh, or:
  203.  
  204.  for %a in (*.htm) do call htmlsrpl %a otherdir\%a
  205.  
  206.   in MS-DOS, where htmlsrpl.bat is the following one-line batch file:
  207.  
  208.  perl htmlsrpl.pl old=ABC new=XYZ %1 > %2
  209.  
  210.  
  211. Author:
  212.  
  213.   Copyright H. Churchyard 1994, 1995 -- freely redistributable.  This code is
  214.   functional but not very well commented or aesthetic -- sorry!  If you find
  215.   an error in this program,  e-mail me at churchh@uts.cc.utexas.edu.
  216.  
  217. htmlsrpl version 1.11, January 22 1995
  218.