ChEeTaH's (NL) blogs

Sims Programma's nu Open Source!

ChEeTaH — Tue, 10 Aug 2010 21:05:37 +0000

Het is een aardige tijd geleden dat de Sims community actief bezig was met the Sims 1. In die tijd heb ik twee programma's geschreven voor het spel: The Neighborhood Handler en The Add-on Handler. Bijna drie jaar geleden besloot ik de broncode van deze twee beschikbaar te maken onder de GPL2 licentie. Er is nogal wat tijd overheen gegaan en de broncode was openbaar beschikbaar, maar dat had ik nooit aangekondigd. Tijd om dat te veranderen: bij dezen dus die aankondiging (en meer)!

The Neighborhood Handler en The Add-on Handler zijn nu dus open source software! Ik moet zeggen dat ik de code niet heb opgeschoond of wat dan ook; het is niet veel meer dan een dump van de code die ik al die jaren geleden geschreven heb. Ik moest het nog leren destijds, dus ik neem aan dat het vol zit met bugs, slechte code en andere nachtmerries. Mocht iemand het echter willen oppakken om een van deze twee projecten te verbeteren (of te herschrijven), dan kan dat nu. Als je gewoon een kijkje wilt nemen: dat kan nu ook.

Wat betreft The Neighborhood Handler: ik heb een kleine herstart gemaakt voor een nieuwe versie (nog steeds C++, maar gebruik makend van Qt voor de interface). Alhoewel ik er nog niet heel veel tijd in heb kunnen steken, is de code wel beschikbaar voor wie er dan ook mee wilt werken.

Er is ook iets handigs voor de makers van Sims 2 content: ik heb aardig wat werk in een Sims 2 Packer gestoken, waarmee je de bekende .package bestanden kunt inpakken voor de Sims 2 (naar de bekende .Sims2Pack bestanden). Dit project is mogelijk ook nuttig als basis voor een vergelijkbaar Sims 3 programma, omdat het bestandsformaat redelijk overeenkomt. Ik ben er nooit aan toe gekomen om dit project af te ronden en te publiceren, maar wellicht is het wel nuttig voor iemand.

Voor alle open broncode, waaronder ook nog Drupal projecten en andere programmaatjes die ik lang geleden heb gemaakt: bezoek mijn publieke git repositories. Als je alleen geïnteresseerd bent in de bovengenoemde projecten, ga naar:

TheNeighborhoodHandler repository (zie de 4.1 branch voor de oude versie, of de master branch voor de nieuwe nog-bijna-niets- gedaan versie)
TheAddonHandler repository
libSims2Pack repository
Sims2PackerUI repository (vereist libSims2Pack)

De oude software heeft Borland C++ Builder nodig om gebakken te worden. Het nieuwere spul (de nieuwe versie van The Neighborhood Handler, libSims2Pack en Sims2PackerUI) gebruiken CMake als build system en is afhankelijk van Qt (beide zijn gratis te downloaden). Je kunt de Qt Creator gebruiken om al die code te compileren en te debuggen.

Let wel op dat dit allemaal niet echt nuttig is als je de tools direct wilt gebruiken en niet geïnteresseerd bent in de daadwerkelijke broncode. Ik heb momenteel geen (recente) binaries/installaties beschikbaar. Je kunt The Neighborhood Handler en The Add-on Handler nog wel op The Sims Zone vinden.

Neem gerust contact met mij op als je vragen hebt over de code, of als je de ontwikkeling van een of meer van deze projecten wilt voortzetten: ik kan schrijfrechten geven op de repositories als je serieus verder wilt gaan. Het is niet waarschijnlijk dat ik binnenkort iets met deze code ga doen.

Al met al is dit vooral verouderd spul, maar toch hoop ik dat iemand het nuttig vindt!

Drupal Ontwikkeling eenvoudiger met de Qt Assistant - Deel 3b

ChEeTaH — Tue, 10 Aug 2010 20:03:34 +0000

Weet je nog hoe we de vorige keer Doxygen commentaar in Drupal dusdanig verwerkte, zodat het ook in de uitvoer van Doxygen er goed uit zou zien? Tijd voor een nieuw deel in de serie, en we gaan nog even door met reparaties. Moet je de boel nog goed opzetten, omdat je de eerdere delen misschien gemist hebt? Lees dan eerst delen 1, 2 en vooral 3a voordat je verder gaat. Deze keer: het werkend krijgen van speciale HTML documentatie zoals de Forms API. Beginnen maar!

Het probleem

In de Drupal documentatie worden alle links, inclusief die naar andere pagina's, gemaakt met behulp van het @link commando. We hebben eerder al de externe en Drupal-specifieke links gerepareerd. Onze Doxygen documentatie bevat echter nog steeds sommige onderwerpen niet omdat Doxygen HTML files niet zomaar oppikt of toevoegt. Vanwege de manier waarop Doxygen alles verwerkt, blijven de gedefinieerde links wijzen naar iets dat niet bestaat. De links werken dus niet, en we hebben de documentatie niet bij de rest zitten.

We kunnen natuurlijk gewoon de links aanpassen en naar de externe pagina's op api.drupal.org laten wijzen. Maar zou het niet beter zijn als we alle documentatie op dezelfde plek hebben? Daar gaan we nu voor zorgen!

Meer preprocessen

Herinner je dat we in onze preprocessor wat ruimte hadden overgelaten voor HTML verwerking? We gaan nu een HtmlPreprocessor toevoegen. Later zorgen we ervoor dat Doxygen de HTML bestanden ook meeneemt. Met onze speciale preprocessor zorgen we dat Doxygen de HTML pagina's maakt en toevoegt. Vervolgens kunnen we daar naar linken ook al passen we de links niet aan.

Eerst wat structuur. Open het preprocess-drupal-doxygen.php bestand in je teksteditor of IDE. Onder de CodePreprocessor klasse, voeg je het volgende skelet toe:

class HtmlPreprocessor extends Preprocessor {
  private $_basename = ''; /**< The basename of the filename */
 
  public function __construct ($filename) {
    Preprocessor::__construct($filename);
    $this->_basename = basename($filename);
  }
 
  protected function doProcess($contents) {
    // We will go and fill this in soon...
  }
}

De constructor hebben we al gemaakt, die slaat de basisnaam van het bestand dat we verwerken op (dat is de bestandsnaam zonder pad of directory-informatie). Dat hebben we verderop nodig. De doProcess() functie is er ook al bij, maar heeft nog wat inhoud nodig.

Vergeet niet dat de $contents variabele het hele HTML document opslaat. Dit is inclusief headers, rommel op het eind en nog veel meer. Maar voor toekomstige handigheid, of zelfs voor je eigen projecten, wil je misschien een simpele HTML pagina met alleen de inhoud maken. Dat bestand zelf is dan misschien geen correcte HTML, maar dat komt wel goed als we het in Doxygen zetten. Wat de invoer ook is, we gaan het zo goed mogelijk vewerken.

Vissen naar de titel

Het eerste deel van de doProcess functie haalt de titel uit het document. Bij voorkeur staat deze in een <title> tag. Maar als we geen header hebben en deze tag niet bestaat, willen we misschien zoeken in tags als <h1> tot en met <h6>. Voor elk van deze tags kijken we of die in het document voorkomt en niet leeg is. We pakken de inhoud van de tag en zorgen dat alles op één regel staat. Mocht het document dan de regel midden in de titel afbreken, dan schopt dat onze documentatie niet in de war.

