Retrouvez cet article dans : Linux Pratique Hors série 5

PmWiki est écrit en langage PHP et distribué sous la licence GPL. Cette application est principalement destinée à la conception de sites Web « collectifs », tel que le sous-entend le suffixe « wiki ». Pleinement conforme aux recommandations du W3C, PmWiki a été conçu pour être simple à installer, à modifier et à entretenir pour nombre d'usages différents.

Installation et paramétrage de PmWiki

Prérequis

C'est en consultant l'excellent site Debian Women (http://women.alioth.debian.org/) que j'ai découvert PmWiki. La facilité éditoriale, le système de contrôle d'accès et le grand nombre de modules de personnalisation de PmWiki m'a décidé à franchir le pas. Je dois avouer que l'absence de base de donnés a largement pesé dans la balance En effet, les pages sont simplement enregistrées dans un format textuel. Ceci n'influence aucunement la réactivité de PmWiki sur la fiabilité du stockage et la vélocité de présentation des données.

Fig. 1

Fig. 2

Le site de PmWiki, avec plus de 40 000 pages, fonctionne avec le système de fichiers à plat, sans problème de performance notable. Les prérequis sont tout à fait frugaux, car nous n'avons besoin que d'Apache et PHP4 pour assouvir notre appétit de publication numérique.

Installer PmWiki

Installer PmWiki consiste à télécharger la dernière version (archive pmwiki_latest.zip ou .tgz) puis à la décompresser et la copier à la racine de votre serveur Web. L'archive décompressée nous donne un dossier nommé pmwiki-2.1.5/, nous allons le renommer en pmwiki/ (ce sera plus simple pour l'écriture des URL). Dans notre cas, il s'agit d'une installation en local. Nous choisissons d'installer PmWiki dans /var/www/.
Rendons-nous maintenant à l'adresse d'installation de PmWiki, soit http://votre_espace_web/pmwiki/pmwiki.php. Vous devriez tomber sur une page présentant l'accorte apparence d'un wiki frétillant de bonne santé. Malheureusement, en bas de votre page HTML, PmWiki vous adresse le message suivant : « PmWiki can't process your request » (Fig. 1).
En effet, PmWiki nécessite un répertoire nommé
wiki.d/, accessible en écriture ; ce répertoire est destiné à contenir les pages Wiki. Deux solutions s'offrent à nous : créer ce répertoire manuellement et lui donner les permissions adéquates, ou faire du serveur Web le propriétaire du répertoire de PmWiki.
Dans le premier cas, nous entrons les commandes suivantes :

# mkdir /var/www/pmwiki/pmwiki/wiki.d
# chmod 2777 /var/www/pmwiki/pmwiki/wiki.d

Rafraîchissez la page de votre navigateur et les messages d'erreur devraient tous avoir disparus, votre PmWiki est dès lors fonctionnel (Fig. 2). Très important : pour la sécurité de votre wiki, veillez à restreindre les droits en écriture sur le répertoire Pmwiki par la suite :

# chmod 755 /var/www/pmwiki/

Pour l'autre solution, plus simple, il suffit d'entrer la commande suivante :
# chown www-data.www-data /var/www/pmwiki/ (www-data désigne le serveur Web pour Debian et dérivées, à adapter en fonction de votre distribution).

Configuration initiale

Configurer PmWiki pour l'adapter à vos besoins est très simple. Tout se déroule dans le fichier nommé local/config.php. Seulement, nous avons beau explorer ce répertoire, ledit fichier ne s'y trouve pas. Même s'il est possible de le créer à la main, nous allons copier le fichier modèle prévu par les créateurs de PmWiki à l'intention des partisans du moindre effort que nous sommes. Ce fichier doit être renommé en config.php :

#cp /var/www/pmwiki/docs/sample-config.php /var/www/pmwiki/local/config.php

Puisque que nous y sommes, ajoutons une directive au fichier de configuration d'Apache pour lui ordonner de considérer la page pmwiki.php comme un Directory Index. Pour ce faire, recherchez la ligne consacrée au Directory Index dans le fichier de configuration, puis ajoutez la page pmwiki.php à la suite de index.php (et autres pages éventuelles). Puis, relançons Apache :

# /etc/init.d/apache restart

Il n'est plus besoin maintenant d'indiquer pmwiki.php à la suite du chemin absolu de votre PmWiki. L'URL http://votre_espace_web/pmwiki/pmwiki.php devient http://votre_espace_web/pmwiki ; emballez c'est pesé.

