Copyright © 2011 Crane Softwrights Ltd.
Portions copyright © OASIS Open 2011. All Rights Reserved. -
http://www.oasis-open.org/who/intellectualproperty.php
$Date: 2011/10/30 02:00:22 $(UTC)
Table of Contents
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.
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...":
Select the "Transformation" tab and press the "Browse..." button for the "XSLT for export" selection:
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):
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:
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.
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:
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:
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.
The output subset XML is a well-formed XML general entity and not a well-formed XML document. Please see Section 4, “Creating a valid genericode file from a genericode subset” regarding how to use this subset to create a well-formed XML file in order to use the information as XML or to validate that file using the genericode schema.
In this example, the file
"myCodeList-SimpleCodeList.xml
" is created. Note
the ".xml
" extension is assumed.
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:
all worksheets of the spreadsheet are included in the export as a contiguous set of rows, each independently defining the rows for that worksheet
each first-row column's visible text string, with all white-space
characters removed, defines the genericode
<ColumnSet><Column Id="">
identifiers used
by the attribute values in the <Value
ColumnRef="">
elements in the exported rows
the second and subsequent rows are exported as
Row
elements, ending before the first row whose
entire row content is the string "END" (thus allowing non-exported
comments to follow), or at the last row of the spreadsheet if no such
"end row" exists
every row exports the worksheet tab title as a <Value
ColumnRef="ModelName"><SimpleValue>
element
you can hack the stylesheet to replace the one occurrence of
the nine letters 'ModelName
' with the desired
value:
if you wish to change the column reference used for the worksheet tab title, replace the string with the desired value (keeping the surrounding quotes)
if you wish to inhibit the export of the worksheet tab title, empty the string (keeping the surrounding quotes)
you can find the stylesheet to edit by using the dialogue box pictured in Figure 2, “Browsing the export directory”
only those columns of each row that have non-white-space visible
text are exported, each one in a
<Value><SimpleValue>
element
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.
[CLRTC] G. Ken Holman, Chair Code List Representation Technical Committee
[genericode] Tony Coates genericode, OASIS Code List Representation Technical Committee repository
[ODF] Open Document Format http://www.oasis-open.org/committees/office/
[OOo] Open Office http://www.openoffice.org