Als er geen tags gevonden worden, vallen we terug op de oorspronkelijke bestandsnaam. Hiermee krijgen we dus de volgende code, waarvan de reguliere expressie is geïnspireerd op code uit de Drupal API module:

    // Find title in the first listed tag that's in the file
    $title = NULL;
    $titleTags = array('title', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6');
    foreach($titleTags as $tag) {
      $titleMatch = array();
      if (preg_match('@<' . $tag . '(\s.*?)?>\s*(\w.*?)\s*</' . $tag . '\s*?>@is', $contents, $titleMatch)) {
        $title = str_replace("\n", " ", $titleMatch[2]); // Make sure it's all on one line
        break;
      }
    }
 
    if (!isset($title)) {
      $title = $this->_basename;
    }

En de rest?

Nu de daadwerkelijke inhoud. We hebben twee gevallen, zoals eerder beschreven: geval één is dat het bestand een volledige HTML pagina is (inclusief header enzovoorts, en de erg belangrijke <body> tag), of we hebben een wat rommeliger document met alleen de inhoud zelf (zonder <body> tag).

Wat doen we dan? Zoals hierboven ook gedaan is, gaan we de inhoud van de <body> tag proberen te pakken te krijgen. Vinden we niks, dan pakken we gewoon het hele bestand:

    // Get <body> of HTML, if present (otherwise use whole document)
    $bodyMatch = array();
    if (preg_match('!<body(\s.*?)?>(.*)</body(\s.*?)?>!is', $contents, $bodyMatch)) {
      $contents = $bodyMatch[2];
    }
    $contents = str_replace("\n", "\n * ", $contents);
    $contents = preg_replace('!([@\\\\])endhtmlonly!', '\\1<span>endhtmlonly</span>', $contents);

De op een na laatste regel springt elke regel in met " * ". Doxygen haalt dit weer weg uit z'n uitvoer. Maar waarom doen we dat dan? Stel dat het HTML document ergens een regel heeft die begint met " * ", dan willen we dat behouden in de uitvoer. Door deze inspringing toe te voegen, verwijdert Doxygen alleen het extra toegevoegde deel en niets anders.

Een ander probleem is dat het document het Doxygen commando @endhtmlonly kan bevatten. Zoals je later zult zien, kan dit problemen veroorzaken omdat het ons @htmlonly blok, waarmee we hieronder de HTML code letterlijk zullen invoegen, zal afbreken. Let op dat in dit blok alleen het @endhtmlonly door Doxygen herkent wordt. Het escapen van het commando heeft geen zin, dus we gaan het een beetje "slopen" waar het ook voorkomt. Dit doen we door het endhtmlonly deel in een (verder nutteloze) <span> tag te zetten. Je ziet geen verschil, maar Doxygen ziet @<span>endhtmlonly</span> en blijft doorgaan met het uitspugen van letterlijke HTML code. Succes gegarandeerd!

Het laatste probleem dat we hebben is dat er nog referenties naar andere documenten te vinden is. De Forms API Quickstart en Forms API Reference wijzen bijvoorbeeld naar elkaar, door middel van absolute links naar api.drupal.org. Het werkt, maar we hebben alle documentatie al in Doxygen, dus waarom kunnen we niet daar naartoe linken?

We gaan dus wat links vervangen. Voeg de volgende functie toe aan de HtmlPreprocessor:

  private function replaceLinks($contents, $links) {
    foreach($links as $original => $new) {
      $re = '/(<a\s+[^>]*)href=(["\'])' . str_replace('/', '\/', $original) . '(\/\S*)?\\2/si';
      $contents = preg_replace($re, '\\1href=\\2' . $new . '\\2', $contents);
    }
    return $contents;
  }

Deze functie zoekt links op die we in de $links array meegeven (als array sleutels), en vervangt deze met de bijbehorende waarde uit de array. Ook langere URLs worden meegenomen, als de URL verder gaat met een slash en dan de rest. Gevolg is dat een link naar http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 verandert in gewoon forms_api_reference.html als we de functie als volgt aanroepen (voeg dit toe aan de doProcess() functie):

    $contents = $this->replaceLinks($contents, array(
      'http://api.drupal.org/api/file/developer/topics/forms_api.html' => 'forms_api.html',
      'http://api.drupal.org/api/file/developer/topics/forms_api_reference.html' => 'forms_api_reference.html',
      'http://api.drupal.org/api/file/developer/topics/javascript_startup_guide.html' => 'javascript_startup_guide.html',
    ));

Nu de belangrijkste stap: een Doxygen commentaarblok maken en de HTML code invoegen. We geven Doxygen wat documentatie over het bestand zelf, en maken daarnaast een Doxygen pagina met wat HTML inhoud. Dit gebeurt met het volgende blok:

    $contents = "/**\n"
              // Clone page's documentation in File listing
              . " * @file\n"
              . " * @brief @link {$this->_basename} {$title} @endlink\n"
              . " * \n"
              . " * This file contains a special documentation topic: @link {$this->_basename} {$title} @endlink.\n"
              . " */\n"
              // Create custom page
              . "/**\n"
              . " * @page {$this->_basename} {$title}\n"
              . " * \n"
              . " * @htmlonly\n"
              . " * " . $contents . "\n"
              . " * @endhtmlonly\n"
              . " */\n";
    return $contents;

Het enige probleem dat hier over blijft is dat de documentatie van het bestand, als je via de bestandenlijst van Doxygen gaat, niet de documentatie zelf bevat. In plaats daarvan is er alleen een verwijzing naar de eigen pagina die gemaakt is, waar wel alles staat. Als je dat prettiger vindt, kun je de drie regels vanaf @htmlonly tot @endhtmlonly kopieren naar de bestandsdocumentatie. Je moet echter de andere pagina laten staan, anders zullen de (ongewijzigde) links naar de pagina niet werken.

Je kunt nu naar de documentatie waar je maar wilt met behulp van het Doxygen commando @link (bijv. "@link bestand.html Mijn Link Tekst @endlink").

Er is nog een laatste ding dat onze preprocessor moet doen: de HtmlPreprocessor maken en gebruiken. Als je het script van de vorige keer hebt gebruikt, zoek dan de regel (vrij ver onderaan) op, waar staat // HTML Processing is for later.... Gevonden? Vervang deze regel met de volgende:

$processor = new HtmlPreprocessor($filename);

Dat is alles voor de preprocessor. Als je ergens de weg kwijt bent geraakt, kun je het hele script hieronder downloaden. Alle code is overigens GPL v2 code, dus voel je vrij om het aan te passen, te hergebruiken en verder te verspreiden.

Maar Doxygen leest nog steeds geen HTML bestanden!

Nu de preprocessor helemaal klaar is, kunnen we Doxygen de HTML bestanden laten gebruiken. Dit is relatief eenvoudig: eerder lieten we Doxygen alleen maar .php, .inc, .module en .install bestanden voor Drupal verwerken. Voeg gewoon .html (en eventueel andere extensies die je gebruikt) toe aan de FILE_PATTERNS lijst (Input onderdeel) in de Doxywizard. Voer Doxygen uit, en de documentatie wordt netjes toegevoegd. Voor de Drupal documentatie kun je dit gelijk zien op de hoofdpagina met onderwerpen. Als alles klopt, werkt alles zoals verwacht.

Samenvatting

In deel 1 hebben we het systeem klaargemaakt, in deel 2 hebben we de Drupal documentatie in de Qt Assistant gezet. Nu hebben we fouten in de documentatie opgelost met wat eigen code uit deel 3a en dit deel. Vorige keer hebben we wat verschillen tussen de Drupal API module en Doxygen wat betreft het verwerken van commando's gecorrigeerd, zodat de Doxygen uitvoer overeenkomt met die van de module. Deze keer hebben we de code uitgebreid om geavanceerde onderwerpen uit HTML pagina's toe te voegen.

Er is nog een laatste probleem. Alle documentatie, van Drupal core en alle modules, is op een grote hoop gegooit. Vaak is het echter wel prettig om de documentatie van een specifieke module te bekijken. Qt Assistant ondersteunt dit door ons een selectie van documentatiecollecties te tonen (en dat kan de hele bundel zijn, zoals nu). Hoe? Dat lees je binnenkort.

Drupal Ontwikkeling eenvoudiger met de Qt Assistant - Deel 3a

ChEeTaH — Tue, 27 Jul 2010 09:20:11 +0000

Welkom terug! Het is een tijd geleden sinds ik deel een en twee van deze serie heb gepost (ja, ik moet vaker bloggen...). Weet je nog dat ik de Drupal documentatie in de Qt Assistant, een handige viewer voor documentatie, aan het zetten was? Mooi. Ik heb goed nieuws: ik heb weer wat tijd gestoken in het in orde krijgen van de documentatie. Dus we gaan gelijk door!

Plan voor vandaag

In deel een hebben we ons systeem voorbereid en de nodige tools klaar gemaakt voor het werk. In deel twee kregen we de documentatie daadwerkelijk in de Qt Assistant, alhoewel er nog layout problemen waren zoals je misschien wel gemerkt hebt.

Nadat we de veranderingen in de Drupal documentatie sinds de vorige keer weer opgepakt hebben, zoomen we nu in op (Drupal specifieke) problemen in de gegenereerde documentatie. Hierbij hoort vooral het terughalen van tekst die verloren gaat in het Doxygen proces, door de code vooraf te "preprocessen." Dit is subdeel A, binnenkort krijgen we ook de specifieke onderwerpen (zoals de Forms API referentie) aan de praat in deel 3B.

Veranderingen sinds de vorige keer

Sinds de vorige keer zijn er enkele dingen veranderd in de bronnen die we gebruiken. Ook al gebruik ik nu een andere Linux distributie, lijkt het erop dat de Doxygen templates een make-over hebben gehad: je documentatie ziet er nu nog beter uit met de nieuwste versie. Alles heeft een wat moderner jasje, wat ik goed vind. Je wilt denk ik je software (Doxygen en Qt) even bijwerken naar de nieuwste versies als je dat niet al gedaan hebt, gewoon voor de handigheid.

Een belangrijkere aanpassing is echter dat de Drupal Developer Documentatie op CVS niet meer de voorbeelden bevat. In plaats daarvan zijn ze vehruisd naar een eigen project. Je kunt een snapshot van de geschikte versie downloaden en in je developer subdirectory uitpakken (waar je Drupal Developer Documentatie staat). Een andere handige optie is om de voorbeelden ook van CVS te halen (zie "Checking out from the contributions repository" voor gedetailleerde instructies):

cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -d developer/examples contributions/modules/examples

Vergeet niet je developer documentatie ook bij te werken naar de laatste versie. Met name als je Drupal 6 gebruikt, wil je vast ook even de goede branch selecteren, als volgt (vanuit de Drupal directory, vervang -r DRUPAL-6--1 met -A voor de laatste HEAD versie):

cvs -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib update -d -P -r DRUPAL-6--1 developer

Gewoon voor de volledigheid, om een schone checkout te doen van al deze extra documentatie, gebruik je de volgende twee commando's:

cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 -d developer contributions/docs/developer
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 -d developer/examples contributions/modules/examples

Gedaan? Goed zo, dan gaan we weer verder...

Is je iets opgevallen?

Als je de documentatie die de vorige keer gemaakt is hebt gebruikt, ben je misschien wat vervelende problemen tegen gekomen. We slaan de kapotte links op de hoofdpagina nu nog even over. Eerst gaan we ontbrekende tekst corrigeren. Kijk maar eens naar de documentatie van de t() functie (in includes/common.inc). Je kunt zien wat er mis is in de volgende screenshot:

Zie je hoe het stukje @variable ontbreekt bij het tweede item, net als het % teken voor variable in het derde puntje? Een kijkje in de Doxygen fout-uitvoer leert ons dat Doxygen het @variable commando niet kent. Doxygen commando's worden vooraf gegaan door een '@' of '\' in Doxygen, maar de Drupal API module (die gebruikt wordt voor api.drupal.org) negeert vrolijk alle onbekende commando's. Doxygen niet, wat hier problemen veroorzaakt. Met het '%' teken vertellen we Doxygen in principe dat we het woord 'variable' niet automatisch willen linken. Ook hier doet de Drupal API module niks mee en deze print het vrolijk uit.

We gaan deze problemen in een paar stappen oplossen. Deel een: tijd voor wat PHP Regular Expressions magie!

Een eenvoudige preprocessor

Maak een nieuw tekstbestand aan met een leuke naam als perprocess-drupal-doxygen.php. Dat zegt ons precies wat het doet: Drupal bestanden preprocessen voor Doxygen; en het is een PHP script. Om te beginnen maken we alvast een basis klasse met behulp van de volgende code:

#!/usr/bin/php
<?php
abstract class Preprocessor {
  private $_filename = '';
 
  public function __construct ($filename) {
    $this->_filename = $filename;
  }
 
  public function process() {
    $contents = file_get_contents($this->_filename);
    // Convert Mac/Win line breaks to Unix format.
    $contents = str_replace("\r\n", "\n", $contents);
    $contents = str_replace("\r", "\n", $contents);
 
    return $this->doProcess($contents);
  }
 
  protected abstract function doProcess($contents);
}

Opmerking: ik heb in de code hier (en verderop) het meeste commentaar uit de code gehaald; onderaan kun je het volledige script downloaden, met al het commentaar.

Sla het bestand op en zorg de je "uitvoer" rechten hebt. Op Windows moet je misschien een bestands associatie als *.phpx instellen om te zorgen dat het door PHP uitgevoerd wordt, en het bestand vervolgens de juiste naam geven. Een andere optie is om een .cmd bestand te maken dat het PHP script uitvoert (en alle argumenten doorgeeft).

De lap tekst doet een paar dingen. De eerste regel zorgt dat het script uitgevoerd wordt door PHP. Verder is er een Preprocessor klasse, die een bestand leest en alle nieuwe regels naar een Unix formaat omzet, voor de eenvoudigheid (code geleend van de Drupal API module). Daarna roept het de (abstracte) doProcess() functie aan. Hier werken we aan in twee subklasses (waarvan de tweede in deel 3B gemaakt zal worden). Deze gaan daadwerkelijk iets nuttigs doen.

We voegen nu eerst de CodePreprocessor klasse toe, die alle codebestanden (.php, .module, .inc etc.) zal verwerken. Om te beginnen gaan we commentaar eruit vissen:

class CodePreprocessor extends Preprocessor {
 
  public function __construct ($filename) {
    Preprocessor::__construct($filename);
  }
 
  protected function doProcess($contents) {
    // Beyond Drupal's API module: we also work on blocks started with "/*!"
    $contents = preg_replace_callback('@/\*[\*!](.*?)\*/@s',
                                      array($this, 'processCommentBlock'),
                                      $contents);
    // And those with at least two lines of /// or //!
    $contents = preg_replace_callback('@(//[/!])[^\\n]*\\n(\\1[^\\n]*\\n)+@s',
                                      array($this, 'processCommentBlock'),
                                      $contents);
    // Return processed file contents
    return $contents;
  }
 
  private function processCommentBlock($matches) {
    $contents = $matches[0];
 
    // ADD FUNCTION CALLS HERE LATER
 
    return $contents;
  }

De doProcess implementatie hier zoekt Doxygen commentaren op. In tegenstelling tot Drupal's API module, nemen we ook blokken mee die beginnen met '/*!', net als blokken van tenminste twee regels beginnend met '///' of '//!'. Dit zijn allemaal blokken die Doxygen gaat doorlopen, dus wij doen hetzelfde. Op elk blok roepen we processCommentBlock aan. Deze functie krijgt de matches array van de reguliere expressie ($matches[0] bevat de gehele match), en verwacht een string retour. Vervolgens wordt het gevangen stuk tekst vervangen met deze waarde. Al met al een handige functie om onze verwerking in te zetten.

Onbekende commando's escapen

Nu wat echte verwerkingscode. Om Doxygen de '@' en '%' tekens te laten behouden in de uitvoer (om het eerste probleem op te lossen), moeten we ze escapen, oftewel een backslash ervoor zetten. We willen echter niet dat bestaande Doxygen commando's genegeerd worden. We kunnen tegelijkertijd ook een ander probleem oplossen: drupal_match_path() heeft documentatie met daarin "\r" en "\n". Drupal's API module verwerkt het "\n" commando niet, terwijl Doxygen de regel afbreekt. Ook zeurt Doxygen dat het "\r" commando niet bestaat, en gooit het weg. We gaan dus ook commando's beginnend met een backslash escapen, net als (geldige!) backslash commando's gevolgd door een enkele letter (\a, \n enz), zo lang deze niet al ge-escaped zijn. Dus: \r wordt \\r (en weer \r in de HTML uitvoer), maar iets als \\e scaped blijft hetzelfde.

Dus: tijd voor meer magie met reguliere expressies. Voeg een functie toe in deCodePreprocessor class, die begint met het opnoemen van alle bekende Doxygen commando's:

  private function escapeUnknownCommands($contents) {
    static $commandsArray = array(
      'a', 'addindex', 'addtogroup', 'anchor', 'arg', 'attention', 'author', 'b', 'brief', 'bug',
      'c', 'callgraph', 'callgraph', 'callergraph', 'category', 'class', 'code', 'cond',
      'copybrief', 'copydetails', 'copydoc', 'date', 'def', 'defgroup', 'deprecated', 'details', 'dir',
      'dontinclude', 'dot', 'dotfile', 'e', 'else', 'elseif', 'em', 'endcode', 'endcond', 'enddot',
      'endhtmlonly', 'endif', 'endlatexonly', 'endlink', 'endmanonly', 'endmsc', 'endverbatim', 'endxmlonly',
      'enum', 'example', 'exception', 'extends', 'file', 'fn', 'headerfile', 'hideinitializer', 'htmlinclude',
      'htmlonly', 'if', 'ifnot', 'image', 'implements', 'include', 'includelineno', 'ingroup', 'internal',
      'invariant', 'interface', 'latexonly', 'li', 'line', 'link', 'mainpage', 'manonly', 'memberof', 'msc',
      'n', 'name', 'namespace', 'nosubgrouping', 'note', 'overload', 'p', 'package', 'page', 'paragraph',
      'param', 'post', 'pre', 'private', 'privatesection', 'property', 'protected', 'protectedsection',
      'public', 'publicsection', 'protocol', 'ref', 'relates', 'relatesalso', 'remarks', 'return', 'retval',
      'sa', 'section', 'see', 'showinitializer', 'since', 'skip', 'skipline', 'struct', 'subpage',
      'subsection', 'subsubsection', 'test', 'throw', 'todo', 'tparam', 'typedef', 'union', 'until', 'var',
      'verbatim', 'verbinclude', 'version', 'warning', 'weakgroup', 'xmlonly', 'xrefitem',
      'annotatedclasslist', 'classhierarchy', 'define', 'functionindex', 'header', 'headerfilelist',
      'inherit', 'l', 'postheader',
    );
    static $backslashCommandsArray = array(
      'addindex', 'addtogroup', 'anchor', 'arg', 'attention', 'author', 'brief', 'bug',
      'callgraph', 'callgraph', 'callergraph', 'category', 'class', 'code', 'cond',
      'copybrief', 'copydetails', 'copydoc', 'date', 'def', 'defgroup', 'deprecated', 'details', 'dir',
      'dontinclude', 'dot', 'dotfile', 'else', 'elseif', 'em', 'endcode', 'endcond', 'enddot',
      'endhtmlonly', 'endif', 'endlatexonly', 'endlink', 'endmanonly', 'endmsc', 'endverbatim', 'endxmlonly',
      'enum', 'example', 'exception', 'extends', 'file', 'fn', 'headerfile', 'hideinitializer', 'htmlinclude',
      'htmlonly', 'if', 'ifnot', 'image', 'implements', 'include', 'includelineno', 'ingroup', 'internal',
      'invariant', 'interface', 'latexonly', 'li', 'line', 'link', 'mainpage', 'manonly', 'memberof', 'msc',
      'name', 'namespace', 'nosubgrouping', 'note', 'overload', 'package', 'page', 'paragraph',
      'param', 'post', 'pre', 'private', 'privatesection', 'property', 'protected', 'protectedsection',
      'public', 'publicsection', 'protocol', 'ref', 'relates', 'relatesalso', 'remarks', 'return', 'retval',
      'sa', 'section', 'see', 'showinitializer', 'since', 'skip', 'skipline', 'struct', 'subpage',
      'subsection', 'subsubsection', 'test', 'throw', 'todo', 'tparam', 'typedef', 'union', 'until', 'var',
      'verbatim', 'verbinclude', 'version', 'warning', 'weakgroup', 'xmlonly', 'xrefitem',
      'annotatedclasslist', 'classhierarchy', 'define', 'functionindex', 'header', 'headerfilelist',
      'inherit', 'postheader',
    );
    static $noWordCommands = array(
      'f[\$\[\]\{\}]', '[\$@\\\\&~<>#%"]',
    );
  }

Nu gebruiken we deze lijsten om de belangrijkste reguliere expressies die we nodig hebben te maken: twee stuks om de commando's te escapen. Oh, en we vergeten ook niet om alle procent-tekens te escapen, als dat niet al gebeurt is. Tijd om de zojuist gemaakte functie uit te breiden:

    static $backslashCommandRegex = NULL;
    static $commandsRegex = NULL;
    static $noWordCommandsRegex = NULL;
 
    if (!isset($backslashCommandRegex)) {
      $commandsRegex = '/(^|(?<=\W))(?<!\\\\|@)@(?!' . implode('\W|', $commandsArray) . '\W|'
                     . implode('|', $noWordCommands) . ')/';
      $backslashCommandRegex = '/(^|(?<=\W))(?<!\\\\|@)\\\\(?!'
                             . implode('\W|', $backslashCommandsArray) . '\W|'
                             . implode('|', $noWordCommands) . ')/';
    }
 
    // First replace all unknown backslash commands that occur before commands
    $contents = preg_replace($backslashCommandRegex, '\\\\\\\\', $contents);
    // And unknown '@' prefixed commands
    $contents = preg_replace($commandsRegex, '\@', $contents);
    // Escape all unescaped percentage characters
    $contents = preg_replace('/(?<!\\\\|@)%/', '\\\\%', $contents);
    return $contents;

De reguliere expressies zien er ingewikkeld uit (vooral omdat we zelf een hoop backslashes moeten escapen), maar de werking is zoals hierboven beschreven. De 'noWordCommands' is apart gehouden, omdat dan die commando's gevolgd met een letter intact blijven. Een normaal commando dat gevolgd wordt door extra letters, moet alsnog een backslash ervoor krijgen (bijvoorbeeld: @var moet zo blijven, maar @variable moet veranderen in \@variable).

Nu moeten we de nieuwe functie nog aanroepen. Plaats de volgende regel in de belangrijke processCommentBlock() functie zoals eerder beschreven, bij de duidelijk gemarkeerde opmerking:

$contents = $this->escapeUnknownCommands($contents);

Uitproberen

Voordat we de code kunnen gaan gebruiken, moet er nog een beetje toegevoegd worden om de preprocessor aan te sturen, onderaan het script (na alle klasses):

// Default to processing stdin if no arguments are given
if ($argc == 1) {
  $argc = 2;
  $argv[1] = '-';
}
 
// Process all files in argument list
for ($i = 1; $i < $argc; ++$i) {
  $filename = $argv[$i];
 
  if ($filename == "-") {
    $filename = "php://stdin";
  }
 
  // Find out type of file (based on filename)
  $processor = NULL;
  $info = pathinfo($filename);
  if (!empty($info['extension']) && in_array($info['extension'], array('html', 'htm', 'xhtml'))) {
    // HTML Processing is for later...
  }
  else {
    $processor = new CodePreprocessor($filename);
  }
 
  // Process file
  print $processor->process();
}

Deze code maakt een CodePreprocessor instantie aan (later voegen we hier een apart item voor HTML bestanden aan toe). Alle bestanden die als argument mee worden gegeven, wordt de code verwerkt en de resultaten teruggestuurd. Standaard wordt er van de standaard input gelezen, om het script te kunnen hergebruiken buiten Doxygen, mocht dat ooit nodig zijn (Dat was vooral handig tijdens het debuggen van het hele script, zodat ik het op selecties of andere bestanden kon gebruiken, direct vanuit mijn IDE).

Laten we het script eens gaan uitproberen. Sla het op (ik gebruik hier /home/cheetah/public_html/drupal.api/preprocess-drupal-doxygen.php) en open de Doxygen wizard weer eens (zoals in deel twee). Verander de instelling INPUT_FILTER in het Input onderdeel zodat het naar je script wijst. Het is ook nuttig om de bestandsnaam toe te voegen aan de lijst van uitgesloten bestanden (voeg preprocess-drupal-doxygen.php aan de EXCLUDE instelling in het Input onderdeel toe), mocht je het script in je Drupal directory opslaan. Hierdoor krijg je de documentatie van dit script niet in je Drupal documentatie.

Als je nu Doxygen uitvoert en de documentatie weer bekijkt, zul je zien of alles gelukt is. Zo ja, dan zou de documentatie van t() er nu uit moeten zien zoals het online is. Mooi.

Kapotte links

Iets anders dat je direct al opvalt is dat op de hoofdpagina van de documentatie niet alle links werken. De links naar groepen (Module system, Database abstraction layer, enzovoorts) werken prima, net als de voorbeeldmodules als je die in je documentatie hebt staan. De links naar de constanten, globale variabelen en de geavanceerdere onderwerpen werken echter geen van allen. Tijd om dat ook op te lossen, door de preprocessor uit te breiden.

We beginnen met de link naar alle constanten, of enums in Doxygen. We weten dat er een pagina is, maar die staat niet op /api/constants. We willen de globals_enum.html pagina gebruiken; dat is de pagina met alle define() elementen die in de code gevonden worden. Dus maken we er een normale anchor link van (oftewel een <a> tag):

  private function makeAnchorLinks($contents, $links) {
    foreach($links as $original => $new) {
      $re = '/@link ' . str_replace('/', '\/', $original) . '(\/\S*)?\s(.*\S)\s*@endlink/';
      $contents = preg_replace($re, '<a class="el" href="' . $new . '">\\2</a>', $contents);
    }
    return $contents;
  }

De volgende functie zal links naar /api/globals gaan veranderen in een link die naar de globals.php documentatie verwijst. Dit bestand, in de extra developer documentatie, bevat gedocumenteerde versies van alle globale variabelen in Drupal zelf. Een andere optie is om met bovenstaande functie de link naar globals_vars.html te laten wijzen, waarin alle globale variabelen (ook die van modules) opgesomd worden. Als je daarvoor kiest is de volgende functie onnodig, tenzij je meer kapotte links vind die je wilt repareren.

  private function replaceLinks($contents, $links) {
    foreach($links as $original => $new) {
      $re = '/@link ' . str_replace('/', '\/', $original) . '(\/\S*)?\s(.*\S)\s*@endlink/';
      $contents = preg_replace($re, '@link ' . $new . ' \\2 @endlink', $contents);
    }
    return $contents;
  }

Zet beide functies in de CodePreprocessor klasse. Roep ze als volgt aan, na de aanroep naar escapeUnknownCommands:

      $contents = $this->makeAnchorLinks($contents, array(
        '/api/constants' => 'globals_enum.html',
        // '/api/globals' => 'globals_vars.html',
      ));
      $contents = $this->replaceLinks($contents, array(
        '/api/globals' => 'globals.php',
      ));

Zie je de regel commentaar? Dat is het alternatief voor de globale variabelen; verwijder of maak commentaar van de andere regel over /api/globals als je liever de global_vars.html pagina gebruikt (je kunt daar hoe dan ook bij via Files, dan Globals in de Doxygen navigatie). Merk ook op dat de code flexibel genoeg is om snel meer links toe te voegen. Ook worden langere URLs automatisch meegenomen, zolang het extra deel met een slash begint (bijv. /api/constants/7 wordt ook in zijn geheel aangepast, maar /api/constants_7 wordt als andere link gezien).

Nu nog de externe links (zoals de "Drupal Programming from an Object-Oriented Perspective" link op de hoofdpagina). De volgende functie haalt het gebruikte @link commando weg, en vervangt het met een HTML tag die door Doxygen verder met rust gelaten wordt.

Now to deal with any external links (like the "Drupal Programming from an Object-Oriented Perspective" link on the main page). The following function will remove the used @link command, and replace it with an HTML tag again.

  private function replaceExternalLinks($contents) {
    return preg_replace('/@link (([a-zA-Z]+:\/\/|mailto\:)\S*)\s+(.*\S)\s*@endlink/',
                 '<a class="el" href="\\1">\\3</a>', $contents);
  }

En de aanroep:

$contents = $this->replaceExternalLinks($contents);

Let wel dat elk protocol (http://, ftp:// enz) als extern gezien wordt. Het mailto: protocol wordt enigszins apart afgheandeld, omdat er geen twee slashes achter komen, maar verder is alles gelijk. De hele URL, tot de eerste spatie, wordt gezien als de daadwerkelijke URL om naar te refereren. De rest is de tekst die gelinked wordt. Als je een stapje verder wilt gaan, kun je ook code toevoegen om de URL als gelinkte tekst te laten zien, als er verder geen tekst aanwezig is (Doxygen zal dat voor je doen als je de @link en @endlink commando's weg filtert). Dat laat ik verder als oefening open.

Samenvatting

Dus... wauw. Deze post is wat langer geworden dan ik had verwacht. Ik heb een vernieuwd Doxyfile in de bijlagen gezet (met de ingevulde INPUT_FILTER en aangepaste EXCLUDE instellingen), net als de code uit deze post. De grootste problemen in de Doxygen code zijn nu opgelost, waarmee de documentatie van Drupal meer geschikt wordt voor Doxygen zelf. Allemaal werk dat ook nuttig is als je de Qt Assistant niet gebruikt; zodra je Doxygen in plaats van Drupal's API module gebruikt, wil je de problemen die hier beschreven zijn opgelost hebben.

Hierna volgt niet deel 4, maar 3b. De volgende stap is namelijk om te zorgen dat Doxygen de HTML pagina's met documentatie, zoals de Forms API referentie, gaat toevoegen. Dat zal sneller gaan nu we de basis klaar hebben.

Bijlage	Grootte
Doxyfile.	62.95 KB
preprocess-drupal-doxygen.php_.txt	9.55 KB

MacDesperate nu Online!

ChEeTaH — Tue, 08 Dec 2009 18:59:05 +0000

Na een behoorlijke tijd (meer dan een jaar), hebben we afgelopen zondag eindelijk MacDesperate gelanceerd. Wij zijn Rosana, Alex, Wouter en ik. Uiteraard draait MacDesperate op Drupal. Rosana en Wouter sparen voor Macs - zij zijn de echte MacDesperates - en mijn Donation Goals module helpt ze bij te houden hoeveel ze al hebben. De eerste donaties zijn al binnen. Nu is het tijd dat jij ze gaan steunen! Aarzel niet en ga naar MacDesperate.com! We hebben goodies!

Drupal Ontwikkeling eenvoudiger met de Qt Assistant - Deel 2

ChEeTaH — Sun, 22 Nov 2009 22:38:31 +0000

In het vorige deel van deze walk-through hebben we de nodige software geïnstalleerd om de Drupal API documentatie in de Qt Assistant te krijgen. De volgende stap is om de Drupal documentatie te genereren zodat we er doorheen kunnen bladeren, zoeken en meer. Als je dat nog niet gedaan hebt, lees dan eerst deel 1 zodat je zeker weet dat je de goede software geïnstalleerd hebt.

Een Doxyfile Maken

Allereerst moeten we een configuratiebestand voor Doxygen maken. Dit bestand bevat instructies voor Doxygen over het formaat waarin de documentatie moet zijn, waar de code staat, enzovoorts. Ik zal laten zien hoe het werkt met het grafische programmaatje, doxywizard. Natuurlijk is het ook mogelijk om het doxygen commando een bestand aan te laten maken, dat je handmatig aanpast (met een tekstverwerker). Het maakt niet uit hoe je het doet. Als je het Doxyfile bestand direct wilt downloaden: dit staat onderaan deze post.

Laten we beginnen met de Doxygen wizard. Deze staat in je applicatiemenu, waarschijnlijk onder Ontwikkeling (Development). Je kunt ook gewoon doxywizard starten van een terminal. Het venster dat je te zien krijgt vraagt je, als eerst, om de werkdirectory te selecteren. Kies een Drupal directory hier. In mijn geval is dat /home/cheetah/public_html/drupal.api. Aangezien we wat geavanceerde instellingen willen aanpassen, gaan we gelijk naar het Expert tabblad om alles te configureren.

De eerste instellingen waar je op moet letten zijn de PROJECT_NAME ("drupal"), PROJECT_NUMBER ("6" of welke versie van Drupal je ook mee werkt), en de OUTPUT_DIRECTORY instellingen. Voor die laatste is het het makkelijkst om een nieuwe locatie op te geven waar Doxygen zijn bestanden wegschrijft. Hiermee voorkom je dat Doxygen bestanden je Drupal installatie volgooit met allerlei bestanden. Ik heb een doxygen subdirectory gebruikt ("/home/cheetah/public_html/drupal.api/doxygen"). Je kunt het best ook de REPEAT_BRIEF en ALWAYS_DETAILED_SEC opties inschakelen. De STRIP_FROM_PATH zou nu leeg moeten zijn, maar het is wel zo handig om de hoofddirectory van je Drupal installatie hier in te vullen (op deze manier, als je Doxygen niet vanuit de Drupal directory start, haalt hij nog steeds het juiste pad van de bestandsnamen af). Ik heb ook de QT_AUTOBRIEF en OPTIMIZE_OUTPUT_FOR_C opties ingeschakeld.

Als laatste is er nog één belangrijke instelling op het Project topic, en dat is EXTENSION_MAPPING. Normaal gesproken gebruikt Drupal *.php, *.module en *.inc bestanden voor de code. We moeten Doxygen wel vertellen dat dit PHP bestanden zijn. Voeg "module=PHP" en "install=PHP" toe aan deze instelling (volgens de documentatie moet je de punt vooraan in de extensie weglaten).

Het volgende tabblad is het Build topic. We willen alle documentatie krijgen, dus zetten wede EXTRACT opties aan voor ALL, PRIVATE, STATIC, LOCAL_CLASSES en LOCAL_METHODS. De SHOW_DIRECTORIES instelling is handig als je de directorystructuur zichtbaar in de documentatie wilt hebben. We gaan gelijk verder naar Input, waar we onze Drupal directory aan de INPUT instelling toevoegen. Belangrijk is ook de FILE_PATTERNS instelling: deze geeft aan Doxygen aan in welke bestanden documentatie staat. De bestanden *.php en *.inc staan er waarschijnlijk al, maar voor Drupal moet je hier ook de *.module en *.install patronene aan toevoegen. Hiermee zal Doxygen de meeste, zo niet alle, documentatie van Drupal code indexeren (helaas werkt Doxygen niet zo goed met Javascript).

Schakel ook de RECURSIVE optie in, anders moet je Doxygen precies vertellen in welke directories er gezocht moet worden, in de INPUT instelling. Als je een directory met backups van oude modules binnen je Drupal installatie bewaart, stel dan het pad in bij de EXCLUDE instelling (bijvoorbeeld "backup"). Voor EXCLUDE_PATTERNS zijn de volgende patronen wellicht nuttig: */CVS/*, */.svn/*, */.git/* (zodat Doxygen bestanden van versiebeheersystemen negeert), plus */settings.php en */*.settings.php om site-specifieke instellingbestanden te negeren.

De volgende stap is het HTML topic, waarmee we de HTML uitvoer van Doxygen instellen. Ja, we willen HTML genereren (schakel GENERATE_HTML in) in de html subdirectory (HTML_OUTPUT) met de .html extensie voor de bestanden (HTML_FILE_EXTENSION). Nu een heel belangrijke instelling voor het maken van Qt Help bestanden, die de Qt Assistant gebruikt. Schakel GENERATE_QHP in. Voor QCH_FILE, die net beschikbaar is gemaakt, stel je drupal-6.qch in (of simpelweg drupal.qch, of vervang de 6 door het versienummer van Drupal waar je mee werkt). Stel QHP_NAMESPACE in op org.drupal.6 (vervang weer het versienummer) en stel all in als de QHP_VIRTUAL_FOLDER - dit komt later nog van pas. Dan nog de filter instellingen: Zet QHP_CUST_FILTER_NAME op "Drupal 6 (all)" en zowel QHP_CUST_FILTER_ATTRS als QHP_SECT_FILTER_ATTRS op drupal drupal-6. Als laatste stellen we het pad naar het "qhelpgenerator" programma ("qhelpgenerator.exe" op Windows, neem ik aan) in met de QHG_LOCATION instelling. Dit is waarschijnlijk iets als "/usr/bin/qhelpgenerator" of "C:/Qt/bin/qhelpgenerator.exe". Laat de rest van de instellingen op hun standaardwaarde staan (DISABLE_INDEX uit, GENERATE_TREEVIEW op none, enz.).

Controleer uiteindelijk nog even dat de uitvoer van LaTeX, RTF, Man en XML uit staan op de topics daarvoor. We gebruiken deze toch niet. Als je wilt kun je ook nog de klassediagrammen aan of uitschakelen op het Dot topic. Dit zal voor sommige modules (met name Views) verschil maken.

Eerste Keer Starten

Alles is nu ingesteld, tijd om Doxygen te draaien! Ga naar het Run tabblad, klik op de Run doxygen knop en laat het z'n werk doen. Als het eenmaal klaar is, klik je op "Show HTML Output" en je browser start met de Drupal documentatie recht voor je. Tenzij je de "sites" subdirectory hebt weggelaten, krijg je ook de documentatie van contributed modules mee. Sommige links zullen niet werken (bijvoorbeeld de Form API referentie), en het geheel is misschien wat onoverzichtelijk als je veel modules erbij hebt. Dat lossen we in het volgende deel op. Eerst sluiten we de wizard af. Hij vraagt om de configuratie op te slaan. Doe dit met de standaard naam ("/home/cheetah/public_html/drupal.api/doxygen/Doxyfile" in mijn geval). Het voorbeeldbestand dat hier gemaakt is vind je onderaan deze post.

Als laatste voor vandaag gaan we zorgen dat de Qt Assistant onze documentatie gaat laten zien. Dit vereist enig werk op de terminal/command line. Zorg eerst dat je weet waar Qt Assistant staat. Het programma heet simpelweg assistant, dus op de meeste platforms moet je het nu met which assistant kunnen vinden. Op Windows kijk je in je Qt installatiedirectory, in de bin directory. Kies nu een bestandsnaam voor je Qt Help Collectie, en maak een leeg bestand aan met deze naam. Dit kan met het touch commando, of door met je bestandsbeheerder een leeg bestand met de juiste naam aan te maken (Windows gebruikers willen dat waarschijnlijk doen; gebruik de Verkenner of Kladblok en maak dat bestand aan. Zorg wel dat de extensie .qhc en niet .txt of iets anders is!). Start nu je terminal en voer het volgende commando uit (uitgaande van een bestandsnaam van drupal-6.qhc in je home directory, en een username van cheetah):

/usr/bin/assistant -collectionFile /home/cheetah/drupal-6.qhc

Je kunt ook een snelkoppeling maken die dit uitvoert, natuurlijk. Je krijgt nu een lege Qt Assistant te zien:

Zolang het de eerste keer is dat je de assistent met dit bestand opstart, kun je naar het Edit > Preferences menu gaan. Kies hier het Documentation tabblad, klik Add... en voeg het drupal-6.qch bestand toe dat door Doxygen is gemaakt (dit staat in de doxygen/html directory in je Drupal installatie, als je deze tutorial hebt gevolgd. Qt Assistant werkt nu de index bij, en je kunt je documentatie nu zien en doorzoeken:

Als je de assistant de volgende keer opstart met dezelfde collectionFile parameter, dan zal het Documentation tabblad niet meer beschikbaar zijn onder de voorkeuren, zelfs na het verwijderen en opnieuw aanmaken van het bestand. Als dit gebeurt, kun je het helpbestand nog wel uit de collectie registreren en deregistreren, vanaf de opdrachtregel, als volgt (pas natuurlijk wel de bestandsnamen aan):

assistant -collectionFile drupal-6.qhc -register /home/cheetah/public_html/drupal.api/doxygen/html/drupal-6.qch

Om het bestand weer uit de collectie te verwijderen:

assistant -collectionFile drupal-6.qhc -unregister /home/cheetah/public_html/drupal.api/doxygen/html/drupal-6.qch

Deze commando's vertellen je of er iets nuttigs gebeurt is, maar ze starten de assistant niet op. Start hem opnieuw op met alleen het collectionFile argument om de documentatie weer te zien.

Let op dat zolang de Qt Compressed Help bestanden (die aangemaakt zijn door Doxygen) op dezelfde plek blijven staan, je de documentatie kunt bijwerken en de aanpassingen direct kunt zien in de assistant, als je ooit de documentatie bijwerkt. De assistant maakt automatisch zijn index opnieuw aan en regelt de rest voor jou. Met die kennis kun je dus een icoontje maken dat de assistant opstart, met directe toegang tot de Drupal documentatie. Gewoon bovenstaand commando gebruiken (dat van boven de lege assistant screenshot). Let op dat je de juiste bestandsnaam meegeeft!

Updates

Als je ooit je documentatie wilt bijwerken (omdat je bijvoorbeeld extra modules hebt geïnstalleerd, Drupal hebt bijgewerkt naar een nieuwe versie, enz), maak je de documentatie opnieuw aan met Doxygen. Je kunt met de wizard het eerder opgeslagen Doxyfile inladen, Doxygen opnieuw draaien, en de assistant toont de bijgewerkte documentatie als je het de volgende keer opstart. Zo simpel is het. Je kunt ook, met een terminal, naar je Drupal directory gaan (of waar je je Doxyfile dan ook hebt staan) en daar doxygen aanroepen. Zolang je de INPUT instelling hierboven expliciet hebt ingesteld, kun je ook doxygen /pad/naar/Doxyfile gebruiken en zo zelfs een geheel andere bestandsnaam gebruiken voor je Doxygen configuratie. Je kunt natuurlijk ook wat met de instellingen van Doxygen spelen, het opnieuw draaien, en zo de documentatie met de nieuwe instellingen in je Qt Assistant krijgen.

Natuurlijk hoef je ook geen apart collectiebestand (*.qhc) te gebruiken voor elke Drupal versie die je hebt. Je kunt elke versie van Drupal in dezelfde assistant zetten. Zolang je verschillende namespaces hebt gebruikt (vandaar dat de versienummers in de configuratie staan), kun je filteren op versie aan de bovenkant van de interface.

Samenvatting

De vorige keer hebben we alleen wat software geïnstalleerd. Deze keer hebben we die software allemaal gebruikt, al is het wel op de meest eenvoudige manier, maar met succes: de Qt Assistant laat nu de Drupal documentatie zien. Hiermee kun je al een heel eind op weg om alle informatie van de Drupal API die je nodig hebt te vinden. Er zijn nog wat problemen met niet werkende links naar speciale onderwerpen en je kunt nog niet filteren per module, enzovoorts.

Maar: het belangrijkste zit er op. De volgende keer gaan we wat dieper in op die problemen, om deze op te lossen. Het wordt vast niet zo veel werk als dit deel. Tot de volgende keer!

Bijlage	Grootte
Doxyfile.	62.83 KB

Donation Goals module op Drupal

ChEeTaH — Sat, 14 Nov 2009 20:41:44 +0000

Gisteren heb ik wat werk afgerond dat ik een een nieuwe Drupal module heb gestoken, voor een site die waarschijnlijk voor het eind van het jaar nog de lucht in gaat (ik wil geen druk op anderen zetten!). Het heet "Donation Goals" en kan van de Donation Goals Projectpagina gedownload worden.

Met Donation Goals kun je een nieuw content type in je Drupal site maken. Je raadt 't al, een "Donation Goal." Even wat gegevens invullen, vooral hoeveel geld je nodig hebt. Dan de boel publiceren en zorgen dat je bezoekers krijgt. Ze kunnen dan geld doneren aan jou, via PayPal, zodat je zo je doel kunt bereiken.

De module houdt de donaties bij (zolang ze via de site gemaakt worden) en maakt het zelfs mogelijk hippe overzichten van alle donaties te maken (Views FTW!). Als je zelf wat geld gespaard hebt, kun je dit natuurlijk via PayPal toevoegen. Makkelijker is het om het geld gewoon toe te voegen aan de hoeveelheid gespaard geld en de module de rest van het werk laten doen (en daarmee omzeil je ook de PayPal kosten omdat je geld aan jezelf geeft).

Er zijn een paar vergelijkbare modules (Bounty, Donation and ChipIn) beschikbaar, maar ze zijn allemaal subtiel anders en/of worden niet meer bijgehouden.

Een eerste ontwikkelversie is nu uit, maar de module heeft waarschijnlijk nog genoeg functionaliteit die toegevoegd kan worden, dingen om te veranderen en fouten om te repareren. Probeer hem alvast van drupal.org/project/donation_goals en laat me weten wat je er van vindt!

Drupal Ontwikkeling eenvoudiger met de Qt Assistant - Deel 1

ChEeTaH — Tue, 10 Nov 2009 22:53:44 +0000

Als je mijn blog ook maar enigszins volgt, weet je dat ik KDE 4 als desktop omgeving heb. Ik heb ook een hoop ontwikkeld (vooral wat aangeklooid tot nu toe, alleen tContact is gepubliceerd) voor Drupal. Een van de programma's die mij daarbij helpt is de Qt Assistant, die bij Qt 4 en later meegeleverd wordt. Het is een snel programma om documentatie te lezen, met een goede index om razendsnel die kleine details van elke functie in Qt 4 op te kunnen zoeken... of Drupal. Ik zal je laten zien hoe ik de boel heb aangepakt.

Oh, als je niet zoveel hebt met al deze technische zooi: je hoeft niet verder te lezen, natuurlijk.

Opmerkingen vooraf

Ten eerste: deze gids gaat vooral over hoe de Drupal API in de Qt Assistant terecht komt, maar het zou voor zo'n beetje elk C++/PHP/Java/Python project enz. moeten werken, zolang Doxygen er mee overweg kan. Zie de Doxygen website voor informatie hoe je je code moet documenteren enzovoorts. Helaas is het mij nog niet gelukt om de PHP documentatie zelf geïntegreerd te krijgen in de Qt Assistant.

Ik gebruik soms ook wat scripts die vanuit een terminal of shell gedraaid moeten worden. Dit zou in principe geen probleem moeten zijn voor Linux of Mac gebruikers, voor Windows is het misschien nodig om CygWin te gebruiken. Helaas heb ik dit alles niet in Windows geprobeerd, dus als iemand handige/bruikbare tips in de opmerkingen kan achterlaten voor Windows gebruikers, dan is dat zeer welkom.

Voorbereiding

Zo, je bent er nog. Het eerste wat er moet gebeuren is Qt4 installeren. Dat kun je downloaden van QtSoftware.com voor zo'n beetje elk platform. Gebruik de LGPL/Free versie van het Framework of SDK. Voor Linux gebruikers zit dit overigens vaak in de repositories van de distributie, je moet misschien wel de -dev of -devel pakketten installeren.

Punt 2: download Drupal van Drupal.org en pak het ergens uit op je harde schijf. Je kunt natuurlijk ook je bestaande Drupal installatie met alle modules gebruiken, of welk product je dan ook wilt kunnen gebruiken met de Assistant (mits je de broncode hebt). Je kunt ook meerdere versies van Drupal gebruiken, om zo los van elkaar de documentatie van Drupal 5, 6 en 7 te hebben. De keuze is aan jou. Je hoeft 't overigens niet te installeren, je hebt genoeg aan het beschikbaar maken van de broncode.

Voor Drupal is het ook handig om de Ontwikkelaarsdocumentatie van CVS te halen. Hierin staan wat extra help pagina's zoals de FAPI Referentie en meer, en documentatie over alle hooks (hook_* functies). Ik zal de precieze instructies hier niet herhalen. Je vindt de instructies namelijk op drupal.org (Engelstalig).

Als laatste is het de beurt aan Doxygen (www.stack.nl/~dimitri/doxygen/). Linuxgebruikers vinden dit weer in de repository van de distributie. Dit programma leest de documentatie uit de broncode en zet deze in handige HTML bestanden - en uiteindelijk ook de Qt Assistant.

Qt Assistant - Een klein overzicht

Nu alle nodige software is geïnstalleerd, kun je even een kijkje nemen in wat de Qt Assistant precies doet voor Qt. Als het goed is vind je het in de programmastarter/start menu/waar dan ook (Mac: /Developer/Applications/Qt) of door gewoon "assistant" vanuit een terminal. Probeer het maar, je zou iets moeten zien dat er ongeveer zo uit ziet:

Laten we even een functie opzoeken waarvan we een (deel van) de naam kennen: aboutQt(). Klik op het Index tabblad aan de linkerkant, vul about in en je ziet een lijst van declaraties en algemene onderwerpen met about in de naam. Dubbelklik op aboutQt en de Qt Assistant vraagt je welk onderwerp je precies wilt bekijken, QApplication of QMessageBox. Ik heb gekozen voor QApplication in de onderstaande screenshot. Daadwerkelijke documentatie!

Als laatste nog een functie die ik niet zo vaak gebruik, maar wel razendsnel is: de zoekfunctie. Je vindt dit tabblad aan de rechterkant, net boven je documentatie. Zoek naar "about" en je krijgt iets wat lijkt op onderstaande screenshot, erg handig als je alleen een globaal onderwerp weet van iets wat je nodig hebt:

Speel wat rond en als je durft: probeer alvast de Drupal documentatie in de Assistant te krijgen. Dat zal in het volgende deel besproken worden - de gehele Drupal (en modules) API, geheel zonder het door de Qt documentatie te mixen.

Kijk! Onderhoud!

ChEeTaH — Tue, 10 Nov 2009 21:59:53 +0000

Hoera! Mijn lieftallige Rosana (MissDesign) heeft de site iets beter laten werken door wat aan het thema te sleutelen (HEEL erg bedankt, Rosana!). Dit was eigenlijk al een paar weken geleden gedaan. Ik heb net ook nog wat oude blogs gerepareerd zodat die er ook weer goed uit zien (screenshots e.d. moesten helaas even aangepast worden tijdens de updates, maar dat is nu opgelost). De verbeteringen zijn onder andere minder flikkeringen bij de knoppen bovenaan, opmerkingen hebben nu een betere stijl, en nog veel meer kleinere dingetjes. Ik heb net ook de Lightbox module aangezet op de site, waardoor afbeeldingen niet meer de hele website overnemen, maar in een mooie overlay te zien zijn. Ik heb zelfs slideshows! Ik beloof je, ik blog snel weer!

tContact op Drupal.org!

ChEeTaH — Thu, 02 Jul 2009 21:20:39 +0000

Ik heb het er al eerder over gehad... maar vandaag is het dan eindelijk zo ver! Ik heb een week of twee geleden al een CVS account voor Drupal.org gekregen. Daar had ik alleen nog niet echt gebruik van gemaakt wegens tentamens, tot zonet. Heb je een Drupal site en wil je je contactformulieren vertaald krijgen? Ontmoet tContact! Versie 6.x-1.0 is nu officiëel los!

Bachelor Informatica Bijna Voltooid!

ChEeTaH — Mon, 29 Jun 2009 18:30:26 +0000

De afgelopen 2 weken heb ik tentamens gehad, waarvan één voor voor m'n Bachelor Informatica. Ook het laatste voor die graad - nog een vak wat ik deze zomer (online) moet maken. Dit vak: "Semantiek & Berekeningsmodellen." Het goede nieuws kwam vandaag: geslaagd. Score: 7. Dat betekent dat ik na de zomer m'n Bachelor diploma waarschijnlijk heb. Woot! Natuurlijk een screenshot als bewijs: