blog van ChEeTaH

RTL XL Directe Links

ChEeTaH — Sat, 12 Mar 2011 13:20:19 +0000

Het Nederlandse (nou ja, officiëel Luxemburgs) TV station RTL heeft een paltform genaamd RTL XL. Hierop publiceren ze video's. Met alle ontwikkelingen in de wereld, is het soms handig om die video's te kunnen bekijken. Helaas eist RTL XL het gebruik van Silverlight, ook al zijn niet alle video's verpest met DRM. Vooral de nieuwsvideo's zijn - gelukkig - DRM-vrij. Maar: Silverlight - of Moonlight - op Linux blijft niet bepaald probleemloos...

Dus wilde ik de video's kunnen zien zonder Moonlight op m'n Linux systemen te moeten hebben. Na wat coden kan ik nu directe links naar de video's op RTL.nl en RTL XL krijgen. De video's kunnen dan met bijvoorbeeld VLC of MPlayer afgespeeld worden. Allemaal dankzij GreaseMonkey en wat mad coding skillz ;-)

Als je Firefox gebruikt, installeer dan GreaseMonkey en het user script. Voor andere browsers moet je deze pagina lezen over de mogelijkheden voor het gebruiken van het script. Het script voegt een link naar de video toe als een pagina van RTL een video heeft.

De code valt onder GPLv3 (ik zal binnenkort de licentie-informatie in het script bijwerken). Je kunt de Git repository hier bekijken of clonen van git://git.simply-life.net/simply-life.net/userscripts/rtlnl_media_url.

Drupal Ontwikkeling eenvoudiger met de Qt Assistant - Deel 4

ChEeTaH — Sat, 22 Jan 2011 23:18:04 +0000

Welkom bij het vierde en laatste deel van deze serie blogs. Eerder hebben we een PHP preprocessor gemaakt, waarmee enkele kleine problemen in de Drupal documentatie opgelost werden. Daarvoor in deel 1 hebben we ons systeem voorbereid en in deel 2 zijn de belangrijkste items van Doxygen geconfigureerd. Lees deel 3a en deel 3b voor het werk aan de PHP Preprocessor. Deze keer gebruiken we mijn eigen DoxyAssist programma om veel van het werk te automatiseren. Tijd om de documentatie nuttig te maken!

Goede basis

Dankzij het configureren en repareren van Doxygen de vorige keer, voor Drupal in het geheel, hebben een goede basis opgebouwd om mee te beginnen. De volgende stap is om de DoxyAssist scripts te installeren naar een handige locatie. DoxyAssist helpt jou - met name Drupal projecten - om modulair documentatie te bouwen. In plaats van één grote bundel, splitst DoxyAssist de core en extra modules van elkaar. Doxygen wordt voor elke module apart uitgevoerd, waarmee aparte sets van helppagina's gemaakt worden.

Daarna combineert DoxyAssist alle aparte bestanden weer in één Qt Help Collectie. Deze kan gebruikt worden in de Qt Assistant. Met behulp van filters in de UI van de Assistant wordt het mogelijk om alle documentatie samen te bekijken, of de documentatie van specifieke modules.

Projectbestand

