[Gramps-devel] GEPS023 merged into trunk

[Tim L. <guy...@gm...>]

I am pleased to announce that commit 18548 merges GESP023 into trunk.


This means that databases will be upgraded to the new citation format  
when using the latest trunk. You may need to remove the ini files in  
your .gramps directory for Gramps to work properly. There are  
something like 160 files changed, so no doubt there may be some  
anomalies noticed. As always, you should backup your database before  
running the new trunk and getting your database upgraded, and should  
not use it for production work.

There are a few known issues which are documented in the wiki:
http://www.gramps-project.org/wiki/index.php?title=GEPS_023:_Storing_data_from_large_sources#Known_Issues
so before reporting any problems, please be sure to check the list of  
known issues. The issues include a few imports/exports (ProGen, FTree,  
Grdb), simple report support, some webapp modules, and tool/Check.  
However, I do not believe that these issues should prevent normal use  
of trunk.

I would like to thank Nick Hall for the enormous help and  
encouragement I have received from him, especially in implementing the  
tree model for two different primary objects which is largely his  
code. Without his help, this enhancement would not have been possible.

Also thanks for help, testing and support from Michiel Nauta (advice  
on upgrade transactions), John Ralls (fixes to some make files),  
Jerome Rapinat (fixes to translation files etc.), Benny Malengier  
(advice on upgrade), Brian Matherly (svn admin), Rob Healey, Gary  
Burton, Doug Blank and Cedric Scott and everyone else whose names I  
may have missed.




On 28 Nov 2011, at 13:43, Doug Blank wrote:

> If we are going to merge GEPS023 into trunk, it would also be
> convenient to do this sooner rather than later so that those of us
> that have time over the winter break/holiday seasons will be able to
> update related code, and test.
>
> Tim, as part of this transition, it would be quite useful to have a
> brief summary of the changes to the database, and how data is mapped
> to the new structures.
>
> -Doug

The user interface has been designed on the principle that Aunt Martha  
should not need to know or even be aware that citations have changed.  
Hence she will see a Source navigation with similar information to the  
current view. There will be a disclosure triangle, but she can ignore  
that. When she wants to add a source to a person or event, she clicks  
on the add or add existing button, and gets a similar choice of source  
as at present. (Again she can ignore the disclosure triangles). The  
editor that appears is then very similar to the existing editor. Only  
if a user particularly wants to share citations between objects do  
they need to be aware of the change. The change is also intended to be  
entirely compatible with GEDCOM.

Simple access to, and updating of, citations or sources does not  
involve very extensive changes to existing code. The database changes,  
the various editors, filters and proxies etc. have involved more  
extensive changes.

The Citation primary object corresponds pretty closely to the  
SourceRef secondary object. Data in the SourceRef is mapped to the  
Citation. A Citation has the additional possibility of having media  
objects attached (which is not possible with SourceRefs). A Citation  
points to exactly one Source (the code may assume that here is always  
a source object present).

The 'shape' of existing objects is unchanged. The change is that  
SourceBase is replaced by CitationBase.

For creating data, where you previously created a SourceRef, you now  
create a Citation object, and set_reference_handle() to point to the  
Source object. There is a difference that you then have to do a  
db.add_citation(citation, transaction). You then do an  
obj.add_citation(citation_handle) instead of an  
obj.add_source_reference(sourcerefobj) to add the SourceRef/Citation  
to the object.

An example of the changes is:
http://gramps.svn.sourceforge.net/viewvc/gramps/branches/geps/gep-023-large-sources/src/plugins/lib/libgedcom.py?r1=18405&r2=18415


As far as data access is concerned, you do obj.get_citation_list()  
instead of obj.get_source_references() to get a list of Citation  
handles/SourceRefs respectively. With the citation, you then need to  
do a db.get_citation_from_handle(citation_handle). Having got the  
object, you do get_reference_handle() to get the source object handle.

An example of the changes is:
http://gramps.svn.sourceforge.net/viewvc/gramps/branches/geps/gep-023-large-sources/src/plugins/export/ExportGedcom.py?r1=18405&r2=18408


Note 1. The names of the functions and the return values are mostly  
chosen to match the way notes are attached to objects, so  
obj.add_citation(citation_handle) corresponds with add_note - both  
taking handles as parameters, and obj.get_citation_list() corresponds  
with get_note_list() - both returning handles.

Note 2. I am aware of PEP 8 and pylint and have followed them for new  
code. However, where I have just been modifying existing code, or have  
largely copied some existing code, I have retained the style of the  
existing code, for example in terms of code layout, naming conventions  
and the number of parameters or methods in a class. This may result in  
a lowered pylint score.

[N.B. This is only a guide, no guarantee!]