#***********************************************************************************************************************
# DMTF - Distributed Management Task Force, Inc. - http://www.dmtf.org
#
# dsp2023_<vers>_readme.txt - part of the DMTF DSP2023 zip archive.
#
# This readme file provides the document information for DMTF document DSP2023.
#
# Release URLs (once DMTF Standard):
# http://www.dmtf.org/standards/published_documents/dsp2023_1.0.1.zip
# http://www.dmtf.org/standards/published_documents/dsp2023_1.0.zip
#
# Date: 2012-08-19
# Version: 1.0.1
# Document status: DMTF Standard
#
# Title: XML Management Profile Samples
#
# Document type: Informational
# Document language: en-US
#
# Copyright notice:
# Copyright (C) 2008-2012 Distributed Management Task Force, Inc.  (DMTF).  All rights reserved.
# DMTF is a not-for-profit association of industry members dedicated to promoting enterprise and systems management and
# interoperability.  Members and non-members may reproduce DMTF specifications and documents for uses consistent with
# this purpose, provided that correct attribution is given.  As DMTF specifications may be revised from time to time,
# the particular version and release date should always be noted.
# Implementation of certain elements of this standard or proposed standard may be subject to third party patent rights,
# including provisional patent rights (herein "patent rights").  DMTF makes no representations to users of the standard
# as to the existence of such rights, and is not responsible to recognize, disclose, or identify any or all such third
# party patent right, owners or claimants, nor for any incomplete or inaccurate identification or disclosure of such
# rights, owners or claimants.  DMTF shall have no liability to any party, in any manner or circumstance, under any
# legal theory whatsoever, for failure to recognize, disclose, or identify any such third party patent rights, or for
# such party's reliance on the standard or incorporation thereof in its product, protocols or testing procedures.  DMTF
# shall have no liability to any party implementing such standard, whether such implementation is foreseeable or not,
# nor to any patent owner or claimant, and shall have no liability or responsibility for costs or losses incurred if a
# standard is withdrawn or modified after publication, and shall be indemnified and held harmless by any party
# implementing the standard from any and all claims of infringement by a patent owner for such implementations.
# For information about patents held by third-parties which have notified the DMTF that, in their opinion, such patent
# may relate to or impact implementations of DMTF standards, visit http://www.dmtf.org/about/policies/disclosures.php.
#
# Foreword:
# This document was prepared by the DMTF Architecture Working Group. DMTF is a not-for-profit association of
# industry members dedicated to promoting enterprise and systems management and interoperability. For information about
# the DMTF, see http://www.dmtf.org.
#
# Acknowledgments:
# The DMTF acknowledges the following individuals for their contributions to this document:
# * Andreas Maier, IBM (editor)
# * Michael Johanssen, IBM
# * Bob Blair, AMD
# * George Ericson, EMC
# * Steve Hand, Symantec
#
# Introduction:
# The DSP2023 ZIP file provides sample profiles and a sample build infrastructure for XML-based management profiles
# defined using the XML format described in DSP8028 (so called "machine readable profiles", MRP).
# This readme file describes the content of the DSP2023 ZIP file.
#
# Change log:
# 0.9.1  - 2008-11-06 - Released as a first Work in Progress.
# 0.9.3  - 2009-05-31 - Released as a second Work in Progress.
# 1.0.0a - 2010-03-16 - Released as a third Work in Progress.
# 1.0.0b - 2010-05-31 - Released as a fourth Work in Progress.
# 1.0.0c - 2011-02-22 - Released as a fifth Work in Progress.
# 1.0.0d - 2011-06-21 - Released as a sixth Work in Progress.
# 1.0.0e - 2011-08-16 - Released as a seventh Work in Progress.
# 1.0.0f - 2011-09-13 - Released as a Work in Progress.
# 1.0.0g - 2011-09-13 - Member review of Draft Standard.
# 1.0.0  - 2012-03-19 - Released as DMTF Standard.
# 1.0.1  - 2012-08-19 - Released as DMTF Standard, with the following changes:
# - Added description for using Eclipse or IBM Rational Software Architect for editing MRP XML.
# - Simplified the MRP XML to HTML conversion by providing a mrp2html.py Python script, and removing the files that
#   were used by the more complicated procedure in V1.0.0:  bin/xalan.bat, bin/CatalogManager.properties,
#   profiles/resources/embed-file.awk and profiles/resources/embed-css-file.awk.
# - Picked up dsp8028_1.0.1.xsd and dsp8029_1.0.1.xsl.
#***********************************************************************************************************************