DoxyAssist gebruikt projecten en subprojecten om te bepalen welk deel van de broncode wel of niet meegenomen moet worden in elke aparte uitvoer van Doxygen. Speciale ondersteuning is er voor Drupal, waarmee Drupal automatisch subprojecten (community modules, thema's, enzovoorts) ontdekt in de "sites" directory.

Dus maken we een XML bestand dat DoxyAssist vertelt waar de broncode gevonden moet worden, welk Doxyfile als basis bebruikt moet worden en welke opties overschreven moeten worden. Het geeft ook enkele specifieke opties voor de Qt Assistant aan. Deze laatste opties bepalen welke mogelijkheden beschikbaar zijn in de assistant, bij het openen van de collectie.

In dit voorbeeld neem ik even aan dat het basis-Doxyfile correct ingesteld is voor Drupal. Zie deel 3b voor de laatste versie, maar pas het wel aan voor jouw omgeving. Open daarna je editor en plak om te beginnen het volgende stuk erin:

<?xml version="1.0" encoding="utf-8"?>
<DoxyAssist xmlns="http://simply-life.net/doxyassist/doxyassist.xsd"
            xmlns:da="http://simply-life.net/doxyassist/doxyassist.xsd"
            version="1.0" type="drupal" name="Drupal API">
    <doxygen doxyfile="/home/cheetah/public_html/drupal/Doxyfile" />

Zoals je ziet in het deel hierboven worden eerst enkele basisdingen als XML namespaces uitgewerkt. We geven aan dat het een project van het type "drupal" is en dat we versie 1.0 van het DoxyAssist configurieformaat gebruiken. We geven de confuratie een naam en vertellen DoxyAssist welk basis-Doxyfile gebruikt moet worden. Vergeet niet daar het pad aan te passen!

In het volgende deel voegen we opties voor de Qt Assistant toe:

    <qtHelp collectionFile="/home/cheetah/.local/doc/drupal-6.qhc"
            projectFile="/home/cheetah/.local/doc/drupal-6.qhcp"
            storage="qch" copyAction="copy">
        <title>Drupal API Documentation (6.x)</title>
        <startPage>qthelp://org.drupal.6-x/org.Drupal.6-x/main.html</startPage>
        <applicationIcon>drupal.png</applicationIcon>
        <enableFilterFunctionality visible="true">true</enableFilterFunctionality>
        <enableDocumentationManager>false</enableDocumentationManager>
        <enableAddressBar>false</enableAddressBar>
        <cacheDirectory>drupal6/api</cacheDirectory>
    </qtHelp>

De paden naar het collectionFile en het projectFile zijn zodanig dat ze bij de dagelijse taken niet in de weg staan. De aparte qch bestanden worden in een "qch" subdirectory gezet (het "storage" attribuut) en ze worden gekopiëerd van de Doxygen uitvoerdirectories. Andere opties daarvoor zijn "move" (waarmee de gecomprimeerde helpbestanden uit de oorspronkelijke Doxygendirectories verplaatst worden) en "symlink" (maak een symbolische link naar de oorspronkelijke locatie).

De opties die volgen defini&eum;lren de interface van de Assistant. Meer details hierover vind je in de Qt documentatie. Let op het applicationIcon: dit moet in dezelfde directory als het collectionFile staan. Hiermee kun je een speciaal icoontje voor je Drupal assistant gebruiken - als je hiet niet wilt gebruiken laat je de optie gewoon weg.

Nu het interessante deel: de definities voor het Drupal (6) project:

    <drupal>
        <name>Drupal</name>
        <version>6.x</version>
        <versionSpecific>true</versionSpecific>
        <input>/home/cheetah/public_html/drupal</input>
        <exclude>/home/cheetah/public_html/drupal/backup</exclude>
        <exclude>/home/cheetah/public_html/drupal/doc</exclude>
        <output>/home/cheetah/public_html/drupal/doc</output>
        <logDirectory>/home/cheetah/public_html/drupal/doc/log</logDirectory>
        <namespace>org</namespace>
 
        <!-- The following are Drupal specific options! -->
        <groupBy>name</groupBy>
        <buildCore>true</buildCore>
        <buildModules>true</buildModules>
        <buildThemes>false</buildThemes>
        <latestContribOnly>true</latestContribOnly>
    </drupal>
</DoxyAssist>

Oh, en we sluiten de DoxyAssist ook nog even af. Maar eerder definiëren we ons project met een naam en versie. We willen versiespecifieke builds, wat wil zeggen dat de projectversie wordt meegenomen in de uiteindelijke uitvoer. Dat maakt het net wat makkelijker om later de versies uit te zoeken. In de input optie geven we aan waar de Drupal broncode staat. We voegen ook nog even enkele directories toe die Doxygen niet mee moet nemen. Daar zit ook onze uitvoerdirectory bij, waar Doxygen alle bestanden plaatst. Er is ook nog een aparte directory waar de logbestanden van Doxygen naar weggeschreven worden, zodat ook (mislukte) uitvoeren apart onderzocht kunnen worden, mocht dat nodig zijn.

Als laatste is de namespace optie de basisnamespace die gebruikt wordt in de Qt Assistant. DoxyAssist zet daar automatisch de projectnaam ("Drupal") en versie ("6.x") achter. Voor modules, komt hier op een vergelijkbare manier nog de modulenaam en versie achter. In de Qt Assistant worden deze volledige namen gebruikt om alle pagina's te kunnen onderscheiden. Zo wordt overlap voorkomen, wat zeker bij veel voorkomende pagina's een probleem is.

Tot dusver zijn de opties met name voor elk (generiek) DoxyAssist project geschikt. De volgende set opties is specifiek voor Drupal. Daarmee bepaal je van welke items de documentatie gemaakt moet worden (Core, extra modules en/of thema's) en of alle versies van een project gebruikt moeten worden, of alleen de laatste versie. Dat laatste is met name handig met een multi-site installatie, waar sommige sites nog oudere versies van modules hebben.

De groupBy optie is ook belangrijk: hiermee bepaal je hoe documentatie van modules gegroepeerd moet worden. De waarde is een item in de .info bestanden van modules. Nuttige waarden voor deze optie zijn "name" of "package".

DoxyAssist komt met een voorbeeldconfiguratie voor Drupal projecten met meer uitleg over elke optie in XML commentaar. Die kun je gebruiken om mee te beginnen. Zie de doc/examples directory in het DoxyAssist pakket om dat voorbeeld te krijgen.

Sla het XML bestand dat je hebt gemaakt op waar je het weer terug kunt vinden. De extensie maakt niet veel uit, maar ik raad zelf simpelweg .xml of .doxyassist aan. Ik ga in dit voorbeeld verder uit van /home/cheetah/public_html/drupal/drupal6.xml.

DoxyAssist Uitvoeren

Phew, alles staat klaar. Onze preprocessor uit de eerdere delen staat (hopelijk) ook nog op zijn plek. Tijd om het geheel werkend te krijgen. Het projectbestand staat klaar, dus dat kunnen we ook maar beter veilig bewaren. Als je het nog niet hebt, installeer dan nu Python 2.7 (Python 3.x werkt nog niet goed, 2.6 zou het wel gewoon moeten doen).

Start een terminal en voer het volgende in:

python /home/cheetah/usr/share/doxyassist/doxyassist.py /home/cheetah/public_html/drupal/drupal6.xml

Pas uiteraard het pad aan naar waar je DoxyAssist hebt geïnstalleerd. Als je hiermee een vage (syntax) foutmelding krijg, vervang dan "python" door "python2" - Python 3.x is dan waarschijnlijk je standaardversie.

Als je het commando goed hebt, leest DoxyAssist de configuratie en gaat aan de slag. Dit kan even duren. Als je PyQt4 ook nog hebt geïnstalleerd, zal de cache van de Assistant verwijderd worden. Dit betekent dat aanpassingen in de Assistant met dezelfde collectie (een oudere build) gereset worden. Dit is nodig om overgebleven filters te verwijderen. Zonder die stap zouden oude tags (bijvoorbeeld oude versies van modules) in de filterlijst blijven staan, ook al is de documentatie niet meer beschikbaar.

De laatste stap is om even de collectionFile instelling in het qtHelp gedeelte in het DoxyAssist configuratiebestand op te zoeken. Je hebt dit nodig om de Drupal Assistant eindelijk te starten:

assistant -collectionFile /home/cheetah/.local/doc/drupal-6.qhc

Het resultaat is te zien in de volgende set screenshots:

Tot slot, als je ooit nieuwe modules installeert, Drupal bijwerkt of de documentatie gewoon opnieuw wilt maken: simpelweg DoxyAssist opnieuw starten met hetzelfde projectbestand is voldoende. Alles wordt bijgewerkt en de volgende keer dat je de Drupal Assistant start zie je de vernieuwde documentatie met alle updates - inclusief nieuwe of bijgewerkte modules. Snel en simpel.

Einde

Dit is het einde van deze serie blogs (eindelijk!). We hebben de Qt Assistant zo gemaakt zodat hij ons ook assisteert bij Drupal ontwikkeling. Dit alles met behulp van Doxygen, een speciale preprocessor en DoxyAssist. Ik hoop dat je het nuttig vond.

Laat gerust een comment achter als je problemen hebt. Natuurlijk kun je ook contact met me opnemen als je het wilt hebben over DoxyAssist, bugs wilt melden of features wilt vragen enzovoorts!

Andere delen in deze serie:

Nieuw: DoxyAssist!

ChEeTaH — Sat, 22 Jan 2011 22:14:38 +0000

Voor mijn serie blogs over Drupal documentatie en de Qt Assistant, wilde ik modulaire API documentatie krijgen. Alles - Drupal Core en alle geïnstalleerde modules - op de grote hoop gooien werd namelijk erg rommelig. Aan de andere kant, alles helemaal gescheiden is ook weer omslachtig. Ik had een hulpje nodig dat automatisch nieuwe modules ontdekt en de documentatie in elkaar zet voor me. Daarna alles bundelen in één Qt Help Collection met de nodige filters, zodat ik alles samen of elke module's documentatie apart kan bekijken en snel kan wisselen binnen één interface. En dat is DoxyAssist!

Met DoxyAssist kun je documentatie van elk groot softwareproject opsplitsen in modules. De documentatie voor elke module wordt apart gebouwd. Daarna, als je de Qt Assistant gebruikt en DoxyAssist jouw help collectie laat maken, bundelt het ook weer alle losse onderdelen van de documentatie. In de Assistant worden filters aangemaakt, zodat je eenvoudig kan selecteren welke documentatie je precies wilt zien.

Verder is het mogelijk om een enkel Doxygen configuratiebestand (Doxyfile) in te lezen en te gebruiken als template. Als submodules kleine variaties in deze instellingen nodig hebben, kunnen ze aangepast worden zonder aparte Doxyfiles voor elke module te maken. Je kunt de nodige instellingen in het DoxyAssist configuratiebestand zetten, en teamleden hun eigen basistemplate laten gebruiken zodat ze de documentatie naar eigen wens kunnen aanpassen.

Speciale ondersteuning voor Drupal is er ook, waardoor DoxyAssist automatisch alle modules en thema's van de community zoekt en de documentatie groepeert zoals jij wilt.

Hierbij presenteer ik versie 0.1, onder GPLv3 licentie. DoxyAssist vereist Python en eventueel PyQt4. Het komt met wat configuratievoorbeelden om je op weg te helpen.

Download hier

Source code @ Gitorious

Sinterklaasliedje, op z'n Denglish #2

ChEeTaH — Sun, 05 Dec 2010 13:39:31 +0000

Wegens de vele vraag ernaar (lees: 2 mensen hebben erom gevraagd), nog een Sinterklaasliedje in het Denglish*. Dit is ook de laatste van het jaar.

* Opmerking: Wikipedia noemt "Denglisch" een mix van Duits en Engels. Misschien is Dunglish (Steenkolenengels) dus de betere term in dit geval... Ik bedoel in ieder geval het mengen van Nederlands en Engels. Mijn Denglisch (de Duitse variant) is waarschijnlijk veel slechter dan mijn Denglish/Dunglish.

The Sack of Santa Clause
The sack of Santa Clause
Santa Clause, Santa Clause
The sack of Santa Clause
Oh boys, boys, it's such a boss
There stops he, there stops he
There stops he happy of sin,
The whole, the whole
The whole world in
The sack of Santa Clause
Santa Clause, Santa Clause
The sack of Santa Clause
Oh boys, boys, it's such a boss

He is for big and small
Big and small, big and small
He is for big and small
Foreseen of tay and marsepain
And mountains, and mountains
And mountains sugar goods
So lecker, so lecker
So lecker and so sweet
He is for big and small
Big and small, big and small
He is for big and small
Foreseen of tay and marsepein

But under in that sack
In that sack, in that sack
But under in that sack
There lies the very big pack
For the lovely, for the sweet
For the lovely sweet child
Say was you, say was you
This year gehoresame friend?
But under in that sack
In that sack, in that sack
But under in that sack
There lies the very big pack

Met dank aan Liedjesland voor de originele Nederlandse tekst.

Sinterklaasliedje, op z'n Denglish

ChEeTaH — Sat, 04 Dec 2010 13:54:32 +0000

Morgen is het Sinterklaasfeest, en omdat ik overtuigd ben om te gaan bloggen, is hier een Sinterklaasliedje. In het kader van globalisering heb ik het persoonlijk vertaald naar het Denglish, zodat de gemiddelde* Nederlander de tekst ook nog begrijpt.

See Ginder Comes The Steam boat
See ginder comes the steam boat
From Spain already on
He brings us Saint Nicholas
I see him already standing
How huppels his horse
The deck up and near
How wave the wimples
All heen and all weather

His knight stands to laughing
He screams us yet too
Who sweet is gets candy
Who bad is the roo
Oh dear Saint Nicholas
Come also to me
And don't drive really silent
Past my home

* Nee, ik heb geen enkel onderzoek of wat dan ook gedaan naar de kennis van het Engels voor de gemiddelde Nederlander.

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.

Andere delen in deze serie:

Bijlage	Grootte
Doxyfile.	62.98 KB
preprocess-drupal-doxygen.phps	12.45 KB

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.

Andere delen in deze serie:

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!

Andere delen in deze serie:

Bijlage	Grootte
Doxyfile.	62.83 KB