RE: [kmip] Naming and format suggestions for Base Objects and Managed Objects

["Rod Wideman" <Rod.Wideman@quantum.com>]

Hi Rene,

 

Yes, this is better.  Do you think the third column should still be "Required Field" instead of just "Required"? (the examples from section 3 still have "Required Field").  I think "Required" is sufficient.

 

Personally, I still think including the top level structure as a row by itself could lead to confusion, since the table is mainly trying to describe what is in the structure; the fact that it is a structure is already conveyed by the text and title.  Even by using the PASCAL example, the table contents would be the items between RECORD and END, as the table itself is the TYPE framework.

 

One last suggestion would be to just combine the first two rows:

 

Credential Field	Field Encoding	Required
Credential Type	Enumeration	Yes
Credential Value	Octet String	Yes

 

The indentation could be preserved if desired.  This seems more economical and clear to me, but I realize it's a matter of opinion.

 

Thanks!

Rod

 

---

From: Rene Pawlitzek [mailto:rpa@zurich.ibm.com]
Sent: Thursday, June 25, 2009 7:23 AM
To: Rod Wideman
Cc: kmip@lists.oasis-open.org
Subject: Re: [kmip] Naming and format suggestions for Base Objects and Managed Objects

Rod, 

here is my proposal for reformatting the tables. I 
believe that with only a few minor changes we can increase readability. The idea 
is to format the tables into a PASCAL-like layout. 

Rene 




--

Rene Pawlitzek
IBM Zurich Research Lab.
Department of 
Computer Science
Saeumerstr. 4
CH-8803 Rueschlikon
Switzerland
tel.: 
+41-44-724-8683
mail: rpa@zurich.ibm.com
http://www.zurich.ibm.com/~rpa/

http://hamlets.sourceforge.net

From:	"Rod Wideman" <Rod.Wideman@quantum.com>
To:	<kmip@lists.oasis-open.org>
Date:	06/10/2009 06:10 AM
Subject:	[kmip] Naming and format suggestions for Base Objects and Managed Objects

---

Hi, 
  
I have a few observations and suggestions to share 
regarding sections 2.1 (Base Objects) and 2.2 (Managed Objects).   
  
Base Objects appear 
to be consistently structures, and the term "base objects" seems to be an idea 
to differentiate them from managed objects. Some of these base objects have 
additional structures within them. The tables used throughout 2.1 are all 
consistent in layout though, using the same layout for things called objects and 
things called structures. The first column header is labeled "Object", but most 
of the rows appear to be fields within the object (or structure), and the last 
column header is labeled either "Required" or "Required Field" (the latter label 
also implying that the rows are fields). 
  
Each table includes a row that is the name of the 
object or structure itself, for which the table defines.  Since this row is 
included along with the rows (fields) that compose the object or structure, it 
may lead to some confusion, but at least seems distracting (to me 
anyway). 
  
So my 
suggestions are as follows: 
  
 - Structure the tables slightly differently by using a 
title for each table and reference the table by title in the text 
  
 - Call "base 
objects" something else, like just "structures".  Then whether or not they 
contain sub-structures, all the tables and text in 2.1 can be consistent and 
Managed Objects in 2.2 can more cleanly refer to structures. 
  
I'm attaching a PDF that 
attempts to show a few examples of what I'm describing. 
  
Thanks, 
Rod Wideman 
Quantum 
Corporation 
  
(please disregard the confidentiality statement below)

---

The information contained in this transmission may be confidential. 
Any disclosure, copying, or further distribution of confidential information is 
not permitted unless such privilege is explicitly granted in writing by Quantum 
Corporation. Furthermore, Quantum Corporation is not responsible for the proper 
and complete transmission of the substance of this communication or for any 
delay in its receipt.[attachment "ObjectTableFormatChanges.pdf" deleted by Rene 
Pawlitzek/Zurich/IBM] ---------------------------------------------------------------------
To 
unsubscribe from this mail list, you must leave the OASIS TC that
generates 
this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php