This web-site copy of the readme.html file is posted to provide information regarding the scope and use of this software.

1. Introduction

This package supports the editing of OASIS [OASIS] genericode [genericode] files and OASIS context value association [CVA] files (which reference genericode files) using OpenOffice 3 [OOo]. It also includes the validation and formatting of the resulting genericode and CVA XML [XML 1.0] documents. These two specifications are maintained by the OASIS Code List Representation Technical Committee [CLRTC].

Installing these two packages as XML Filters in OpenOffice 3 enables the user to create new or edit existing genericode and CVA files. The supplemental validation and rendering processes are supported using either drag-and-drop or a command-line interface in Windows.

Some sample genericode and CVA files from the OASIS Universal Business Language 2.0 [UBL 2.0] package are included for demonstration.

For limitations please review Section 9, “Help, future plans and other documentation”.

1.1. Restrictions of use

Redistribution in source or binary forms in any way is strictly prohibited.

There is no charge for the purchase of this code but the use of this code, unless specifically permitted in writing by Crane Softwrights Ltd., is restricted to bona-fide users of Crane Softwrights Ltd. book: Practical Code List Implementation [Crane Books].

THE AUTHOR MAKES NO REPRESENTATION ABOUT THE SUITABILITY OF THIS CODE FOR ANY PURPOSE. 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.

2. Installation

No special preparation of OpenOffice 3 is required for the first time installing these filters. Subsequent installations of these filters 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. If you choose to simply install the new filter, you will know this is successful if opening a genericode or CVA file presents the Crane interface. If you attempt to open a genericode or CVA file and you end up with an empty spreadsheet instead of the Crane interface, this is evidence of the new filter having been corrupted during installation over top of the old filter.

The following steps will effectively remove the significant remnants of an old installation, and must be performed once for each of the two filters:

Start OpenOffice 3 and open a new document or spreadsheet. Click the menu item "Tools" / "XML Filter Settings...", select (for example) the "Genericode 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 repeat for the "Template for import" entry (note that it is not necessary to do this for the "XSLT for import" entry):

Figure 4. Browsing the template directory

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 5. Deleting the package itself

Don't forget to do the same steps for the second of the two filters, in this example that would be the "CVA by Crane Softwrights Ltd" filter.

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

2.2. Installing the two filters

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

Each filter is installed separately using the following procedure (illustrated for the "Genericode by Crane Softwrights Ltd" filter but the same steps are taken for the "CVA by Crane Softwrights Ltd" filter). Press the button "Open Package..." without regard for any existing filter that may happen to be selected:

Figure 6. XML Filter Settings Dialogue

Navigate to the directory in which you unzipped the distribution file and select Crane-gc2ods.jar (for this example) to add the "Genericode by Crane Softwrights Ltd" filter to your installation and report successful operation:

Figure 7. XML Filter Successful Installation Dialogue

Repeat this "Open Package..." step using Crane-cva2ods.jar for the "CVA by Crane Softwrights Ltd" filter.

3. Opening genericode files

You can open up an existing genericode file (subject to the limitations described in Section 9, “Help, future plans and other documentation”) or create a new genericode file.

3.1. Opening an existing genericode file

Open an existing genericode file from within OpenOffice the using the "File/Open..." menu item and selecting files of type "Genericode (*.gc)". This file type entry is sometimes difficult to find in the very long list of document types, but can quickly be selected by pressing the "G" key until the type is given. When using the drop-down list, this entry is found in the long section of spreadsheet file types beginning with "ODF Spreadsheet (*.ods)".

The file extension of the genericode file does not have to be ".gc" but can be any file extension. In the example of the extension being ".xml", first enter "*.xml" for the file name and then select the file type to be genericode.

Review Section 9, “Help, future plans and other documentation” when opening a genericode file results in an empty spreadsheet.

Figure 8. Open an existing genericode document

3.2. Creating a new genericode file from scratch

Selecting the menu item File/New/Templates and Documents" brings up the "Templates and Documents - Templates" dialogue. Double-click on the "Genericode by Crane Softwrights Ltd" entry to bring up the "Templates and Documents - Genericode by Crane Softwrights Ltd" dialogue. Double-click on the "genericode" entry to bring up a copy of the genericode template.

Figure 9. New genericode document from scratch

4. Opening CVA files

You can open up an existing context value association file (subject to the limitations described in Section 9, “Help, future plans and other documentation”) or create a new context value association file.

4.1. Opening an existing context value association file