1. Content of the DSP2023 ZIP file:

  The DSP2023 ZIP file contains samples of Machine Readable Profiles (MRP).  In addition, it contains everything that is
  needed for developing your own profiles in the MRP format, except for tools and CIM schema files.

  Directory structure within the DSP2023 ZIP file:

       +                            Root directory
       |
       +-- profiles                 Subtree for MRP profiles; contains a makefile and is the CWD for running make.
       |   +-- xmp1000              Sample profile xmp1000 (for details on files in that directory, see below)
       |   +-- xmp1009              ...
       |   +-- xmp1011              ...
       |   +-- xmp1013              ...
       |   +-- xmp1033              ...
       |   +-- xmp1999              ...
       |   +-- resources            Files referenced by MRP profiles (that cannot be redirected via XML Catalog).
       |       +-- cim-xml          Place for CIM-XML files of CIM Schema (not included in DSP2023).
       |
       +-- localcopy                Local copy of files on the web, redirected to by an XML Catalog.
       |
       +-- bin                      Files related to build tools

  Files in the profile subdirectories (e.g. profiles/xmp1000):

    xmp<dspn>_<vers>.mrp.xml        Sample MRP XML files (that is, MRP profiles).

                                    These files are sample management profiles in the Machine Readable Profiles (MRP)
                                    XML format defined by DSP8028.xsd. Unless otherwise noted in design notes
                                    within these sample profiles, these sample profiles represent the functionality of
                                    the corresponding DSP<dspn> profiles with the same version number.

                                    The sample profiles are:

                                      XMP1000 - MRP profile template.
                                                Use this for new MRP profiles.

                                      XMP1009 - MRP version of DSP1009 (Sensors Profile).
                                                Demonstrates how to centralize boilerplate text into DSPmrpo (MRP
                                                Organization Message Registry).
                                                Demonstrates the use of collaborations in diagrams.

                                      XMP1011 - MRP version of DSP1011 (Physical Asset Profile).
                                                Demonstrates how to use abstract base adaptations.

                                      XMP1013 - MRP version of DSP1013 (Fan Profile).
                                                Demonstrates how to define indications.

                                      XMP1033 - MRP version of DSP1033 (Profile Registration Profile).
                                                Demonstrates nothing in particular, but is meant to be the starting
                                                point for transitioning DSP1033 to MRP format.

                                      XMP1999 - Sample glossary in MRP format.

    xmp<dspn>_<vers>.html           Sample HTML output files.

                                    These files have been created from the sample MRP XML files using the HTML build
                                    process described in 3.d).  These files are standalone and can be viewed with a Web
                                    browser as described in 3.a).

    xmp<dspn>_<vers>_<figname>.gif  Sample picture files.

                                    These files are figures used by the sample MRP XML files.  They have been created by
                                    Visio by saving the corresponding sheet in the Visio source file as GIF.
                                    The GIF files have been saved with 240 dpi resolution (source size does not matter).

    xmp<dspn>_<vers>.vsd            Sample Visio source files.

                                    These Visio diagrams have been created based on the Visio source files of the
                                    original DSP<dspn> profiles.  They have been adjusted in some cases to become
                                    collaboration structure diagrams, as defined by DSP1001 (PUG) 1.1.


