Discussion List Archives

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

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

What is the harm in an unused item remaining around forever?  There
is very real harm if we confuse people writing code about what
is or is not in the spec.  I would suggest we err on the side of
caution and assume that there are people who have read and used what
has been posted since 2007, and try to communicate with them
very, very clearly.  I have had some deprecated items in the
imgCIF dictionary for a decade, and they still crop up often
enough that I have automatic conversions built into some of
my software. -- 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:

> 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
> 
> 
> 
> 
> 
>
_______________________________________________
ddlm-group mailing list
ddlm-group@iucr.org
http://scripts.iucr.org/mailman/listinfo/ddlm-group

Reply to: [list | sender only]
International Union of Crystallography

Scientific Union Member of the International Council for Science (admitted 1947). Member of CODATA, the ICSU Committee on Data. Member of ICSTI, the International Council for Scientific and Technical Information. Partner with UNESCO, the United Nations Educational, Scientific and Cultural Organization in the International Year of Crystallography 2014.

ICSU Scientific Freedom Policy

The IUCr observes the basic policy of non-discrimination and affirms the right and freedom of scientists to associate in international scientific activity without regard to such factors as ethnic origin, religion, citizenship, language, political stance, gender, sex or age, in accordance with the Statutes of the International Council for Science.