#***********************************************************************************************************************
# 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.0.zip
# http://www.dmtf.org/standards/published_documents/dsp2023_1.0.zip
#
# Date: 2012-03-19
# Version: 1.0.0
# 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. Directory structure and files in the DSP2023 ZIP file:

  Directory structure:

       +                            Root directory of DSP2023 ZIP file
       |
       +-- profiles                 Subtree for MRP profiles; contains a makefile and is the CWD for running make.
       |   +-- xmp1000              Sample profile xmp1000
       |   +-- 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 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 DSP8029.xsl.  They
                                    can be looked at using a Web browser without having to set up the CIM-XML files
                                    needed by the DSP8029.xsl XSLT stylesheet.  The HTML files reference the sample
                                    figure files as well as some files from the profiles/resources directory (e.g.
                                    DSP8054 CSS and DMTF logo)

  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:


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

      This unpacking step is required for the MRP XML and HTML output files to be able to find the right figure files.
      Opening any MRP XML or HTML output files directly from within this archive without unpacking it typically results
      in an incorrect display of these files.


   b) For viewing the sample MRP XML files in a Web browser (item 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 in the
         DSP8029 XSLT stylesheet (profiles/resources/dsp8029_*.xsl, global parameter "cim-xml-root-url").

         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 WG members only.

              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.

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

           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, it 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.

         - 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.


   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:

      Establish a build environment as follows (for Windows):

      1) Have the commands available that are described in the file profiles/makefile. They can be installed from the
         following packages:

           CygWin 1.7                                 http://cygwin.com/install.html
           Apache Xalan-J 2.7.1                       http://xml.apache.org/xalan-j/downloads.html#latest-release
           Apache URI Resolver 1.2 from XML-Commons   http://xml.apache.org/commons/#releases

      2) Customize the bin/xalan.bat script from DSP2023 for your environment and make it available in the PATH.

      3) Customize the bin/CatalogManager.properties file from DSP2023 for your environment and make it available in the
         CLASSPATH (as defined in your customized xalan.bat).  For consistency, you can let the "catalogs" variable in
         that properties file point to the XML Catalog file your XML editor uses (e.g. for XMLSpy, the RootCatalog.xml
         file), instead of directly to the localcopy/catalog.xml of DSP2023.

      4) 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.

      5) Customize the bin/prince-xml.bat script from DSP2023 for your environment and make it available in the PATH.

      6) 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.

      The build environment described above is a sample build environment based on the use of the GNU make utility that
      is part of CygWin, and of other tools.  See the makefile in the profiles directory for a complete list of
      prerequisites.  This environment is provided for convenience and can be used to develop your own MRP profiles if
      you follow the directory structure used by the sample profiles.  However, there is no requirement to use this
      particular build environment.  For example, the IBM Rational Software Architect environment with its built-in XML
      editor, XSLT processor, and ANT build tool has been used successfully as alternative build environment.


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.

      Using the make-based build environment described in 2.d) on Windows, 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.

      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.


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