2. Preparation:

   This section describes the preparation steps for certain tasks. Depending on how much you want to do with
   MRP, you can perform less than all of these steps.

   a) Unpack this archive (the DSP2023 ZIP file) into an empty directory.

      Note:  This unpacking step is required for the MRP XML and HTML output files to be able to find the right figure
      files.  Opening an MRP XML file directly from within the archive without unpacking it typically results in an
      incorrect display of these files.  The HTML output files can be opened directly from the archive, because they are
      standalone.

   b) For viewing the sample MRP XML files in a Web browser (see also 3.b), this additional preparation is needed:

      1) Download the CIM-XML files used by the sample profiles into profiles/resources/cim-xml, within the unpack
         directory from the previous preparation step.

           Local CIM-XML files                               Description

           profiles/resources/cim-xml/CIM/2.10/CIM_*.xml     CIM Schema 2.10.u final
           profiles/resources/cim-xml/CIM/2.19/CIM_*.xml     CIM Schema 2.19.u final
           profiles/resources/cim-xml/CIM/2.19+/CIM_*.xml    CIM Schema 2.19.u experimental
           profiles/resources/cim-xml/CIM/2.22+/CIM_*.xml    CIM Schema 2.22.u experimental

         The .u in the description is the latest published update version of a schema release.  The update version does
         not show up in the directory names.  The CIM_*.xml files are the CIM-XML files with a single CIM class in each
         file.

         If you want to change the location of the local copy of the CIM-XML files, this can be customized either in the
         DSP8029 XSLT stylesheet (profiles/resources/dsp8029_*.xsl, global parameter "cim-xml-root-url"), or better in
         the scripts that invoke the XSLT processor.

         There are multiple options for obtaining these CIM-XML files:

           1. Download the CIM-XML ZIP files in the CIM-XML folder of the MRP area of the Architecture WG.  These ZIP
              files already have the required directory structure inside, but they may not always be available for the
              latest CIM Schema releases.  This is the most convenient option, but works for DMTF members only.

              Link to that CIM-XML folder:

              http://members.dmtf.org/apps/org/workgroup/technical/dmtf-arch/documents.php?folder_id=1521

           2. Download the ZIP files with the individual XML classes on the CIM Schema download page of the desired CIM
              Schema releases.  You have to establish the required subdirectory structure yourself.

              Link to the CIM Schema download page:

              http://www.dmtf.org/standards/cim

              Note:  You need to download the ZIP archive of individual XML classes, for example:
              cim_schema_2.29.0Final-XMLClasses.zip

           3. Download the individual CIM-XML files from their publication space, using WinHTTrack or a similar offline
              copy tool.  The subdirectory structure on their publication space is as required for the local copy.  At
              this point, their publication space only contains CIM Schema 2.29 and above:

              http://schemas.dmtf.org/wbem/cim-xml/2.2.0/cim-schema

      2) Make sure you use a Web browser that works with MRP:

         The following Web browsers have been tested with MRP XML files and MRP HTML files:

           Firefox 5.0           1)
           Opera 11
           Safari 5
           Google Chrome 12      2)
           Internet Explorer 8   3)  4)  5)

         Setup requirements:

           1) Firefox requires a particular setting to permit the use of the parent directory ("..") in relative URIs
              used in xml-stylesheet processing instructions:  "security.fileuri.strict_origin_policy" must be "false"
              in about:config. For details about this setting, see
              http://kb.mozillazine.org/Security.fileuri.strict_origin_policy. Support for the use of parent directories
              can be tested by opening one of the sample .mrp.xml files with the web browser.  If the web browser does
              not support the use of parent directories, it will ignore the xml-stylesheet processing instruction in the
              sample .mrp.xml files, and the displayed file then appears to miss a lot of text that would otherwise be
              inserted by the DSP8029 XSLT, including a properly looking document title page.

         Restrictions:

           2) Google Chrome 12 displays the generated MRP HTML files correctly, but does not dynamically convert the MRP
              XML files to HTML at all.

           3) Internet Explorer 8 does not support CSS counters and "content" attributes.  Therefore, it does not
              display heading numbers in headings, table numbers in table captions, and figure numbers in figure
              captions.

           4) Internet Explorer 8 has a size limit of 32 kB for Data URIs.  It truncates images after that.  Internet
              Explorer 9 has lifted that limit to 4 GB, see
              http://blogs.msdn.com/b/ieinternals/archive/2010/09/15/ie9-beta-minor-change-list.aspx

           5) Internet Explorer 8 does not support the Javascript used to dynamically create the table of contents,
              table of figures and table of tables in the generated HTML.  It therefore displays the dummy text "[Insert
              table of <toc-type> here ..." instead of the generated tables.


   c) For editing the sample MRP XML files in an XML editor (item 3.c), this additional preparation is needed:

      1) Establish the localcopy/catalog.xml file as an XML Catalog for your XML editor.

         The following list describes how to do that, for a selected set of XML editors:

         - Altova XMLSpy:
           Add a line such as:
             <nextCatalog catalog="file:///C:/..../localcopy/catalog.xml"/>
           at the end of its RootCatalog.xml file.  Make sure that "file:" is used in that URL (Xalan-J has issues
           without it) and that three shlashes are used after that (XMLSpy has issues when just one slash is used).  On
           Windows, use forward slashes as path delimiters.

         - Eclipse (V4) or IBM Rational Software Architect (V8):
           Open the XML Catalog settings dialog via Window -> Preferences, select XML -> XML Catalog and add a new entry
           of type "Next Catalog" for the localcopy/catalog.xml file.

         This can be tested by opening one of the sample .mrp.xml files with your XML Editor without having an Internet
         connection.  A properly established XML Catalog will redirect the remote schema locations of .xsd files in that
         .mrp.xml file to local copies in the localcopy directory and will cause the XML Editor to report no errors
         about missing .xsd files.

         Note: Web browsers typically do not support XML Catalog lookup.

      2) Eclipse or RSA:

         Create a project of any type with a project directory that is the unpack directory from step 2. a).
         The unpack directory can also be further down in the subtree of the project directory, but this description
         assumes it is directly in the project directory.


   d) For converting the sample MRP XML files to HTML output files and further to PDF output files (item 3.d), this
      additional preparation is needed:

      1) Have Python installed and in the PATH:

           python 2.6 or 2.7                          http://python.org

      2) Install the Prince-XML PDF generator.
         The samples have been tested with the free edition of Prince-XML Version 8.0.

           Prince-XML 8.0                             http://www.princexml.com/

         The free edition of Prince-XML is fully functional, but generates a small Prince logo on the title page.
         Note that using Prince-XML is only one way of generating PDF files from HTML files.

      3) Only when using a make-based build environment:

         3.a) Have the commands available in the PATH that are described in the files ./makefile and profiles/makefile.
              They can be made available by installing the following packages:

                CygWin 1.7 (or higher)                     http://cygwin.com/install.html

         3.b) Customize the bin/prince-xml.bat script from DSP2023 for your installation path of Prince-XML.

         3.c) Add the bin directory from DSP2023 to your PATH environment variable.

         At this point, a make-based build environment has been established.

         The build environment can be tested by running "make clean build" in the profiles directory.  If no error
         messages are displayed (besides the few intentional "Profile Error" messages issued by DSP8029), and if the
         HTML and PDF files for the sample profiles are generated in their respective subdirectories, the build
         environment works.

         The makefile in the profiles directory has a default target "help" which prints information about the available
         make targets.

      4) Only when using an Eclipse or RSA based build environment:

         4.a) Register the ant script bin/mrpbuild.ant as an external tool in Eclipse or RSA:

         - Click menu Run -> External Tools -> External Tools Configurations
         - Right click on "Ant Build" and enter information as follows:
           Name: mrpbuild
           Buildfile: ${workspace_loc:/bin/mrpbuild.ant}
           Base Directory: (empty)
           Arguments: -Dmrp.xml=${selected_resource_loc}
           Set an Input handler: Checked

         4.b) Edit the properties file of the ant script, bin/mrpbuild.ant.properties, and customize
              any property values as needed.

         To test the ant build script, select one of the sample .mrp.xml files unpacked from DSP2023, and click menu Run
         -> External Tools -> mrpbuild

         This executes the mrpbuild.ant script, which creates a .html file and a .pdf file for the selected .mrp.xml
         file in the directory of the selected .mrp.xml file.


