====== DokuWiki, installazione ======

Preso il ''**[[http://wiki.splitbrain.org/wiki:dokuwiki|Dokuwiki]]**'' originale invece del pacchetto Debian, scompattato in ''**/home/dokuwiki/**''. Per iniziare tutti i file appartengono a **root:root**, permessi **0644** per i file e **0755** per le directory. Queste le personalizzazioni:

<code>
touch data/changes.log
</code>

<code>
cp conf/users.auth.php.dist conf/users.auth.php
cp conf/acl.auth.php.dist   conf/acl.auth.php
cp conf/local.php.dist      conf/local.php
chgrp www-data conf/users.auth.php
chgrp www-data conf/acl.auth.php
chgrp www-data conf/local.php
chmod 664      conf/users.auth.php
chmod 664      conf/acl.auth.php
chmod 664      conf/local.php
</code>

<code>
chown -R www-data data
</code>

Dare il permesso di scrittura al server web sui file di configurazione **users.auth.php**, **acl.auth.php** e **local.php** serve a permettere l'amministrazione di Dokuwiki da interfaccia web.

====== Plugin ======

**NOTA:** per poter fare il download e l'installazione dei plugin direttamente dall'interfaccia web di amministrazione basta dare i permessi di scrittura su **''lib/plugins/''** al server web. Dopo aver fatto l'installazione si può nuovamente togliere i permessi, anche alla directory del plugin installato.

Effettuata l'installazione dei plugin **[[http://wiki.splitbrain.org/plugin:indexmenu|indexmenu]]** e **[[http://wiki.splitbrain.org/plugin:blog:devel|blog]]**. Il secondo è [[http://wiki.splitbrain.org/wiki:develonly|develonly]], cioè funziona solo sulla versione in sviluppo di Dokuwiki. Per l'installazione è stato usato il plugin manager, bisogna fare in modo che il server web possa scrivere la directory ''**lib/plugins**''. Hanno funzionato correttamente, salvo la necessità di forzare il reload della pagina.

====== Sidebar (barra laterale) ======

Per avere una barra laterale, ad esempio per ospitare un indice del sito. In origine disponibile come **template**, qui il [[http://wiki.jalakai.co.uk/dokuwiki/doku.php/start|sito web originale]] e qui la pagina su [[http://www.dokuwiki.org/template:sidebar|Dokuwiki.org]]. Il suo uso tuttavia **è sconsigliato** perché ad ogni aggiornamento del Dokuwiki bisognerebbe aggiornare lo stile del template per comprendere tutte le novità (nuovi pulsanti, variazioni dello stile predefinito, ecc.).

Molto meglio **[[http://wiki.birth-online.de/software/php/dw-sidebar-plugin|l'implementazione come plugin]]** che è sostanzialmente indipendente dallo stile/template in uso. Qui la pagina su [[http://www.dokuwiki.org/plugin:sidebar|Dokuwiki.org]].

L'installazione e la configurazione si fanno normalmente dall'interfaccia di amministrazione. Provato e funzionante con la versione 2012-01-25 di Dokuwiki.
====== Patch (modifiche) ======

Ho modificato alcuni file:

^ lib/plugins/include/helper.php.dist  | La funzione **blog** deve presentare solo la prima parte di un articolo, interrompendo non solo al primo titolo (opzione **firstseconly** del plugin), ma alla prima occorrenza di una entity (ho scelto **=>**)  |
^ lib/tpl/sidebar/main.php.dist  | Nella sidebar compare una scritta **hide**, che non si capisce bene a cosa serve; tolta!  |
^ conf/interwiki.conf  | Aggiunta la sigla interwiki **wpit** che punta a [[wpit>Wikipedia]] Italia.  |

Qui l'{{:tecnica:download:dokuwiki_changes_2009-02-14.tgz|archivio con i file modificati}} e gli originali (rispetto alla versione 2009-02-14).

====== Configurazione locale ======

Queste le configurazioni messe in ''**conf/local.php**''.

<code php>
// Configuration of DokuWiki core.
$conf['title'] = 'rigacci.org';
$conf['template'] = 'sidebar';
$conf['breadcrumbs'] = 6;
$conf['useheading'] = 1; //use the first heading in a page as its name
// Temporarly disabled beacause of a problem on PCRE library.
$conf['usewordblock']= 0; // block spam based on words? 0|1
$conf['useacl'] = 1;
$conf['superuser'] = '@admin';
$conf['phpok'] = 1;
$conf['compress'] = 0;
$conf['hidepages'] = 'sidebar|blog'; //regexp for pages to be skipped from RSS, Search, Recent Changes and blog
// Make URLs more friendly to webalizer and search engines.
$conf['userewrite'] = 2; //this makes nice URLs: 0: off 1: .htaccess 2: internal
$conf['useslash'] = 1; //use slash instead of colon? only when rewrite is on

// Configuration for the Blog plugin.
$conf['plugin']['blog']['showlink'] = 0;
$conf['plugin']['blog']['showdate'] = 0;
$conf['plugin']['blog']['showuser'] = 0;
$conf['plugin']['blog']['sortkey'] = 'pagename';
$conf['plugin']['blog']['stop_on_entity'] = '=>';

// Configuration for the Indexmenu plugin.
$conf['plugin']['indexmenu']['headpage']      = 'blog,:start:'; //name for the pages from which retrive the title
$conf['plugin']['indexmenu']['hide_headpage'] = 'true';
$conf['plugin']['indexmenu']['skip_index']    = '/(playground|wiki)$/'; //namespaces to skip
$conf['plugin']['indexmenu']['skip_file']     = ''; //files to skip
$conf['plugin']['indexmenu']['empty_msg']     = 'Sorry, no menu for <b>{{ns}}</b>';
</code>

====== Link relativi ======

Quando si usano i namespace conviene utilizzare link relativi rispetto alle pagine o ai file. Questa la sintassi da utilizzare:

<code>
[[..:..:namespace:page|Two level up page]]
[[.:namespage:page|One level down page]]
</code>

====== URL rewriting and Apache alias ======

Abbiamo attivato le opzioni ''**$conf['userewrite']**'' e ''**$conf['useslash']**'' in modo che gli url generati da DokuWiki siano più adatti ai motori di ricerca e al Webalizer.

^ URL standard | %%http://www.rigacci.org/wiki/doku.php?id=doc:appunti:linux:sa:dokuwiki%% |
^ URL rewrite  | %%http://www.rigacci.org/wiki/doku.php/doc/appunti/linux/sa/dokuwiki%% |

Inoltre si vuole il DokuWiki nella sottodirectory ''**/wiki/**'', non a livello della DocumentRoot. I file PHP sono in realtà installati in ''**/home/dokuwiki/**'', si è provato inizialmente con un alias di Apache:

<file>
# WARNING! Does not work with DokuWiki 'userewrite'!
Alias /wiki /home/dokuwiki
</file>

Purtroppo in questo modo non funziona. Si è quindi creato un link simbolico dalla DocumentRoot verso ''**/home/dokuwiki**'', nella configurazione di Apache rimane solo l'indispensabile.

<code>
lrwxrwxrwx 1 root root 14 Oct 19 14:37 /var/www/www.rigacci.org/wiki -> /home/dokuwiki/
</code>

<file>
<Location /wiki/>
    # Disable indexes and enabled symlinks.
    # Without symlinks enabled you may get
    #403 Forbidden errors when url rewriting.
    Options -Indexes +FollowSymLinks
    AllowOverride All
    order allow,deny
    allow from all
</Location>
</file>

====== Forzare https su login ======

Per forzare il passaggio in https quando si effettua l'autenticazione si aggiunge alla configurazione del VirtualHost:

<file>
# Force https for Dokuwiki login.
RewriteEngine On
RewriteCond %{HTTPS} !on
RewriteCond %{QUERY_STRING} \bdo=log(in|out)\b
RewriteRule ^(.*) https://%{HTTP_HOST}/$1 [R,QSA,L]
</file>

====== Cached pages bug on upgrade ======

After upgrading Dokuwiki Debian package from version 20050713-2 to **0.0.20060309-3**, I got several pages with junk messages like this:

<code html>
<b>Warning</b>:  call_user_func_array(): First argumented is expected to be a valid callback, 'doku_renderer_xhtml::toc_open'
was given in <b>/usr/share/dokuwiki/inc/parserutils.php</b> on line <b>370</b><br /><br />
<b>Warning</b>:  call_user_func_array(): First argumented is expected to be a valid callback, 'doku_renderer_xhtml::tocbranch_open'
was given in <b>/usr/share/dokuwiki/inc/parserutils.php</b> on line <b>370</b><br /><br />
<b>Warning</b>:  call_user_func_array(): First argumented is expected to be a valid callback, 'doku_renderer_xhtml::tocitem_open'
was given in <b>/usr/share/dokuwiki/inc/parserutils.php</b> on line <b>370</b><br /><br />
</code>

It seems that XML parsing functions changed, so the old cached pages are not longer valid. To invalidate all the cached pages you can simply touch the file ''**dokuwiki/conf/local.php**'' with a new timestamp.


====== Forzare il refresh dei dati ======

DokuWiki mantiene in alcuni file dei metadati relativi alle pagine memorizzate, ad esempio la ricerca per testo libero non avviene direttamente sulle pagine, ma su file indice (**''data/cache/*.idx''**) per velocizzare l'operazione di ricerca.

Inoltre quando viene generata una pagina, questa viene salvata anche nella cache di DokuWiki, in modo che possa essere servita successivamente.

Ovviamente nel normale utilizzo di DokuWiki la cache dovrebbe essere sempre coerente con i dati, ma in alcune circostanze potrebbe essere necessario forzare un aggiornamento.

=== Pagina non da cache ===
Per forzare la generazione di una pagina senza utilizzare la copia in cache basta chiamare la pagina ed aggiungere all'URL il paramtro ''**&purge=true**''.

=== Indici per ricerca ===
Se una pagina viene aggiunta senza passare per DokuWiki - ad esempio copiando direttamente un file nella directory - l'indice per la ricerca a testo libero non la include. Per rigenerare gli indici **.idx** si può utilizzare lo script da riga di comando:

<code>
cd /home/dokuwiki
php bin/indexer.php
chown -R www-data:www-data ./data
</code>

**ATTENZIONE!** Il comando chown serve a ripristinare le giuste **ownership** ai file contenuti nella directory **data**, i file vengono creati con l'owner di chi esegue indexer.php.

=== Messaggio di notifica ===
Se è attiva l'opzione ''**$conf['updatecheck']**'', quando è loggato un amministratore può comparire all'inizio della pagina un messaggio del tipo:

<code>
New release available: rc2006-10-08. Fixes a XSS vulnerability - upgrade now! [5]
</code>

Teoricamente il messaggio dovrebbe scomparire appena effettuato l'aggiornamento, se dovesse persistere si può rimuovere manualmente il file ''**data/cache/messages.txt**''. Il messaggio visualizzato dipende dal numero contenuto nella prima riga del file ''**conf/msg**'': viene fatta una richiesta per messaggi nuovi al server **%%http://update.dokuwiki.org/check/%%**.

=== Heading (titolo) di pagina ===
Come fare ad aggiornarlo?

====== Dokuwiki upgrade ======

Upgrade from ''dokuwiki-2008-05-05.tgz'' to ''dokuwiki-2009-02-14.tgz''. Manual way.

  * Extract the tarball into a new directory and check permissions
  * Merge old **''data/''** directory into the new tree
  * Purge files and directories from **''data/cache/''**
  * Merge localized files into **''conf/''** (see below)
  * Restore all locally installed **''lib/tpl/''** and **''lib/plugins/''**
  * Regenerate the search indexes (see below)

Configuration files to be restored:

  * **''acl.auth.php''**
  * **''interwiki.local.conf''** (was ''interwiki.conf'')
  * **''local.php''**
  * **''mime.local.conf''**
  * **''plugins.local.php''**
  * **''users.auth.php''**

Example of plugins/templates installed: ''plugins/include'', ''plugins/indexmenu'', ''plugins/blog'', ''tpl/sidebar''.

Fix permissions on all files and directories:

<code>
cd dokuwiki_new
chown -R root:root *
find . -type d -print0 | xargs -0 chmod 755
find . -type f -print0 | xargs -0 chmod 644

chgrp www-data conf
chmod 775 conf

chgrp www-data lib/plugins
chmod 775 lib/plugins

for file in local.php acl.auth.php users.auth.php; do
    touch conf/$file
    chgrp www-data conf/$file
    chmod 664 conf/$file
done

touch conf/local.php
</code>

Regenerate indexes (to be safe):

<code>
php bin/indexer.php
chown -R www-data:www-data ./data
</code>

====== Style customization ======

In the file **''lib/tpl/default/style.ini''** you can read: //Changing this file is the simplest method to give your wiki a new look//.

One simple way is to make an image with several block filled with the original colors, then adjust the colors as you want (e.g. with GIMP, //Adjust Color Balance// function). Finally pick the hex value of each color and replace it into the file.

The following PHP script can be used to print a table with all the used colors:

<code php>
<?php
$fp = fopen('lib/tpl/default/style.ini', 'r');
echo "<table cellpadding=\"3\" cellspacing=\"1\" border=\"1\">\n";
while(!feof($fp)) {
    $line = fgets($fp, 2048);
    if (preg_match('/(\S+)\s*=\s*"#([0-9a-fA-F]+)"/', $line, $matches)) {
        echo '<tr><td>' . $matches[1] . '</td>';
        echo '<td>' . $matches[2] . '</td>';
        echo '<td width="180" bgcolor="' . $matches[2] . "\">&nbsp;</td></tr>\n";
    }
}
echo "</table>\n";
fclose($fp)
?>
</code>

====== Plugins customization ======

Here it is some {{.:patches:dokuwiki_plugins_customization.tgz|patches}} to **indexmenu** (2009-08-29) and **include** (2009-11-27) plugins, they are working with Dokuwiki 2010-11-07.

===== indexmenu: disable context menu from JavaScritp index =====

Changed the following files:

  * ''lib/plugins/indexmenu/jsmenu/admmenu.js.dist''
  * ''lib/plugins/indexmenu/jsmenu/menu.js.dist''
  * ''lib/plugins/indexmenu/jsmenu/usrmenu.js.dist''

commented out the **''var indexmenu_contextmenu''** declaration.

===== include plugin: limit included text untill special char =====

Changed the following file:

  * ''lib/plugins/include/helper.php''

added a statement which searches for the **''=>''** entity and treats it like the end of the first section.
====== Plugin dw2pdf (esporta PDF) ======

Il plugin **[[http://www.dokuwiki.org/plugin:dw2pdf|dw2pdf]]** aggiunge la funzione "esporta PDF" ad ogni pagina.

  * Si installa come gli altri plugin.
  * Il PDF si ottiene aggiungendo all'URL il parametro **''do=export_pdf''**.
  * Per aggiungere un pulsante //Esporta PDF// si deve modificare il template in uso. Ad esempio in **''lib/tpl/default/main.php''** si aggiunge nel ''div'' **''%%id="bar__bottomleft"%%''** il seguente codice: <code>
<form class="button" method="get" action="<?php wl($ID)?>">
  <div class="no">       
    <input type="submit" value="Export to PDF" class="button" />
    <input type="hidden" name="do" value="export_pdf" />
    <input type="hidden" name="id" value="<?php echo $ID?>" />
  </div>            
</form>
</code>

===== Personalizzazione =====

Alcuni aspetti del PDF generato (ad esempio le **intestazioni** e i **piè di pagina**) possono essere personalizzati configurando il plugin.

Lo stile per la creazione del PDF è controllato dagli stili contenuti in  **''dw2pdf/tpl/default/''**, è possibile creare altre directory e poi scegliere quale stile usare da //Amministrazione// => //Configurazione Wiki//.

FIXME Valido per la vecchia versione del plugin: i selettori devono fare riferimento alle classi della pagina web, escludendo il parent **''div.dokuwiki''**.

===== Intestazioni e piè di pagina =====

FIXME Problema riscontrato con la vecchia versione del plugin: Sembra che ci sia **un bug** per cui non viene usata l'intestazione e piè di pagina per le pagine dispari (//odd//), ma viene usata quella delle pagine pari, scambiando il lato destro con il sinistro. Forse è un [[http://www.dokuwiki.org/plugin:dw2pdf#footer|bug della libreria mPDF]]?

Se si vuole evitare l'effetto //mirror// si imposta **''%%$mpdf->mirrorMargins = 0%%''** in ''action.php'', in questo modo verranno usati intestazione e piè di pagina delle pagine pari (//even//), senza l'effetto //mirror//.

===== Bug PDF corrotto =====

C'era un [[https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/issues/80|bug]] nella versione dw2pdf del 2012-05-20, per cui il PDF generato è corrotto alla prima richiesta, ma è buono dalla seconda in poi. Il tutto è causato da un errore il cui output si inserisce nel file PDF generato, mentre nelle richieste successive il file viene recuparato dalla cache e quindi è valido.

Il bug è stato risolto il 18 dicembre 2013, con il commit [[https://github.com/splitbrain/dokuwiki-plugin-dw2pdf/commit/28e636ea2c440004f73897bbe4181c53ac3b7952|28e636e]].
====== No input file specified ======

In alcune installazioni, quando si attiva l'opzione [[http://www.dokuwiki.org/config:userewrite|userewrite]] si può incappare nell'errore:

<code>
No input file specified.
</code>

La soluzione può essere quella di impostare il paramtero PHP [[http://www.php.net/manual/en/ini.core.php#ini.cgi.fix-pathinfo|cgi.fix_pathinfo]] (che dovrebbe essere abilitato come impostazione predefinita):

<code>
cgi.fix_pathinfo = 1
</code>

Per attivare l'opzione **''userewrite = 2''** bisogna che il server gestisca il PATH_INFO, per verificare si può creare una pagina ''pathinfo.php'' con questo codice:

<code php>
<?php print "PATH_INFO = " . $_SERVER['PATH_INFO']; ?>
</code>

puntando il browser all'indirizzo **%%http://example.server.org/pathinfo.php/PROVA123%%** si deve ottenere la risposta:

<file>
PATH_INFO = /PROVA123
</file>
====== Riferimenti web ======

  * Homepage: [[http://www.splitbrain.org/]]
  * Plugins: [[http://wiki.splitbrain.org/wiki:plugins]]
  * Dokuwiki devel: [[http://wiki.splitbrain.org/wiki:development]]
  * Indexmenu plugin: [[http://samuele.netsons.org/dokuwiki/media/indexmenu.zip]]
  * Blog devel plugin: [[http://wiki.splitbrain.org/plugin:blog:devel]]
  * Sidebar template: [[http://wiki.jalakai.co.uk/dokuwiki/doku.php/start]]
  * Sidebar devel: [[http://www.cdsmith.plus.com/dokuwiki/template-sidebar-dev.tar.gz]]