[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [ddlm-group] DDLm aliases (subject changed). .. .. .. .. .

Title:
I can see depricating an item in an approved dictionary.  DDLm has not been approved and it is clear that the xref section cannot be meaningfully used in its present form.  Anyone using the posted draft dictionary must understand that changes will be made and that any development work done using this dictionary may be nonconforming.

The need to avoid dataname duplication is a red herring.  We are redefining items in the draft database, thus effectively using the same name to refer to a value with different attributes from those in the original draft.

But it is not worth getting too hung up on this.  Deprecating an item that has never been used does no harm, but it clutters up the dictionary unnecessarily and unless we arrange for the item to self destruct after five years, it will remain forever.  So let's make sure we get the concepts and code correct for the things that matter.

David



Herbert J. Bernstein wrote:
Dear Colleagues,

  There are two very distinct sets of issues in David's
message:

  1.  The management of specification changes in the DDLm
dictionary; and

  2.  The issues of the particular change being considered
here.

Let me address only the first issue here:  the management
of specification changes in the DDLm dictionary.

Both John B. and David seem uncomfortable with the idea of
deprecation rather than abrupt removal of a feature or
definition.  I refer you to the wikipedia article on
deprecation at

http://en.wikipedia.org/wiki/Deprecation

and quote the first paragraph:

"In computer software or authoring programs standards and documentation, the term deprecation is applied to software features that are superseded and should be avoided. Although deprecated features remain in the current version, their use may raise warning messages recommending alternative practices, and deprecation may indicate that the feature will be removed in the future. Features are deprecatedrather than being removedin order to provide backward compatibility and give programmers who have used the feature time to bring their code into compliance with the new standard."

In standards work, the approach has changed over time.  At the time
of Fortran 77, ANSI did not permit deprecation, only removal of
a feature.  Now ANSI not only permits deprecation, must, at least for
software standards, it is the norm for the reasons stated in the
wikipedia.

Thus the real question is whether there is enough invested in
the items being removed to justify retaining them for a while
in deprecated form.  We have no way of knowing.  DDLm has been
posted on the IUCr web site since 2007.  We have no way of
knowing who has seen it and started code development based on
it.  The prudent thing to do, whether we deprecate or remove,
or add a feature is to call attention to the change.  We can
and should do that in separate change documents, but it also
helps to put the warning directly in the DDLm dictionary itself.
If we simply remove a deprecated item, we lose a very convenient
place to put that notice.

There is also the issue of never duplicating tags.  Especially
while DDLm is in this developmental state, there is the risk,
if we remove a tag completely, that we will reintroduce it
later with the same name, but a different meaning -- causing
unnecessry confusion.

So, what I suggest is that we follow the following discipline:

1.  If we are removing an item, that we retain that item
in the dictionary for at least 5 years with one of the
following notations:

***DEPRECATED ITEM DO NOT USE
   RETAINED FOR REFERENCE ONLY***

***DEPRECATED ITEM DO NOT USE
   FOR NEW DEVELOPMENT WORK
   RETAINED ONLY TO SUPPORT
   EXISTING CODE AND DATA****

2.  That all deprecated items be gathered
into a segregated section of any relevant
dictionary.

3.  When a deprecated item is finally removed
from a dictionary, that a record be kept in
a separate deprecated items dictionary to
ensure against reuse of the deprecated
tag with a conflicting meaning.

Regards,
  Herbert

=====================================================
 Herbert J. Bernstein, Professor of Computer Science
   Dowling College, Kramer Science Center, KSC 121
        Idle Hour Blvd, Oakdale, NY, 11769

                 +1-631-244-3035
                 yaya@dowling.edu
=====================================================

On Mon, 31 Jan 2011, David Brown wrote:

Not having done any programming for many years and not being familiar with
the current jargon, I find keeping up with the rapid-fire discussion on
_aliases requires some effort on my part and the discussion has usually
move on before I havc a chance to comment.

However, being incommunicado on weekends, I took Herbert's draft home where
I could sit down without distraction and see what eactly what was
proposed.  The errors and ambiguities in the draft did not help me get my
heasd around the proposal, but I made some progress, and here are my
comments.  First the general comments, then particular comments interleaved
in the draft.

1. _identifier_set:  What does this set identify?  The _id seems to flag
arbitrary groups aliases.  'alias_set' would be a better name for this
category, or even just 'set'.  What's in a name?  It sets certain switches
in the brain, and if these are misset by the dataname, it may take a lot of
work to get them reset.  Not conducive to instant communication. 

2. Why do we need both _alias and _alias_identifier_set categories?  They
have indentical information (if the datanames (Syd's word) or tags
(Herbert's word) are any indication).  I suppose (though this is no where
spelled out) that _identifier_set would have its own save frame in the
dictionary and would not be an attfibute of a datanmae.  If this is a
correct interpretation it would provide a place whare all the alias
datanames in the dictionary could be listed within a single loop).  This
seems redundant, but I cannot speak from programming experience.  If
alias_identifier_set does not appesr in its own save_ frame, how does it
differ from 'alias'?

3. If my supposition in 2. is correct, we would appear to have a problem. 
We will now have a variety of flavours of CIF dictionaries, each expressing
a particular programmer's preferences for grouping the aliases.  This will
make no difference to the CIFs themselves as these groupings are irrelevant
once a CIF has been written, but if, for example, I am given a program
written by Herbert and different program written by either of the Johns, I
might need a different mmCIF dictionary for each of these two programs,
dictionaries that differ only in the way the aliases are gouped.  When I
load my CIF it cannot give instructions on which dictionary to call up
because is will have no knowledge of the idiosyncrasies of the program I
have chosen to use.  A possible solution would be to use the _import
feature to create a virtual dictioanry at run time.  Thus the
_identifier_set information would be held in a local dictionary that would
be imported into the authorised CIF dictioanry at run time.  However, there
are limitations on what can be imported.  The _identifier_set category
could be imported but it would be impossible to import the
_identifier_set_id into the alias loop by this mechanism.  Since I am not
sure that I understand how Herbert intends to use this feature, I do not
feel competent to suggest a way in which this problem could be handled. 
Having programs that used different dialects of CIF dictionaries does not
seem to be in line with the traditional development of CIF, particularly
for a feature that is unlikely to be much used, even if they do not affect
the CIFs themselves.  We should think carefully about the implications of
this move.
 
4. My detailed comments follow the feature they comment on below:



save_definition.xref_code
       _definition.id             '_definition.xref_code'
       _definition.update           2011-01-26
       _definition.class            Attribute
       _description.text
;
        Code identifying the equivalent definition in the dictionary
        referenced by the DICTIONARY_XREF attributes.

        Use of _definition.xref_code is deprecated in favor of
        use of _alias.xref_code
;
       _name.category_id            definition
       _name.object_id              xref_code
       _type.purpose                Identify
       _type.container              Single
       _type.contents               Code
        save_


This item is deprecated.  It should be deleted.   The  alias and xref
iitems have never been tested and it is clear from the current DDLm that
thay are placeholders that are awaiting development.  If there are any
programs that make use of the items they can only have been written by
members of this group.  The current xref defintiions inadequate and
unworkable. .The is no excuse for leaving this item in if we don't need it.

save_ALIAS

       _definition.id               alias
       _definition.scope            Category
       _definition.class            List
       _definition.update           2011-01-26
       _description.text
;
        The attributes used to specify the aliased names of definitions.
        Every tag has an implicit alias to itself with a null
        _alias.xref_code to allow use of the primary tag in
        the ALIAS_IDENTIFIER_SET category.

        The use of _alias.identifier_set_id in the key of
        this catgeory is provide a placeholder for the
        to conform the key of the parent ALIAS category
        to the key of the child ALIAS_IDENTIFIER_SET
        for automatic joins.  It is not intended that
        _alias.identifier_set_id should be used in the
        ALIAS category when no join is being done.


This last paragraph would be easier to undestand if all the words were
present and the sentences grammatical..  In any case it should appear under
_alias,identifierr_set, not here.  If I am right in thinking alias is an
attribute and alias_identifier_set is not,  how does one join a
non-attribute to an attribute?


;
       _category.parent_id          ddl_attr
       _category_key.primitive      ['_alias.definition_id',
                                     '_alias.xref_code',
                                     '_alias.identifier_set_id']
        save_


save_alias.definition_id
       _definition.id             '_alias.definition_id'
       _definition.class            Attribute
       _definition.update           2006-11-16
       _description.text
;
        Identifier tag of an aliased definition.
;
       _name.category_id            alias
       _name.object_id              definition_id
       _type.purpose                Key
       _type.container              Single
       _type.contents               Tag
        save_

save_alias.deprecated
       _definition.id             '_alias.deprecated'
       _definition.class            Attribute
       _definition.update           2006-11-16
       _description.text
;
        Specifies whether use of the alias is deprecated
;
       _name.category_id            alias
       _name.object_id              definition_id


.object_id should be the second part of the _definition.id, i.e.,
'deprecated'.  This needs correcting in many places.

       _type.purpose                STATE
       _type.container              Single
       _type.contents               YesorNo
       _enumeration.default         No
        save_


save_alias.dictionary_uri
       _definition.id             '_alias.dictionary_uri'
       _definition.update           2011-01-26
       _definition.class            Attribute
       _description.text
;
        Dictionary URI in which the aliased definition belongs.
        _alias.dictionary_uri is deprecated in favor if
        _alias.xref_code
;
       _name.category_id            alias
       _name.object_id              dictionary_uri
       _type.purpose                Identify
       _type.container              Single
       _type.contents               Uri
        save_


This item should be moved to the _dictionary_xref category.  The xref.id 
is sufficient link.  Again, the fact that it may appear in the draft
dictionaries should not prevent it being deleted in DDLm since the draft
dictionaries are just drafts and will be chaniged once we have sorted out
how to do the aliases.


save_alias.identifier_set_id
       _definition.id   '_alias.identifier_set.id'
       _definition.class  Attribute
       _definition.update 2011-01-26
       _description.text
;
       A code identifying an identifier_set of related tags.
       This linked item is provided in the ALIAS category to
       ensure that the key of the ALIAS category is
       conformed to the key of the ALIAS_IDENTIFIER_SET
       category.  The alias has not been joined with
       ALIAS_IDENTIFIER_SET, _alias.identifier_set_id
       it is not intended that  _alias.identifier_set_id
       in the ALIAS category.


I cannot make much sense of the last sentence.  Perhaps there are missing
words?


       This is a pointer to _identifier_set.id
;
       _name.category_id alias
       _name.object_id   code


See above.  'code' is not the proper .object_id

       _name.linked_item_id         '_identifier_set.id'
       _type.purpose     Key
       _type.container   Single
       _type.contents    Code
       _enumeration.default  .
      save_


save_alias.xref_code
       _definition.id             '_alias.xref_code'
       _definition.update           2011-01-26
       _definition.class            Attribute
       _description.text
;
        Code identifying the dictionary containing the primary
        definition of the dictionary as given in the
        DICTIONARY_XREF category.

;
       _name.category_id            definition
       _name.object_id              xref_code
       _name.linked_item_id         '_dictionary_xref.code'
       _type.purpose                Key
       _type.container              Single
       _type.contents               Code
        save_


save_IDENTIFIER_SET

     _definition.id      identifier_set
     _definition.scope   Category
     _definition.class   List
     _definition.update  2011-01-27
;
      Data items used to describe the identifier_set identifiers
      used in this dictionary.  Data items in this category
      are NOT used directly as attributes of individual data items.
      See linked item _alias_identifier_set.identifier_set_id
      for such uses.


;
      _category.parent_id ddl_attr
      _category_key.generic  '_identifier_set.id'

      save_

save_identifier_set.id
       _definition.id   '_identifier_set.id'
       _definition.class  Attribute
       _definition.update 2011-01-27
       _description.text
;
       A code identifying an identifier_set of related tags.
       The coverage of an identfier_set may conform precisely
       to the set of tags in a particular dictionary,
       or to tags drawn from multiple dictionaries or
       to a subset of tags from a single dictionary.

       The same tag may belong to multiple identifier
       sets, and a given tag may not belong to any
       identifier set, in which case the only associated
       identifier set is a null value.


Presumably the second line should read 'need not belong to any'.  The
wording above is ambiguous.
The last line should read 'identifier set id' and its default value should
be given explicitly.  What is nul?
Possible nul values are 'nul', '0', ' ', '?', '.', etc.

       To help ensure that dictionaries can be merged,
       each code should either begin with an IUCr-registered
       prefix or, if not prefixed, have been approved
       by COMCIFS.  The special prefix 'local_' may be
       use for purely internal purposes of an organization.


I assume these are not datanames that appear in the dictionaries but a list
of COMCIFS  enumerations, some of which might appear in a non-exclusive
enumeration list.  What happens if someone chooses 'joeblow' as an id?

;
       _name.category_id identifier_set
       _name.object_id   code
       _type.purpose     Key
       _type.container   Single
       _type.contents    Code

      save_

save_identifier_set.description
       _definition.id   '_identifier_set.description'
       _definition.class  Attribute
       _definition.update 2011-01-27
       _description.text
;
       A description of the identifier_set
;
       _name.category_id identifier_set
       _name.object_id   code
       _type.purpose     Describe
       _type.container   Single
       _type.contents    Text


      save_

save_ALIAS_IDENTIFIER_SET

      _definition.id      alias_identifier_set
      _definition.scope   Category
      _definition.class   List
      _definition.update  2011-01-27
;
       The attributes used to specify the identifier_set of
       tags to which a given tag belong.

       A given tag may belong to multiple identifier_sets
       and may be cited against multiple dictionaries.

       Note that _alias_identifier_set.identifier_set_id is a
       component of the key of ALIAS_IDENTIFIER_SET.  If the
       denormalized join presentation is used to bring the object
       ids of this child category up into the parent
       ALIAS category, then _alias.identifier_set_id will
       we used as an implicit addition to the key of
       the denormalized ALIAS category.

       Until DDLm can be formally revised to automatically
       handle the necessary promotion of child catgeory keys
       in denormalized joins, a place-holder
       _alias.identifier_set_id has been defined in the
       ALIAS catgeory.

;
      _category.parent_id  alias
      _category.parent_join  Yes
      _category_key.primitive  ['_alias_identifier_set.identifier_set_id',
                                '_alias_identifier_set.definition_id',
                                '_alias_identifier_set.xref_code']
       save_

save_alias_identifier_set.definition_id
       _definition.id   '_alias_identifier_set.definition_id'
       _definition.class  Attribute
       _definition.update 2011-01-27
       _description.text
;
       Together with _alias_identifier_set.xref_code, identifies
       an alias belonging to an identifier_set.  An alias may
       belong to any number of identifier_sets, including zero.

;
       _name.category_id alias_identifier_set
       _name.object_id   definition_id
       _name.linked_item_id  '_alias.definition_id'
       _type.purpose     Key
       _type.container   Single
       _type.contents    Tag
        save_

save_alias_identifier_set.identifier_set_id
       _definition.id   '_alias_identifier_set.identifier_set_id'
       _definition.class  Attribute
       _definition.update 2011-01-27
       _description.text
;
       Identifies an identifier_set to which the alias
       identified by _alias_identifier_set.definition_id
       and _alias_identifier_set.xref_code ) belongs.

       A pointer to _identifier_set.id
;
       _name.category_id alias_identifier_set
       _name.object_id   code
       _name.linked_item_id  '_identifier_set.id'
       _type.purpose     Key
       _type.container   Single
       _type.contents    Code

      save_


save_alias_identifier_set.xref_code
       _definition.id   '_alias_identifier_set.xref_code'
       _definition.class  Attribute
       _definition.update 2011-01-21
       _description.text
;
       A code identifying the actual dictionary,
       virtual dictionary or other logical grouping
       to which the identifier tag belongs.


What is this identifier tag - '.definiton_id' or '.definiton_set_id'?

;
       _name.category_id alias_identifier_set
       _name.object_id   code
       _name.linked_item_id  '_dictionary_xref.code'
       _type.purpose     Key
       _type.container   Single
       _type.contents    Code
        save_




We also need to refined the _dictionary_xref category.  '.uri; should be
added, '.format' should be better derfined or deleted.  Perhaps '.version'
should also be added.  Definining the dictionaries is just as important as
definiting the definition_sets

David




_______________________________________________ ddlm-group mailing list ddlm-group@iucr.org http://scripts.iucr.org/mailman/listinfo/ddlm-group



begin:vcard
fn:I.David Brown
n:Brown;I.David
org:McMaster University;Brockhouse Institute for Materials Research
adr:;;King St. W;Hamilton;Ontario;L8S 4M1;Canada
email;internet:idbrown@mcmaster.ca
title:Professor Emeritus
tel;work:+905 525 9140 x 24710
tel;fax:+905 521 2773
version:2.1
end:vcard

_______________________________________________
ddlm-group mailing list
ddlm-group@iucr.org
http://scripts.iucr.org/mailman/listinfo/ddlm-group

Reply to: [list | sender only]