3. How to use the sample profiles:

   a) View the sample HTML output files in a Web browser.

      The sample HTML output files represent a human-readable format of the XML management profiles.

      View them by simply opening them (for example, xmp1009_<vers>.html) using your favorite Web browser.

      These HTML files have been generated from the corresponding MRP XML files as described in step d) below.  They are
      basically a static view of what step b) displays dynamically.  The default way to generate the HTML files causes
      the picture files, the DSP8054 CSS stylesheet, and Javascript code that creates the tables of contents, to be
      embedded into the HTML file so that it has no external dependencies.

      Prerequisites:
      - Preparation step 2.a)
      - Your favorite Web browser.


   b) View the sample MRP XML files in a Web browser.

      The sample MRP XML files represent the actual machine readable profiles.

      View them by simply opening them (for example, xmp1009_<vers>.mrp.xml) using your favorite Web browser.

      This will show the same content as the sample HTML output files, but the HTML content is dynamically created by
      your Web browser.  This allows you to immediately see any changes you may make to the sample XML files without
      having to go through the HTML file creation process described in step d).

      This has been tested with Internet Explorer V7, Firefox 3.5+3.6+4.0, and SeaMonkey V1.1, but it should work with
      any Web browser that supports XSLT 1.0.

      It seems that in some installations of Web browsers, the use of ".." in the "href" attribute of "xml-stylesheet"
      processing instruction does not work.  If the MRP XML files when viewed in a Web browser appear to miss some text,
      then most likely the dsp8029 XSLT file specified in the xml-stylesheet processing instruction was not found by the
      Web broeser.  To solve this issue, copy the resources/dsp8029_1.0.0.xsl file to a place that does not require the
      use of ".." in the "xml-stylesheet" processing instruction, and update that processing instruction accordingly.
      If you want to specify the absolute path to the dsp8029 XSLT file, the syntax for Windows uses three slashes after
      "file:" and forward slashes as directory delimiters, like in the following example:
      href="file:///C:/dsp2023-unpack/profiles/resources/dsp8029_1.0.0.xsl"

      Prerequisites:
      - Preparation steps 2.a) and 2.b)
      - Your favorite XSLT 1.0 capable Web browser


   c) Edit the sample MRP XML files in an XML editor.

      Verify that the XML editor finds all prerequisite XSD files.

      Look at the XML Schema description help that should be provided by your XML editor.  This explains the XML schema
      for MRP by showing the XSD schema annotations provided by the MRP XSD and related XSDs.

      Make some changes, and see how they are immediately (after saving ;-) visible in the Web browser that is
      displaying the MRP XML file you are editing, by just refreshing the browser.

      Prerequisites:
      - Preparation steps 2.a), 2.b) and 2.c)
      - Your favorite XSD 1.0 capable XML editor


   d) Convert the sample MRP XML files to HTML output files and further to PDF output files.

      A) When using the make-based build environment:

         Open a command prompt and execute in the profiles directory under the DSP2023 unpack directory:

           make clean buildmrp

         This first deletes the generated HTML and PDF files and then regenerates them.

         You may want to first save the HTML and PDF files that came with DSP2023 and compare the newly generated ones
         with the saved ones.

      B) When using the Eclipse or RSA based build environment:

         Select one of the sample .mrp.xml files unpacked from DSP2023, and click menu Run -> External Tools -> mrpbuild

         This executes the mrpbuild.ant script, which creates a .html file and a .pdf file for the selected .mrp.xml
         file in the directory of the selected .mrp.xml file.

      Prerequisites:
      - Preparation steps 2.a), 2.b), 2.c) and 2.d)


   e) Write your own MRP profiles.

      The sample archive contains XMP1000, which is the MRP Profile Template.  It contains nearly everything an MRP
      profile can contain.  It validates against the XML schemas and produces no profile errors when displayed with the
      DSP8029 XSLT stylesheet.

      XMP1000 should be used as a starting point for writing your first MRP profiles.

      You can of course also look into the other sample profiles, but not all of them use the dsp8008 text registry for
      creating boilerplate text, which is recommended to be used.


   f) Create standard glossaries using the MRP format.

      The sample archive contains XMP1999, which is a sample glossary in MRP format.

      A glossary in MRP format only defines terms and definitions, but it is released as a specification.  The terms and
      symbols can be referenced from MRP profiles (and, of course, from other MRP glossaries).


