Some directions for using the Kavi document repository

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

Fellow Code List Representation TC members,

My action items from our first meeting was to 
overview what I've learned regarding using the 
Kavi document repository.  After years of working 
with the repository I still make mistakes on a 
daily basis that require me to modify my entries, 
so please don't get discouraged trying to work with the files.

First of all, go to our committee work page:

   http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=codelist

   (eventually this will be http://www.oasis-open.org/committees/codelist
    but that link is not yet active)

There is a purple button titled "TC Members Page" 
used to get to the work area after logging in:

   http://www.oasis-open.org/apps/org/workgroup/codelist/

Ignoring the yellow left-aligned banner near the 
top, there is a banner of highlighted words lower 
down, right aligned, in which you will find a 
link to "Roster", "Calendar", "Documents", etc. 
... go into the repository by clicking "Documents".

There are a number of folders:

     Code List Examples
     Discussion Drafts
     Standards
     Submissions
     Temporary files and sandbox

Determine the folder into which you need to 
upload the document and click "Add New Document" 
to start document upload interface.

The upload interface has many fields:

  - the document source can be entered in the 
"Browse for a file on your computer:" box directly or with the browse button
    - I typically follow a convention on the file 
name of including the string "-CCYYMMDD-HHMMz" in 
the filename where the time of day is UTC (indicated by the "z" suffix)
    - you will see below that I have found a 
purpose for using the "Enter Web Address" box, 
but this shouldn't be for committee materials 
because the resources should have a permanent 
home in the Kavi document repository

  - I do not change the document title so that 
the file timestamp shows in the repository

  - the description is used for all versions of 
the document; I typically set it for the purpose of the document

  - the initial comment describes the particular 
revision being uploaded; I don't usually have a 
comment in the first version but I do describe 
changes in this box when I post revisions

  - usually the folder and sharing are pre-set, 
but if not, be sure to enable sharing to the general public

  - the state should be left as draft; other 
states will be used later in the committee process

  - IMPORTANT: turn off Email Notifications:  it 
is my practice (and recommendation) that you post 
your own notification (described below) so please 
turn this off because the automatic notification 
produced by Kavi uses a hyperlink that is only 
password protected, and I prefer posting links 
that are publicly accessible, as this will help 
those who are looking through our archives

  - now the document can be uploaded using the 
"Add Document" button ... I find I often get a 
"cannot find server or DNS error" with large 
files (sometimes even with small files!), 
requiring me to go back to the upload 
(descriptions are preserved but not file name or 
turned-off email notification), reentering the 
filename, and possibly having to turn off the 
email notification and trying again

At this point you should have the document in the 
repository.  Go back to the Documents menu and 
you should see your document in the folder 
listing.  Note that under the "Actions" column at 
the right you can access the meta data by 
clicking on "Manage" for your documents.  This 
reads as "Details" for documents you did not 
upload since you cannot change the meta data for 
those documents.  This is where you would delete 
the document or modify the meta data (including 
the document file name if need be).

Next, to prepare the email announcement to the 
group and archives, you have to determine the 
document number in the repository ... this is 
done by hovering (without clicking) over the 
hyperlink of the filename given to you in the 
"document details" box, or under the Document 
Name column, and looking at your status bar in 
your browser ... this hyperlink has the format:

   http://www.oasis-open.org/apps/org/workgroup/codelist/download.php/#####/XXXXX

... where ##### is the document number in the 
repository and XXXXX is the filename.  This file 
name is the *password protected* filename, so 
this is *NOT* the filename you should be posting 
in the group archive.  Unfortunately this is the 
filename that is posted if you let Kavi do its 
own email announcement of your file, which is why 
I ask that you not let Kavi do it.

Now that you are equipped with the document 
number, you should be able to use your browser 
address bar and enter the hyperlink with "#####" 
replaced with your document's number:

   http://www.oasis-open.org/committees/document.php?document_id=#####

It is with this publicly-accessible link that you 
post your message to the list in the normal 
fashion with your own composed email 
message.  This hyperlink is not protected by a 
password and the general public will have access to the document.

It is hard to remember to do this, but those of 
your documents that are under constant revision 
should be managed in Kavi as separate revisions 
of the *same* document.  I find that I do, 
accidentally, forget to post a new revision as a 
revision of an old document, but I have a recovery strategy noted below.

An example of a document with many revisions is 
in my work in UBL, where the following links to version 7 of a document:

   http://www.oasis-open.org/committees/document.php?document_id=20232

If you should have a revision for your document, 
find the document in the main repository listing 
and click "Manage" under the "Actions" 
column.  Click the "Add a revision" button to 
start the document upload interface again, this 
time for your new revision, and again please 
remember not to use automatic email 
notifications.  You will see that you will get a 
new document number from the repository and you 
can customize your own notification to our mail 
list for others (and the public through the archive) to see.

An example of where I messed up and forgot to 
post a revision as a revision can be see in the revision of the following:

   http://www.oasis-open.org/committees/document.php?document_id=20255

In the history for document 20255 you will see 
that I started revising version 6 of this 
document (the point where I finally learned about 
using revisions) with a version 7 and a version 
8, and each of the ZIP files can be seen.  I 
didn't have a version 9, but when version 10 came 
around I forgot to make it a revision of version 
8 and started a brand new document 20273:

   http://www.oasis-open.org/committees/document.php?document_id=20273

Revisions to this document (version 10) now have 
to go in as revisions to 20273 ... but how did I 
link the unlinked version 10 to the old version 
8?  I went into the "Manage" interface for 
version 8 and posted the above 20273 web page 
address as the document source for the revision 
for version 8 in the "Enter Web Address" box.  I 
also entered filled in the Document Title with 
the revision timestamp and the word "Link".

Now when someone looks in the repository at 
versions 6, 7 or 8, they will find there is a 
revision 10, and when they click on that they 
will then see version 10 and any subsequent 
versions in the history of version 10.  One 
cannot trace backwards to older revisions this 
way, but that is less important than being able 
to trace forwards to newer revisions, which I believe this scheme accomplishes.

I hope this is considered helpful.  I would 
apologize for the complexity, but then I didn't 
design this interface ... but after working with 
it for a while it really does make sense and when 
one is carefully uploading documents the end 
result can be a very useful resource for the 
general public reviewing the archive.  I 
especially like it that someone finding a 
two-year-old link to the repository will see that 
there are revisions of the document they are 
looking for that were posted after the original announcement was made.

So, I live with the complexity.  I hope you can as well.

Please let me know if you have any questions.

Thanks!

. . . . . . . . . . . . . Ken

--
UBL/XML/XSLT/XSL-FO training: Vårø, Denmark 2006-10-02/06,11-20/24
UBL International 2006  2006-11-13/17 http://www.ublconference.com
World-wide corporate, govt. & user group UBL, XSL, & XML training.
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/o/
Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
Male Cancer Awareness Aug'05  http://www.CraneSoftwrights.com/o/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal