
                          XML HRC Pack
                            Ver. 1.04

               Copyright (c) Alexander Gutman; 2001
                  Email: gutman@novosoft-us.com

        A pack of HRC files for coloring XML and XSL syntax
                in  Colorer 4ever (c) Cail Lomecb
                for FAR Manager (c) Eugene Roshal


 1. General description

    XML: The pack recognizes XML elements (with embedding taken into
         account) and their attributes, namespace prefixes and their
         declarations, special attributes xml:space and xml:lang,
         entity references, and, of course, comments, CDATA sections,
         processing instructions and document type definitions (DTD).

         The pack is rather sensitive to syntax violation.
         For instance, it recognizes such a "trifle" as
         an erroneous value of an xml:space attribute.

    XSL: The pack recognizes all known XSL elements and their
         attributes, as well as FO elements names.

         For each attribute of any XSL element, the pack recognizes
         the syntax of the value specific for this particular
         attribute (XPath/XSLT expression, QName, NCName, etc.).

         The pack recognizes attribute value templates, doing this
         only where the latter are admissible.

         In XPath/XSLT expressions, the pack recognizes node tests,
         axes, string constants, predicates and functions
         (with brackets matching and embedding taken into account),
         variables, relations and operations, etc.;
         in short, all known syntax constructions are recognized.

         Almost any error in the name of an element or attribute
         or a syntax error in a typed value of a standard attribute
         or in an XPath/XSLT expression implies either coloring
         violation or specially stipulated error highlighting.

    The pack includes a hundred of customizable color regions
    (see "xml_colors.hrc"). For instance, regions are provided
    therein for color highlighting of individual fragments
    of closing tags, etc.; down to, say, a "$" sign in a variable
    reference.

    There are 15 regions whose tuning makes it possible to regulate
    the packet's sensitivity to various erroneous situations.

    Tuning the type regions for comments and XSLT templates makes
    it possible to include the latter into the list of functions
    produced by Plugin commands -> Colorer -> List functions.

    A special "xmlCustom" scheme makes it possible to include color
    highlighting of personal "temporary" marks (e.g., "?!").

    For a detailed description of all customizable regions, see
    "xml_colors.txt".


 2. Installation instructions

    (a) In the "Far\Plugins\Colorer\hrc\xml" folder create
        a subfolder named "xpack" and copy into it either
        the entire pack content or only its HRC files "xml.hrc",
        "xml_colors.hrc", "xsl.hrc", and "xsl_elements.hrc".

    (b) In the Colorer base file you use
        ("Far\Plugins\Colorer\hrc\colorer.hrc" by default)
        change two lines: replace

          <load name="xml/xml.hrc"/>
          <load name="xml/xsl.hrc"/>

        with the respective lines

          <load name="xml/xpack/xml.hrc"/>
          <load name="xml/xpack/xsl.hrc"/>

        These lines are situated in elements <type descr="xml" ...>
        and <type descr="xsl" ...> respectively.

    (c) If you performed (a) and (b) in FAR, to make sure, reload
        Colorer or just close and reopen FAR. (This is necessary,
        for instance, in the case when you edited a hard link to
        the base file situated outside the Colorer folder system.)

    (d) Load any XML (or better XSL) file into the FAR internal
        editor and make sure that the syntax highlighting has
        changed beyond recognition.

    (e) Having been scared of an absurd colors combination,
        load the "xml_colors.hrc" file into an editor and, looking
        into "xml_colors.txt", change the color settings according
        to your taste.


 3. Customization and utilization hints

    * Certainly, the original color settings will not suit you
      and the presentation will look too many-colored.
      This is so because, first, the settings just reflect
      the author's taste and, second, they are based on your
      personal settings in the Colorer assigns file
      ("Far\Plugins\Colorer\hrd\console\default.hrd" by default)
      which, for sure, are different from those of the author.

      All the color settings of the packet are placed in a separate
      file, "xml_colors.hrc". Experiment on them and you will
      certainly find a suitable colors combination.

    * You will probably wish to turn off some color settings.
      The simplest way of doing this is just deleting the
      corresponding lines in "xml_colors.hrc". Nevertheless,
      instead of deleting lines, better comment them out
      (with "<!--" and "-->") in case you will want to turn
      them on again.

    * Do not turn off the settings for erroneous situations and keep
      their values equal to "dError" if you want Colorer to
      thoroughly follow the W3C recommendations built in the packet.
      Remember that the list of detected errors can be obtained by
      Plugin commands -> Colorer -> Find errors.

    * Bear in mind that turning off or changing certain color
      settings sometimes implies changing of some other settings,
      because "xml_colors.hrc" contains cross-references.

    * Make an effort to define the values for the "xmlAttrValue"
      and "xslXPath" settings so that they have different background
      color. This will allow you to easily distinguish simple string
      values from XPath/XSLT expressions.

    * The pack uses a rather complicated set of schemes, which may
      adversely affect the coloring speed. Unfortunately, simple
      turning off settings in "xml_colors.hrc" does not increase
      the speed.

      You can slightly increase the coloring speed by modifying
      the "xsl_elements.hrc" file. However, it is not worth editing
      this file explicitly. Do the following instead:

        (a) Go into the "generator" subfolder of the pack.

        (b) Create a backup copy of "xsl_elements.xml"
            (name it, say, "xsl_elements.old.xml").

        (c) Modify the "xsl_elements.xml" file.

        (d) Run "generate_hrc.bat" and thus create a new
            "xsl_elements.hrc" file in the same folder.

        (e) Move the newly created "xsl_elements.hrc" file
            into "Far\Plugins\Colorer\hrc\xml\xpack",
            replacing the old file therein.

        (f) To make sure, reload Colorer or reopen FAR.

      The "xsl_elements.xml" file situated in the "generator" folder
      of the pack reflects the XSLT 1.0 specification (W3C
      Recommendation; http://www.w3.org/TR/1999/REC-xslt-19991116).
      It contains a list of XSLT elements and their registered
      attributes. The value of each attribute in the file
      is the name of the corresponding type of values
      ("Expr", "QName", etc.).

      Deletion of a subnode of the document element <elements>
      makes the corresponding XSL element an unknown (erroneous)
      XSL element; therefore it is not worth deleting any subnodes.
      It is deletion of attributes (rather than nodes) which affects
      the coloring speed: deletion of an attribute makes it an
      unknown attribute, thus turning off the corresponding analysis
      of its value.

      Change the value of the "xslErrAttrName" region (which is
      "dError" by default) so that the attributes you deleted
      be not recognized as erroneous.

    * Use syntax highlighting as an analog of an XSLT reference.
      For instance, if you want to find out whether attribute value
      templates (AVTs) are allowed within the value of a certain
      attribute, just type a pair a braces "{}" in it and look at
      the color of this construction: if it changes to the color of
      an expression, AVTs are allowed here, otherwise they are not.

    * If you have got any remarks or suggestions concerning
      XML HRC Pack, contact the author (Alexander Gutman,
      gutman@novosoft-us.com). Probably, this is not the last
      version of the pack, and your wishes will be taken into
      account in the next version.