4. Migration of older MRP profiles to current Work in Progress version

   a) from version 1.0.0e of dsp8028 to version 1.0.0f/1.0.0g:

      Run the Windows batch script mrpmigrate_100e_100f.bat to produce a copy of the 1.0.0e conformant mrp.xml file that
      conforms to version 1.0.0f and 1.0.0g.  That batch script file is located in the bin directory of the DSP2023 ZIP
      file.

      This batch script performs the following changes on the profile copy:
      - adjusts the Work in Progress version of MRP related files.
      - adjusts to the new concept of referencing text registry fragments (by name instead of by message ID).

      This batch script uses commands from CygWin, as documented in the batch script file.

      General command syntax:

        mrpmigrate_100e_100f input_profile_path output_profile_path

      Example command, from within the unpack directory of the DSP2023 ZIP file:

        bin\mrpmigrate_100e_100f profiles\myprofile\myprofile.mrp.xml profiles\myprofile\myprofile.new.mrp.xml

   b) from version 1.0.0f/1.0.0g to 1.0.0

      Edit each mrp.xml file and perform the following changes:

        - Change each <p> element with class="Figure" to a <div> element.  Note that their child <p> elements with
          class="Figure-Caption" remain a <p> element.

        - If you experience Prince-XML errors "Unexpected end tag: p", then this is because you have nested <p>
          elements.  The HTML standard states that nested <p> elements implicitly end their parent <p> elements so that
          they become siblings instead. You may want to clean this up.


#***********************************************************************************************************************
