[Xerte] Developer documentation

[Dave Burnett]

European or African?

> Subject: RE: [Xerte] Developer documentation
> Date: Thu, 14 May 2009 13:55:58 +0100
> From: Patrick.Lockley at nottingham.ac.uk
> To: xerte at lists.nottingham.ac.uk
> 
> Hello,
> 
> First off
> 
> There are two xertes. To filter some mud from the water.
> 
> Desktop Xerte - A developer tool flash based application that can run on
> a windows PC to develop flash and xml to be deployed on a web server.
> This is the EXE Version. The exe version does not have a database. It is
> completely separate and does not care about the Xerte Online Toolkits
> version. Honestly, it never writes or anything. They can be used
> completely separately.
> 
> (Just in case cross wires by exe, I don't mean eXe, but executable.)
> 
> Xerte Online Toolkits - A web based version of the Xerte wizards feature
> available to people working directly on a web server. This is at present
> its usage. The site is however almost completely modularized and could
> support other versions of other templates if someone wants to. I think
> only the export functions aren't modularized. 
> 
> Bringing together a few emails into one
> 
> 1) The reason we don't have a full GPL license is (at the moment)
> because I wanted to explicitly offer my personal thanks to the
> developers of the three other PHP scripts that help the site work. To
> many open source projects just bring together loads of other code and
> pass it off without proper attribution. On the first page of the
> installer it does thank these people. One of these pieces of code also
> lacks a license (he just wants you to send him a copy of what you do),
> so I am not sure legally if we can offer it as GPL anyways. We could
> possibly remove this code from the install and offer a guaranteed GPL
> version, but we'd lose some functions and have two installers to deal
> with.
> 
> 2) There are no instructions for any one downloading from the SVN as to
> what the database script code is, where it is and how to apply this.
> 
> Correct, but there is an installer and a set up folder containing a file
> called basic.sql which does the vast majority of the database creation
> (it could be run separately with some minor mods). There isn't a script
> to do this generically (if you ignore the fact that the installer does
> all of it) as some of the database settings are specific to each
> install.
> 
> If you want to install toolkits, I would suggest downloading the
> installer from http://www.nottingham.ac.uk/xerte rather than using the
> SVN. You can run a local version very easily if you're on a PC by
> choosing the XAMPP installer. If you're not using a localhost install,
> you can choose the full install option. There is someone at Loughborough
> who has done this already and I am guessing you know who so he may be
> able to demo?
> 
> We have worked on the basis that to encourage the use of the project an
> installer makes more sense than forcing people to work out which bits of
> code to change here and there. So far we've had no really complaints
> about the installer, and most people appear to have installed it without
> any issues.
> 
> 3) In addition have you any coding standards that are being followed. I
> ask only because I have noted that you are using the abbreviated php tag
> (<?) rather than the more commonly accepted tag (<?php).
> 
> True, although in my defence and to counter any accusations of laziness,
> I didn't realise this was a problem until I pretty much finished the
> installer (I was working on the basis long tags are a bit obsolete). The
> project has gone through a variety of phases, and a lot of the initial
> work was done before it moved to become open source. So this is somewhat
> of a legacy admittedly, but it is only a matter of doing a find and
> replace on the files.
> 
> As for standards......
> 
> 4) I too am a fan of the phpdoc standard, built in a similar manor to
> the Javadoc. As for Xerte from examining the code the use of this is
> sporadic
> 
> As for this, other than 1-2 pages where I know the commenting isn't
> ideal, I spent two whole weekends commenting up the code to phpdoc
> standard. I've even done the javascript to the same standard (even
> though it was futile as JS DOC uses some XML format instead). If they
> aren't at PHP doc standards, then I have no plans to change them as I
> will be shooting myself to get over how stupid I'll feel.
> 
> I don't have any code standards or preferences, other than to keep to
> PHPdoc now I erm have done it, try to comment every If statement (give
> or take a few where its obvious). I've spent too much time myself bogged
> down in open source code that basically isn't as its written badly and
> without comments. I've tended to use very basic code and simple
> functional patterns so as to make the code as modifiable and
> customisable as possible.
> 
> I would be surprised if someone said the Xerte Online Toolkits code was
> awkward. I've been pretty anally retentive in terms of file names,
> naming conventions and folder structures. The website_code folder
> contains all the website code, in side that are folders called php,
> scripts, styles.... Admittedly it's not a guide per say, but I would say
> its fairly obvious. As to finding out what calls what - I recommend
> fiddler. It is amazing.
> 
> I've attached a presentation I gave on the code workings. I think it
> might cover some of the points you've raised.
> 
> Is anyone still reading? Spot quiz time? What is the air speed velocity
> of a swallow?
> 
> In terms of contributions from other users, so far it's mostly been bug
> fixes (we release a weekly list of fixed bugs and modifications - this
> week is free of them so far), but we have received 4 or 5 changes from
> organizations and colleges where the system is running.
> 
> Every time I have fixed an individual bug, I have offered to that person
> scope for the creation of a Xerte Online Toolkits developer's list / sys
> admin list, or a desire for increased developer documentation. 
> 
> No one has ever replied.
> 
> As a developer, I could go write the manuals, but in terms of sheer
> pragmatism, do people think the time spent on that would be commensurate
> with the resources returned?
> 
> I would love to think people would be interested in doing so, but would
> prefer to establish some sort of steering group before continuing to
> create documentation. And also as the benevolent dictator (though I'd
> see it more as anarchist) I find it hard to work out what people want as
> often I fix things and hear nothing more. I wrote in a load of extra
> code to make moodle integration possible, and then when we did moodle
> integration we took it all out again. Nice.
> 
> If you'd be interested (or anyone else still here) would be interested
> in this then I would be keen to work towards something.
> 
> Apologies for the essay, and it's far too large for me to proof read. So
> I'll call this reply open source and people can correct my spelling at a
> later date.
> 
> Thanks for the interest though. I am grateful for all feedback.
> 
> Pat
> 
> 
> 
> 
> 
> 
> 

_________________________________________________________________
Hotmail® has a new way to see what's up with your friends.
http://windowslive.com/Tutorial/Hotmail/WhatsNew?ocid=TXT_TAGLM_WL_HM_Tutorial_WhatsNew1_052009
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.nottingham.ac.uk/pipermail/xerte/attachments/20090514/a430fcff/attachment.html