Open an existing context value association file from within OpenOffice the using the "File/Open..." menu item and selecting files of type "Context Value Association (*.cva)". This file type entry is sometimes difficult to find in the very long list of document types, but can quickly be selected by pressing the "C" key until the type is given. When using the drop-down list, this entry is found in the long section of spreadsheet file types beginning with "ODF Spreadsheet (*.ods)".

The file extension of the genericode file does not have to be ".cva" but can be any file extension. In the example of the extension being ".xml", first enter "*.xml" for the file name and then select the file type to be CVA.

Review Section 9, “Help, future plans and other documentation” when opening a genericode file results in an empty spreadsheet.

Figure 10. Open an existing context value association document

4.2. Creating a new context value association file from scratch

Selecting the menu item File/New/Templates and Documents" brings up the "Templates and Documents - Templates" dialogue. Double-click on the "CVA by Crane Softwrights Ltd" entry to bring up the "Templates and Documents - CVA by Crane Softwrights Ltd" dialogue. Double-click on the "contextValueAssociation" entry to bring up a copy of the CVA template.

Figure 11. New context value association document from scratch

5. Using OpenOffice format for intermediate results

There is very little validation going on in OpenOffice 3 when creating the content of a genericode file. The export does as much as it can with the information at hand, but some incomplete information may be lost when using the genericode format. After saving the document in genericode format, you can also choose to save a copy in Open Document Spreadsheet [ODF] format which will preserve everything that has been entered.

6. Saving and reloading the file to effect changes

There are a number of actions that take place when a genericode or context value association file is loaded into OpenOffice 3 using these filters, and there are editing steps that are only engaged when the file being edited is reloaded after a save operation. This technique avoids the need to install macros in the template, as some users of OpenOffice are expressly prohibited from engaging macros.

When during the editing process you need to move, insert or delete column definitions, or when needing to increase the quantity of repeated constructs allowed by a cardinality of "0..n" or "1..n", this is engaged by saving and reloading the file being edited.

Be careful to save first before attempting a reload, as if you cancel your changes during a reload process you will lose your work.

To save the document use the "Save" or "Save as..." entry in the "File" menu, avoiding at this time the use of the "Reload" entry:

Figure 12. Saving the current work

To engage the changes after saving, use the "Reload" entry in the "File" menu:

Figure 13. Reloading the current work to engage the changes

7. Validating genericode and context value association files

In the installation directory are the Windows batch files "validate-genericode-drag-and-drop.bat" and "validate-CVA-drag-and-drop.bat". These can be used either from the command line prompt using a direct invocation, or from the Windows file manager using an indirect drag-and-drop invocation. Simply drag your file onto the appropriate validate icon and a window will pop up reporting the results of validation.

Figure 14. Drag and drop Windows validation interface

Figure 15. Drag and drop Windows validation interface

The validation uses the corresponding W3C Schema [W3C Schema] expression of constraints of each document type, checked with Norm Walsh's xjparse [xjparse] invocation of xerces [Xerces].

8. Rendering XML files

In the installation directory is the Windows batch file "stylesheet-drag-and-drop.bat". This can be used either from the command line prompt using a direct invocation, or from the Windows file manager using an indirect drag-and-drop invocation. Simply drag your XML file onto the validate icon and a window will pop up reporting the results of applying the stylesheet referenced in your XML file in the stylesheet association processing instruction[Assoc]. The pop-up window will disappear if there are no problems with the transformation, and will persist if there are.

Figure 16. Drag and drop Windows stylesheet interface

The rendering uses the Saxon [Saxon] invocation of XSLT 1.0 [XSLT 1.0], and works with any XML instance in which the stylesheet association processing instruction is used.

Note that when using the Windows Explorer interface, generating the HTML file in this way sometimes does not trigger a refresh of the File Manager window. Pressing F5 will refresh the directory listing in the window.

Note also that simply editing the genericode or context value association file does not recreate the HTML rendition. To get an up-to-date rendition one must recreate the HTML after saving any changes to the edited file.

9. Help, future plans and other documentation

Getting an empty spreadsheet when trying to open a genericode file in OpenOffice is evidence of an installation problem. Please review Section 2, “Installation” for details regarding uninstalling the old filter and reinstalling a new filter.

All other documentation for this package is found under the "Help" tab of either the genericode.ots or contextValueAssociation.ots template. The template is opened by creating a new genericode file using the procedure described in Section 3.2, “Creating a new genericode file from scratch” or Section 4.2, “Creating a new context value association file from scratch”.

Figure 17. The help tab

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.

10. Bibliography