This package supports the export from an OpenOffice 3 [OOo] spreadsheet of subset rows of the SimpleCodeList element of an OASIS [OASIS] genericode [genericode] file. This specification is maintained by the OASIS Code List Representation Technical Committee [CLRTC].

Installing this package as an XML Filter in OpenOffice 3 enables the user to use the "File / Export..." menu item to export the contents using the "Genericode SimpleCodeList" format.

This export can be used for any ODS spreadsheet that satisfies the spreadsheet assumptions documented in Section 5, “Assumed spreadsheet format”. As such, it will likely be very useful in other projects totally unrelated to UBL or its naming and design rules (NDR). Genericode is an effective XML serialization of sparsely-populated tables.

For important information on how to use the parsed general entity XML output from this export, please review Section 4, “Creating a valid genericode file from a genericode subset”.

If you should encounter any problems within the document areas of functionality, we welcome your feedback to improve the application for you and other users. Please contact us at info@CraneSoftwrights.com with your information.

Copyright (C) - Crane Softwrights Ltd.
              - http://www.CraneSoftwrights.com/links/res-dev.htm

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice,
  this list of conditions and the following disclaimer in the documentation
  and/or other materials provided with the distribution.
- The name of the author may not be used to endorse or promote products
  derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Note: for your reference, the above is the "Modified BSD license", this text
      was obtained 2003-07-26 at http://www.xfree86.org/3.3.6/COPYRIGHT2.html#5

THE AUTHOR MAKES NO REPRESENTATION ABOUT THE SUITABILITY OF THIS CODE FOR ANY
PURPOSE.

No special preparation of OpenOffice 3 is required for the first time installing this filter. Subsequent installations of this filter should follow uninstalling the installed version of the filters.

2.1. Uninstalling the installed version of these filters

At this time of writing there are problems sometimes exhibited in OpenOffice 3 when trying to install a new version of one of these filters on top of an old version of the same filter (that have been reported to the OpenOffice developers http://www.openoffice.org/issues/show_bug.cgi?id=97170). It is recommended that you first uninstall an old version of the filter before installing a new one.

The following steps will effectively remove the significant remnant of an old installation.

Start OpenOffice 3 and open a new document or spreadsheet. Click the menu item "Tools" / "XML Filter Settings...", select the "UBL NDR to Genericode SimpleCodeList by Crane Softwrights Ltd" filter and press the button "Edit...":

Figure 1. Editing the package for deleting the package contents

Select the "Transformation" tab and press the "Browse..." button for the "XSLT for export" selection:

Figure 2. Browsing the export directory

Right click on the stylesheet name and delete the stylesheet (note that if you hold down the shift key this will permanently delete the file rather than sending it to the recycle bin):

Figure 3. Deleting the old filter file

Press the "Cancel" button to return to the "Transformation" tab, and then press "Cancel to return to the "XML Filter Settings" dialogue box. Press the "Delete..." key to delete the filter:

Figure 4. Deleting the package itself

Note at this point it is often true that the filter entry still shows in the "XML Filter Settings" dialogue box even though you have requested to delete it. Pressing "Close" and reopening the dialogue box using the menu item "Tools" / "XML Filter Settings..." will show the list without the deleted entry.

2.2. Installing the filter

Start OpenOffice 3 and open a new document or spreadsheet. Click the menu item "Tools" / "XML Filter Settings..." to get to the filter dialogue.

The filter is installed using the following procedure. Press the button "Open Package..." without regard for any existing filter that may happen to be selected:

Figure 5. XML Filter Settings Dialogue

Navigate to the directory in which you unzipped the distribution file and select Crane-gcExportSubset.jar to add the "UBL NDR to Genericode SimpleCodeList by Crane Softwrights Ltd" filter to your installation and report successful operation:

Figure 6. XML Filter Successful Installation Dialogue

Open a UBL NDR spreadsheet or other compatible spreadsheet (see Section 5, “Assumed spreadsheet format” using the "File / Open..." menu item. Use "File / Export..." to bring up the export dialogue.

The file extension of the genericode subset file does not have to be anything in particular, but it is recommend not to use ".gc" since the exported file as it stands alone cannot be validated using the genericode schemas. The use of the generic ".xml" is quite suitable for an external general entity.

In this example, the file "myCodeList-SimpleCodeList.xml" is created. Note the ".xml" extension is assumed.

Figure 7. Export a genericode subset

The exported output general entity XML syntax cannot be used standalone. The file must be incorporated into an XML document that defines all of the other genericode information for the file. This can be done with cut and paste, however there are XML techniques of incorporating an external general entity without manual intervention.

Consider a fragment of the example myCodeList-SimpleCodeList.xml exported syntax from the MyBusinessDocument.ods spreadsheet included in the distribution, noting that this is a well-formed XML external general entity and not a well-formed XML file (because of the multiple document elements):

<Row>
   <Value ColumnRef="ModelName">
      <SimpleValue>UBL-SignatureLibrary-2.1</SimpleValue>
   </Value>
   <Value ColumnRef="UBLName">
      <SimpleValue>SignatureInformation</SimpleValue>
   </Value>
   ...
</Row>
<Row>
   <Value ColumnRef="ModelName">
      <SimpleValue>UBL-SignatureLibrary-2.1</SimpleValue>
   </Value>
   <Value ColumnRef="UBLName">
      <SimpleValue>ID</SimpleValue>
   </Value>
   ...
</Row>

An XML genericode document incorporates an external general entity using an internal declaration subset, as shown in myCodeList.gc (a copy of which is included in the distribution):

<!DOCTYPE gc:CodeList
[
<!ENTITY SimpleCodeList SYSTEM "myCodeList-SimpleCodeList.xml">
]>
<gc:CodeList xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
   <Identification>
      ...
   </Identification>
   <ColumnSet>
      ...
   </ColumnSet>
   <SimpleCodeList>
      &SimpleCodeList;
   </SimpleCodeList>
</gc:CodeList>

When the referred external general entity exists and is a well-formed entity, the referring XML document is well-formed.

A single XML genericode document can incorporate the output from the exports of multiple spreadsheets using multiple entities and corresponding entity references:

<!DOCTYPE gc:CodeList
[
<!ENTITY rowGroup1 SYSTEM "rowGroup1-export.xml">
<!ENTITY rowGroup2 SYSTEM "rowGroup2-export.xml">
<!ENTITY rowGroup3 SYSTEM "rowGroup3-export.xml">
<!ENTITY rowGroup4 SYSTEM "rowGroup4-export.xml">
]>
<gc:CodeList xmlns:gc="http://docs.oasis-open.org/codelist/ns/genericode/1.0/">
   <Identification>
      ...
   </Identification>
   <ColumnSet>
      ...
   </ColumnSet>
   <SimpleCodeList>
      &rowGroup1;
      &rowGroup2;
      &rowGroup3;
      &rowGroup4;
   </SimpleCodeList>
</gc:CodeList>

This export filter makes the following assumptions regarding the ODS spreadsheet:

These assumptions are satisfied by the UBL Naming and Design Rules spreadsheets, but there is no constraint on this export filter that the file be such a spreadsheet. This filter is likely useful needing a spreadsheet of columnar data exported as a sparsely-populated table in XML syntax.