Image Markup Tool blog

The version information data is crucial for completing the <teiHeader> in a useful way, and I've been puzzling over how best to do it in an automated way. Following hints from this post: http://qtcreator.blogspot.com/2009/10/generating-automatic-version-numbers.html, I've written a bash script that creates a version.h header file, which provides all the key versioning info I'll want to include. Below is the script at the moment (it will probably get a bit more complicated later). I'll also want to figure out how to include the same info into a resource file in order to embed the correct versioning info into Windows builds, based on this post: http://stackoverflow.com/questions/2784697/setting-application-info-in-qt. I run the script automatically when doing a build, to get an up-to-date version.h file. This is done using a Custom Build Step in the Build Settings panel of QT (in "Projects").

#!/bin/bash

#Major version number (unlikely to change).
major=2

#Minor version number is changeable, but done manually.
minor=0

#Build number is yyyymmdd from today.
date=$(date +%Y%m%d)

#This is the file we're dealing with.
outfile="version.h"

#Remove the old file.
rm $outfile

#Do an SVN commit to update the revision number.
svn commit --message "Committing before an application build."

#Get the SVN revision number into a variable.
svnrev=`svnversion`

#echo the info into the output file.
#echo $svnrev>>$outfile
#echo $major"."$minor"."$build"."$svnrev>>$outfile

echo "#ifndef VERSION_H">>$outfile
echo "#define VERSION_H">>$outfile
echo "">>$outfile
echo "namespace Version">>$outfile
echo "{">>$outfile
echo "const int MAJOR = "$major";">>$outfile
echo "const int MINOR = "$minor";">>$outfile
echo "const int DATE = "$date";">>$outfile
echo "const int REVISION = "$svnrev";">>$outfile
echo "}">>$outfile
echo "inline const char* versionString(){return "$'\042'$major"."$minor"."$date"."$svnrev$'\042'"};">>$outfile
echo "">>$outfile
echo "">>$outfile
echo "">>$outfile
echo "#endif // VERSION_H">>$outfile

This is part of making it easier to access and manage ImtLinkGrp and ImtLink objects by using a QString key. The key in this case is the linkType attribute, which we want to ensure is unique anyway.

Centralized the generation of hash values for links into a static class method of ImtLink, so that it can be called from other classes, and so that it's easy for me to tweak it if necessary. Previously there was a possibility that two different pairs of ids could accidentally result in the same hash, but I've fixed that by adding some wrapper characters.

Spent an hour working on the documentation of the core classes, running Doxygen repeatedly and fixing the errors that showed up. I think I have my documentation practices pretty much organized now, so I'll be able to go back and document the earlier parts of the project (the ones that will survive into the application).

Rewrote ImtLinkGrp so that it stores its ImtLinks in a QHash instead of in a QSet. In some ways this is more complicated, but it's a bit more robust, and enables quicker and easier lookup of a link. Modifications were needed to the ImtLink class as well.

Next is the similar task of rewriting ImtLinkSet in the same way. The advantages are more obvious and immediate there.

I've added more methods for finding and checking the existence of links in link groups and sets, and for changing the link type of a link (by moving it from one group to another). I've made other minor tweaks to code and documentation.

However, I'm beginning to question one core decision in the ImtLinkGrpSet class. I don't think that the linkGrps member should be a QSet; I think it should be a QHash. The key should be the linkType value, giving me easy access to the linkGrp and its links through the type string, and ensuring its uniqueness, which is essential. This would require substantial refactoring, but I think it's worth it.

It's also worth thinking about making the links member of the linkGrp class a QHash as well, using a concatenation of the target zone id and target text id as the key. This would have similar advantages; it would then be very easy to get a pointer to a link with its core information. I think this will be my next task.

Moved assignments in constructors into initialization lists where possible, for efficiency and speed. Also added new functions for finding a linkGrp by its linkType, and added getAllLinkTypes method to ImtLinkGrpSet, as preparation for assignment of new links to groups, and moving of links from group to group.

Reliable tracking of the "modified" (aka "dirty") status of data objects, especially those in hierarchies, is important. I've now implemented the system I outlined in the earlier post, with modified status appropriately migrating up or down the tree so that it can easily be determined at any point. I've also started writing more careful testing code.

One issue I haven't yet faced, but I'm beginning to think about, is how to manage changes such as the linkType property of a link element. I can't simply allow that to be changed, because a link may be part of a linkGrp, and in that case the linkGrp would manage the linkType; and in turn, the change of linkType actually represents a move of the link from one linkGrp to another, which itself ought to be managed at the level of the linkGrpSet. I could actually remove the linkType attribute from links altogether, on the basis that in this project, I'm never going to allow that to be used in the context of the link itself or the linkGrp, but only at the level of the linkGrpSet, but that would be rather inflexible; and it does, somehow, seem to be a property of the link when considered from the user's point of view (as it is in the current IMT, where it's shown as a category).

All this needs careful thought before I commit to a strategy.

Added a color property and a property which is an enumeration {NONTRANSCRIPTIONAL, TRANSCRIPTIONAL} to handle the need to set the outline color for a <zone> and the possible need to output @corresp and @facs attributes in addition to <linkGrp>s.

I've also been working on plans for handling the "modified" property for this collection of classes. Ideally, I want to be able to interrogate the ImtLinkGrpSet object to get the modified state of everything below it, but I also want to be able to set modified at any level rather than going through the hierarchy, so I'm thinking of a setModified() method for all the objects which checks to see if it has a parent; if it does, and the new setting is true, it calls the parent's method instead (thus causing true to propagate up to the top level), but if it's false, it just sets its own modified property, and all those of its children. This means I should be able to read and write at any level and get the required behaviour -- assuming that I always try to read at the highest level. Setters at every level can affect the tree upwards and downwards, depending on whether the value is true or false. It's confusing when you try to explain it, but it will work (I've done something similar, but not as well planned, in Delphi code).

Added a caption attribute to the ImtLinkGrp class. This is the human-readable caption for the link group (as opposed to the QName-style identifier linkType), and is stored in the @n attribute of the <linkGrp> tag (TEI defines this vaguely as an identifier or label, so it seems reasonable).

TODO: make the linkType attribute conform to QName constraints.