Apprenons à PmWiki à parler français

Vous avez sans doute remarqué que l'interface de PmWiki est en anglais. Le franciser est un jeu d'enfant : il faut télécharger, puis décompresser l'archive i18n.tgz (à récupérer sur le site officiel, rubrique PmWiki -> Download -> International language packs).
L'archive i18n.tgz contient deux dossiers : scripts/ et wikilib.d/. Le contenu de ces deux répertoires est à copier dans les répertoires du même nom déjà présents dans votre répertoire pmwiki/ : pmwiki/scripts/ et pmwiki/wikilib.d/.
Il faut maintenant indiquer à PmWiki que nous désirons utiliser les scripts de francisation. Pour ceci, il faut éditer le fichier /var/www/pmwiki/local/config.php pour ajouter la ligne suivante :

XLPage('fr','PmWikiFr.XLPage');

En rafraîchissant votre page Web, les menus d'édition doivent apparaître en français (Fig. 3).

Personnaliser PmWiki par les skins

L'interface de PmWiki, quoique ergonomique et plaisante à l'œil, peut ne pas satisfaire tous les goûts. A cette fin ont été créés les skins. Ce sont des thèmes permettant de contrôler l'apparence de votre PmWiki. Un thème est un ensemble de fichiers modifiant les codes de présentation esthétique du site. La liste suivante est honteusement copiée sur le site officiel de PmWiki, mais explique de manière précise et simple le contenu du dossier de skin.

• Un fichier de modèle, tel que skin.tmpl ou gemini.tmpl. Le modèle est écrit en HTML ou XHTML, et constitue le squelette du thème. Il contient des marqueurs spéciaux qui disent à PmWiki où insérer le contenu des pages.
• Les fichiers CSS, qui contrôlent l'aspect du thème.
• Les fichiers Image, pour décorer une page avec des images. Les formats courants d'images sont .jpg, .png, et .gif.
• Les fichiers PHP, tels que skin.php. Ceci permet au thème d'avoir des possibilités de personnalisation étendues que les possibilité du HTML et des CSS ne permettent pas.
• Les fichiers de Documentation, généralement du genre readme.txt ou skinname.txt. Ceci vous informe à propos des particularités d'installation ou des fonctionnalités spéciales du thème.

Fin de citation. Pour avoir mis moi-même les mains dans le cambouis, je vous assure que modifier un skin PmWiki est à la portée de tous ceux qui connaissent un minimum de XHTML et de CSS2, et si vous achetez régulièrement Linux Pratique vous devriez vous en sortir haut la main.
De plus, comme toujours avec les Logiciels libres, de nombreux contributeurs ont déjà élaboré des thèmes. Ils sont disponibles à cette adresse : http://www.pmwiki.org/wiki/Cookbook/Skins. Pour installer un skin, il suffit de télécharger le dossier compressé du skin, de le décompresser et de copier le dossier obtenu dans le répertoire pmwiki/pub/skins.
Remarque : Si, après décompression du skin, vous n'obtenez pas un dossier mais quelques fichiers épars, il vous faudra créer un dossier (portant le nom du skin par exemple) pour y placer ces fichiers.
Modifiez ensuite votre fichier /var/www/pmwiki/local/config.php en recherchant la ligne $Skin pour y indiquer la valeur du dossier précédemment copié. J'ai jeté mon dévolu sur le skin nommé « Soma », j'inscris donc : $Skin = 'soma'; (par défaut c'est le skin 'pmwiki' qui est utilisé). N'oubliez pas de décommenter cette ligne avant d'enregistrer votre modification.

Rafraîchissez votre navigateur, et l'habillage de votre PmWiki est totalement modifié. Libre à vous de modifier la feuille de style pour l'adapter à votre goût. Pensez tout de même à renvoyer un courriel aux auteurs de vos thèmes favoris, ça fait toujours plaisir. Merci donc à Carlos A. Bonamigo pour le skin Soma. Observez les skins Soma et Rose Trellis sur les Figures 4 et 5.

Fig. 4 : Le skin « Soma », créé par Carlos A. Bonamigo.

Fig. 5 : Le skin « Rose Trellis », créé par Sandy Schoen.

L'édition de texte

Nous en avons terminé avec la configuration basique de PmWiki. Pour les quelques extra-terrestres qui ne sauraient pas ce qu'est un wiki je dirais qu'il s'agit d'un site Web dynamique permettant à quiconque d'en modifier le contenu éditorial. Pour exemple, visitez le premier des wikis : http://c2.com/cgi/wiki?WelcomeVisitors créé par Ward Cunningham, et la très célèbre encyclopédie Wikipédia : http://fr.wikipedia.org/wiki/Accueil.
Avant tout, ayez à l'esprit que PmWiki ne vous amènera pas toutes les possibilités du XHTML. Il est avant tout utilisé pour une présentation rapide et fiable de vos documentations. Néanmoins, il offre de nombreuses fonctionnalités éditoriales et dynamiques que nous allons étudier.
Pour éditer une page, il suffit de cliquer sur le menu Éditer de votre PmWiki. Avant de construire le wiki de vos rêves, mieux vaut vous entraîner quelque peu sur le bac à sable nommé WikiSandbox (Fig. 6). Cette page est destinée aux tests. Pour générer du XHTML, PmWiki utilise ses propres balises, c'est en fait le principe de tous les wikis.

La hiérarchisation

Les différents titres et sous-titres correspondant aux balises <h></h> du XHTML sont obtenues au moyen du point d'exclamation. Un titre <h1>Mon titre</h1> est obtenu comme suit : !Mon titre!. Ceci se décline jusqu'à <h6>Mon titre</h6> avec 6 points d'exclamation !!!!!!Mon titre!!!!!!.
Les titres de pages correspondant à la balise <title> /title> sont obtenus grâce à la directive (:title:). La directive (:title Le titre de ma page:) correspond au code XHTML </title>Le titre de ma page<title>.

Le formatage des caractères

On entend par formatage la possibilité de modifier les graisses, les inclinaisons, et la taille des caractères. Pour l'utilisation de l'emphase et du renforcé, la syntaxe PmWiki utilise les guillemets simples. Le mot ou groupe de mots entouré de deux guillemets simples devient italique, et le mot ou groupe de mots entouré de 3 guillemets devient gras (Fig. 7).
Pour obtenir un texte préformaté destiné par exemple à un extrait de code source, il suffit de placer la phrase entre un crochet et une arobase. [@Mon bout de code@] est équivalent à <pre>Mon bout de code</pre> en XHTML.
Il est aussi possible de barrer un texte {-texte barré-}, de le souligner {+texte souligné+}, de modifier la taille du caractère [+Gros texte+] et même [++Très gros texte++] (remplacer le + par un – pour un texte de plus en plus petit). Notez que si vous désirez centrer un texte il faut utiliser le code %center%Mon titre est centré.

Les listes

A ma connaissance, la syntaxe PmWiki ne connaît que deux types de listes : numérotées et à bulles. Pas question ici d'organiser vos listes avec la souplesse du XHTML. Vous conviendrez sans peine que dans la majorité des cas, ces deux modes sont amplement suffisants. La liste à puce s'obtient en faisant précéder la phrase d'une astérisque, la profondeur de la liste est gérée par le nombre d'astérisques. Le code XHTML suivant est obtenu par le code wiki : *coucou

<ul>
<li>coucou
</li>
</ul>

Difficile de faire plus simple. Pour générer une liste ordonnée il suffit de remplacer l'astérisque par un dièse : #coucou.

Les liens

A chaque fois que vous désirez faire d'un mot ou d'un groupe de mots, un lien vers une autre page, il suffit de les entourer de deux crochets [[Mon lien]]. Si la page vers laquelle le lien pointe n'existe pas, il vous suffira de l'éditer par la suite. Ne soyez pas surpris si chaque première lettre de chaque mot est mise en majuscule pour les titres de page, c'est interne à PmWiki et vous n'y pouvez rien.
Bien sûr, des liens externes peuvent être ajoutés. Soit vous tapez l'URL complète, comme http://www.google.fr et elle apparaîtra telle que, soit vous préférez que l'on clique sur un lien nommé et le code deviendra [[http://www.google.fr | Google]], l'internaute cliquera sur le mot Google pour accéder au site. Il est aussi possible de faire apparaître le lien comme référence [[http://www.google.com |#]] et dans ce cas, le lien apparaîtra numéroté entre crochets. Notez qu'insérer l'URL vers une image suffit à la faire apparaître sur votre page PmWiki.

Aller plus loin dans le paramétrage de PmWiki

Vous voici à même de formater simplement vos pages PmWiki. Si vous vous attachez à ce wiki vous découvrirez, au fur et à mesure de vos rédactions, des possibilités d'édition plus larges que celles exposées ici, qui ne servent qu'à une prise en main rapide. De plus, une aide non négligeable à l'édition nous est offerte par PmWiki.

Activer la barre d'édition

Apprendre par cœur les balises d'édition PmWiki est à même de lasser les plus tenaces d'entre nous. A cet effet, Patrick R. Michaud, le créateur de PmWiki, a créé une barre d'édition bien pratique qu'il suffit d'activer dans le fichier local/config.php. Éditez le fichier et recherchez la ligne #$EnableGUIButtons = 1; puis décommentez-la (autrement dit, supprimez le dièse du début de ligne). Editez une page et vous verrez une barre d'édition :

Fig. 6

Fig.7

Fig. 8

Vous pouvez, à l'aide de cet éditeur, effectuer les actions que nous avons étudiées plus haut. De plus, il est possible d'ajouter des fonctionnalités à la barre d'édition en décommentant d'autres lignes situées à la fin du fichier local/config.php. Ces lignes commencent toutes par #$GUIButtons et permettent entre autres d'agir sur la hiérarchisation, les indentations, les listes, et les tableaux. L'édition de vos pages va s'en trouver grandement facilitée et je sens que les lecteurs ayant transpiré sur l'apprentissage de la syntaxe PmWiki sont en train de se demander pourquoi je n'ai pas donné les clefs du bonheur éditorial plus tôt !

La protection par mots de passe

L'originalité et la clef du succès du concept wiki est que tout le monde peut participer à un wiki. Il n'y a qu'à contribuer à Wikipédia pour constater combien il est satisfaisant et gratifiant de participer à un projet collectif. Dans ce cas, il est totalement inutile de protéger par quelque moyen que ce soit l'accès aux pages en lecture ou en écriture.
D'autres cas de figure existent où l'on désire profiter de la facilité d'édition sans pour autant l'ouvrir à des inconnus. PmWiki possède un système interne de contrôle d'accès par mot de passe pour des pages individuelles ou de groupes wiki. Avant d'aller plus avant dans la gestion de la protection des pages, il me faut décrire le concept de groupes wiki.
PmWiki a la capacité de classer les pages en groupes de pages apparentées entre elles. Pour définir un groupe wiki, il suffit de respecter cette syntaxe lors de la création de pages : [[groupe/page]]. Par exemple, si une partie de vos centres d'intérêt se trouve être le fromage, l'édition de la sidebar (Fig. 9) pourrait comprendre cette organisation :

Fig. 9

%sidehead% [[fromage/fromage]]
*[[fromage/le brie]]
*[[fromage/le cantal]]
*[[fromage/le roquefort]]

Toute opération sur le groupe fromage aura une incidence sur les pages concernant le brie, le cantal et le roquefort. Revenons maintenant à nos protections par mot de passe. Pour protéger une page par mot de passe, il suffit d'ajouter ?action=attr à la page que vous consultez. Vous obtiendrez le formulaire tel qu’en Figure 10.

Fig. 10

A vous de choisir le mot de passe, et les actions sur lesquelles il agira. Pour éditer la page protégée, il vous faudra ensuite saisir le mot de passe qui a été défini (Fig. 11).

Fig. 11

Pour définir un mot de passe sur un groupe wiki, c'est à peine plus compliqué. Saisissez l'URL suivante, http://www.exemple.com/pmwiki?n=NomDuGroupe.GroupAttributes?action=attr, en remplaçant NomDuGroupe par le nom de votre groupe wiki. Vous tomberez sur un formulaire ressemblant au précédent. Le mot de passe attribué au groupe wiki affecte toutes les pages appartenant au groupe wiki. Les mots de passes sont écrits en clair mais PmWiki les encode automatiquement.

Activer l'upload

Télécharger depuis où bon vous semble des fichiers sur votre serveur PmWiki est tout à fait possible. Il suffit d'en activer la fonction. Il vous faut rechercher la directive #$EnableUpload du fichier local/config.php et la décommenter.
Tant que nous y sommes, définissons aussi un administrateur dans la directive $DefaultPasswords (située quelques lignes plus haut) ainsi que son mot de passe.

$DefaultPasswords['admin'] = crypt('votre_mot_de_passe');

Notez que le mot de passe est écrit en clair dans le fichier local/config.php mais que PmWiki se charge de l'encoder lors des authentifications.
Sauvegardez vos modifications et ajoutez à l'URL de la page où vous désirez insérer un fichier la directive suivante : ?action=upload. Vous pouvez visualiser la syntaxe de l'URL sur la capture d'écran suivante.
Une boîte de dialogue apparaît vous réclamant le mot de passe administrateur défini plus haut. Remplissez le champ, et validez. Le formulaire suivant vous propose de sélectionner un fichier sur votre disque dur. Il ne vous reste plus qu'à choisir l'image que vous désirez voir figurer sur votre wiki, la sélectionner, et PmWiki se charge de l'uploader (Fig. 12).
Notez que si vous ne donnez pas de nom à la pièce jointe, PmWiki nommera automatiquement la pièce jointe avec son nom d'origine. Vérifiez toutefois que le nom de la pièce jointe ne comporte pas d'espace, et n'oubliez pas de préciser l'extension du fichier. Éditez maintenant la page sur laquelle vous désirez insérer l'image et ajoutez la directive suivante dans le menu d'édition :

Attach:mon_fichier.extension

Puis validez les changements, votre image devrait apparaître. Les fichiers images ne sont pas les seuls à être téléchargeables, preuve en est le fichier
/scripts/upload.php, qui spécifie les types de fichiers valides. Quelle que soit l'extension, le procédé d'upload reste le même, ainsi que la syntaxe Attach:mon_fichier.extension.

Le Cookbook

Le Cookbook est le repository des contributions annexes à PmWiki. Ces contributions étendent les fonctionnalités de base et en ajoutent de nouvelles. L'adresse à laquelle vous pouvez consulter ces contributions est la suivante : http://www.pmichaud.com/wiki/Cookbook/Cookbook.
Elles vont de la création de quiz au calendrier, en passant par la gestion des galeries d'images ou l'insertion de formules mathématiques grâce à LaTeX. Comme découverte des Cookbook, je vous propose d'installer une extension permettant de créer une table des matières dans une page PmWiki. Cette extension se trouve à l'URL suivante : http://www.pmwiki.org/wiki/Cookbook/PageTableOfContents. Téléchargez l'extension :

$ wget http://www.pmwiki.org/pmwiki/uploads/Cookbook/pagetoc.php

Puis copiez-la dans le répertoire /cookbook :

$ cp pagetoc.php /var/www/cookbook

Modifiez le fichier local/config.php en ajoutant la ligne suivante :

include_once("$FarmD/cookbook/pagetoc.php");

Dès que vous aurez besoin d'une table des matières, il vous suffira d'ajouter le code (:toc:) au début de votre page PmWiki pour obtenir le menu illustré par la Figure 14 (bien entendu, la page devra contenir quelques titres pour que la table des matières puisse être générée).

Conclusion

Je n'ai bien sûr pas passé en revue toutes les fonctionnalités de PmWiki, le but de l'article n'étant pas d'être exhaustif, mais d'essayer de vous donner une vision globale de ce logiciel. PmWiki est un exemple de plus à placer à l'actif du modèle collaboratif GNU.
Même si Patrick R. Michaud a initié seul le développement de PmWiki, de nombreux collaborateurs travaillent maintenant à ce logiciel et à ses extensions, et encore plus nombreux sont ceux qui l'utilisent. Je vous souhaite beaucoup de plaisir à explorer toutes les dimensions de PmWiki et espère lire vos documentations dans un avenir proche.

• Dernière version : PmWiki 2.1.5 (mars 2006)

 

Changer le logo de PmWiki

Sachez qu'il vous est tout à fait possible de modifier le logo qui apparaît en haut à gauche de votre wiki. Par défaut, c'est le logo de PmWiki qui apparaît. Pour en changer, éditez le fichier config.php, et modifiez puis décommentez la ligne suivante :

$PageLogoUrl = "$PubDirUrl/skins/pmwiki/pmwiki-32.gif";

Notez que le logo se trouve dans le dossier du skin utilisé. Donc, copiez dans le dossier du skin choisi votre nouveau logo. Pour notre exemple, nous remplaçons ainsi dans la ligne ci-dessus pmwiki-32.gif par tux.png. Observez le résultat sur la figure ci-dessus

 

Fig. 12

Fig. 13

 

Retrouvez cet article dans : Linux Pratique Hors série 5