Welcome to the new location of Alien's Wiki, sharing a single dokuwiki install with the SlackDocs Wiki.

Welcome to Eric Hameleers (Alien BOB)'s Wiki pages.

If you want to support my work, please consider a small donation:

no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


Previous revision
Next revision
slackware:wikinotes [2006/03/24 23:27] alien
Line 1: Line 1:
 +===== Setting up Alien's DokuWiki =====
  
 +Here's what I had to do to get the Wiki up and running. Remember that the DokuWiki has no need for a database server like MySQL. The Wiki pages, indexes and archives are stored as files below the DokuWiki root (or anyplace else if you want to separate the content from the code). This makes it ideal to install in your own home directory. You do not need any additional permissions on the webserver.
 +
 +The DokuWiki comes with a default template which is rather bland. Their web page lists a lot of user-contributed templates, some of which are visually more appealing or functionally better. I opted for the Monobook template. This is a port from the default [[wp>MediaWiki]] template (as seen on [[http://en.wikipedia.org|WikiPedia]]) which I find very nice looking. This template is avtively developed and many nice features have been added recently, which make it even better to customize.
 +
 +==== Installing the dokuwiki tarball ====
 +
 +  * Download the latest and greatest DokuWiki archive at the [[http://www.splitbrain.org/projects/dokuwiki|download page]].
 +
 +  * Unpack the tarball into your Apache DocumentRoot, change to the DocumentRoot directory (by default that is ''/var/www/htdocs'') and create a symbolic link called //dokuwiki// that points to the fresh DokuWiki directory tree: <code>ln -s dokuwiki-yyyy-mm-dd dokuwiki</code>. If you already have a DokuWiki running, better wait with changing the symlink until you're sure you've configured and upgraded everything right.
 +
 +  * Change into the DokuWiki directory and have a look around.\\ The ''conf'' directory is where we will be customizing the new Wiki soon. The ''data''  directory is where all the Wiki content (pages, indexes, archives, media, cache) will be stored. If anything, your Apache webserver //must// be able to write there. The ''conf'' and ''data'' directories are the most important to back up regularly!
 +
 +  * Configuration.\\ You can customize the Wiki by overriding any of the values that are found in ./conf/dokuwiki.php. Just run <code>
 +cd conf
 +cp -a local.php.dist local.php
 +</code> and add any line from ''dokuwiki.conf'' that you want to give a custom value.\\ When you want to add user accounts and access control lists, create the two needed configuration files and edit them (or use the Admin interface of your wiki to set this up): <code>
 +cd conf
 +cp -a users.auth.php.dist users.auth.php
 +cp -a acl.auth.php.dist acl.auth.php
 +</code> \\
 +
 +
 +  * Finally, make sure that the webserver can read and //write// to your DokuWiki: <code>chown -R nobody:wheel .</code> In this example command, I assumed that you are running your Apache as the user "nobody" which is the default for Slackware, and that you have root access to the server.\\  In my case on the Slackware server, I have no privileged account, so I cannot change the ownership of any files. In order to make the Wiki writable by the Apache process, I had to make the ''./data'' directory writable for "others": <code>chmod -R o+w /path/to/dokuwiki/data</code> There is also a problem with Dokuwiki's configuration manager. When you change configuration through the admin interface, the file ''./conf/local.php'' is (re-)written, actually the current file is moved to ''local.php.bak'' and a //new// file is written. In this process the //umask// settings are not honoured and you end up with a file owned by the web server and read-only to yourself. A small patch is enough to fix this, in the file ''./lib/plugins/config/settings/config.class.php'' at the start of function save_settings().\\ This is my diff: <code diff>
 +--- ./lib/plugins/config/settings/config.class.php.org  2006-03-23 08:22:32.000000000 -0800
 ++++ ./lib/plugins/config/settings/config.class.php      2006-03-23 08:23:37.000000000 -0800
 +@@ -80,6 +80,9 @@
 + 
 +     function save_settings($id, $header='', $backup=true) {
 + 
 ++      global $conf;
 ++      umask($conf['umask']);
 ++
 +       if ($this->locked) return false;
 + 
 +       $file = eval('return '.$this->_local_file.';');
 +
 +</code> Now, with a customized umask like ''$conf['umask'] = '0111';'' the ''local.php'' file will have mode 666, so that  even while it is owned by the webserver, you can still edit it.\\
 +<note important> You have to take care with the default umask and dmask settings because you will end up with lots of other files and directories that are owned by the webserver and read-only to you. This has the effect for instance, that you cannot delete the ''./data/cache'' directories and files any longer!</note>
 +
 +  * DokuWiki comes with a plugin manager that according to the documentation is disabled by default - to enable the plugin manager, add the following line to ''./conf/local.php'' <code>
 +$conf['pluginmanager'] = 1;              //enable automated plugin management
 +</code> For this to work, the plugin manager (i.e. efeectively the web server process) must have write access to the ''./lib/plugins'' directory, so I also did <code>
 +chmod -R a+w ./lib/plugins</code>
 +
 +==== Template and plugins ====
 +
 +=== Template: MonoBook ===
 +
 +  * Get the archive file for the monobook template from [[http://tatewake.com/wiki/projects:monobook_for_dokuwiki|Tatewake's web site]]. The template should match with the release of DokuWiki you've just installed. This is only an issue when there has been a major new release of DokuWiki. Usually you would just grab the most recent monobook release.
 +
 +  * Unzip the archive into the DokuWiki template directory: <code>unzip monobook-03142006.zip -d /path/to/dokuwiki/lib/tpl/</code>
 +
 +  * Fix the permissions and ownership of the monobook directory tree, so that the webserver can at least read them.
 +
 +  * //(16-mar-2006)// The monobook template misses the file ''./lib/tpl/default/style.ini'', so I copied it over to the monobook directory. This takes care of some custom definitions in the blog plugin.
 +
 +  * //(21-mar-2006)// The new version of the template (03182006) fixes the style issues I had with the previous version. I also adapted the tabs on the top of the wiki pages (the 'article' 'show page' etc...) to be more conformant with the MediaWiki's original Monobook template. These are my fixes: <code>
 +--- main.css.org        2006-03-20 15:56:32.000000000 -0800
 ++++ main.css            2006-03-20 15:43:56.000000000 -0800
 +@@ -827,6 +827,7 @@
 + #p-cactions li.selected {
 +     border-color: #fabd23;
 +     padding: 0 0 .2em 0;
 ++    font-weight: bold;
 + }
 + #p-cactions li a {
 +     background-color: white;
 +
 +
 +
 +--- main.php.org        2006-03-20 15:55:01.000000000 -0800
 ++++ main.php            2006-03-20 15:54:35.000000000 -0800
 +@@ -59,12 +59,13 @@
 +  <div id="p-cactions" class="portlet">
 +    <h5>Views</h5>
 +    <ul>
 +-     <li id="ca-nstab-main" class="selected"><b><a href="<?php echo DOKU_BASE?>doku.php?id=<?php echo $ID?>">article</a></b></li>
 ++     <li id="ca-nstab-main" class="selected"><a href="<?php echo DOKU_BASE?>doku.php?id=<?php echo $ID?>">article</a></li>
 + <?php if($INFO['perm'] == AUTH_ADMIN) { ?>
 +-     <li id="ca-talk" class="new"><?php tpl_actionlink('admin'); ?></li>
 ++     <li id="ca-talk" class="new<?php if($ACT == 'admin') { echo " selected"; } ?>"><?php tpl_actionlink('admin'); ?></li>
 + <?php } ?>
 +-     <li id="ca-edit"><b><?php tpl_actionlink('edit'); ?></b></li>
 +-     <li id="ca-history"><?php tpl_actionlink('history'); ?></li>
 ++     <li id="ca-edit" <?php if($ACT == 'edit') { echo "class=\"selected\""; } ?>><?php tpl_actionlink('edit'); ?></li>
 ++     <li id="ca-history" <?php if($ACT == 'revisions') { echo "class=\"selected\""; } ?>><?php tpl_actionlink('history'); ?></li>
 ++     <li id="ca-backlink" <?php if($ACT == 'backlink') { echo "class=\"selected\""; } ?>><?php tpl_actionlink('backlink'); ?></li>
 +    </ul>
 +  </div>
 +  <div class="portlet" id="p-logo">
 +</code>
 +
 +=== Plugin: blog ===
 +
 +  * Actually, I'm still testing this.\\ The blog plugin can be obtained [[http://wiki.splitbrain.org/plugin:blog|here]] and downloaded as a ZIP archive: <code>wget http://www.qwik.ch/media/blog.zip</code>
 +
 +  * Unzip the blog plugin into ''./lib/plugins/''. Add this to the //top// of your template's ''main.php'' - in my case that is the file ''./lib/tpl/monobook/main.php'': <code>
 +<?php
 +// include discussion code
 +include(DOKU_PLUGIN.'blog/functions.php');
 +// we must move the doctype down (unfortunately) - headers need to be first
 +?></code> It should come right before the line ''<!DOCTYPE html PUBLIC .....>''.\\ And add this line immediately below the line that says ''<?php tpl_content()?>'': <code><?php tpl_discussion()?>
 +</code>
 +    * (//24-mar-2006//) Actually, this introduces an error when you want to click the plugin's //info// button in the plugin manager.               I get the following error <code>
 +Fatal error: Cannot redeclare html_discussion() 
 +(previously declared in /home/tag-am-meer.info/public_html/wiki/lib/plugins/blog/functions.php:77) 
 +in /home/tag-am-meer.info/public_html/wiki/lib/plugins/blog/functions.php on line 76
 +</code> This is easily solved by changing the line you include at the top of your template’s main.php from <code> include(DOKU_PLUGIN.’blog/functions.php’);</code> to <code>include_once(DOKU_PLUGIN.'blog/functions.php');</code>
 +
 +  * Customization of the blog plugin.\\ Create a file ''./lib/plugins/blog/conf/local.php'' and copy the parameters from the file ''./lib/plugins/blog/conf/default.php'' over into this file if you want them changed. My only change was: <code>
 +$conf['plugin']['blog']['tag_namespace'] = 'blog:categories';       // where should tag links point to?
 +</code> This way, the tags or "categories" get their own [[http://wiki.splitbrain.org/wiki:namespaces|namespace]]. \\ Note that the original //$conf['tag_namespace']// must change to //$conf['plugin']['blog']['tag_namespace']//
 +
 +  * Now, the blog plugin is ready for use. How to use it, is another story entirely, and I am in the process of finding out.
 +
 +
 +=== Plugin: boxes ===
 +
 +The //boxes// plugin enables the ''<box></box>'' tag which shows up in your page as a floating box, with several possible styles. The feature that attracted me to it is the "left" and "right" styles which create floating boxes that are left- or right-aligned.
 +Unfortunately, my Mozilla browser does not display these floating boxes correctly :-( [[http://tag-am-meer.info/wiki/|This wiki]] shows boxes correctly though... who can explain why?\\
 +Installation:
 +
 +  * Download the [[http://www.cdsmith.plus.com/dokuwiki/plugin-box.tar.gz|plugin-box.tar.gz archive]] and unpack it into ''./lib/plugins/''. That is all!
 +
 +  * If your ''<box>'' tags don't show up, the wiki cache is interfering. Altering something in your Wiki configuration (like the used template) seems to force a cache flush, so that is what I did to make the boxes display right away.
 +
 +=== Plugin: note ===
 +
 +I downloaded the "note" plugin for DokuWiki. This plugin displays nice informational icons in the margin, like "tip" "warning" "note" and "note". The plugin source is available at [[http://wiki.splitbrain.org/plugin:note | the DokuWiki site]] but it did not do what I wanted from it, plus it requires you to copy the images into your template directory, and add the CSS to the template's stylesheet. So I hacked it, so that now the plugin is fully contained into the DokuWiki's ''./lib/plugins/note/'' directory. You can download my {{:slackware:dokuwiki-plugin-note-3alien.tar.gz|modified plugin}} and unpack it into your DokuWiki's ''./lib/plugins/'' directory.
 +
 +  * //(23-mar-2006)// My changes were picked up by Olivier, the author of the //note// plugin, and therefore I changed back to the "official" newly released version (which now uses nice rounded corners).
 +
 +
 +==== Tuning the look and feel ====
 +
 +  * The default bitmap that comes with DokuWiki (the one you see in the top left of every page) did not fit with the look and feel I wanted for my site. So I used the "blue orb" version of the Slackware "S" logo I found at [[http://www.kde-look.org/content/show.php?content=11377|KDE-look]] because that one is transparent and the blue "S" logo on the [[http://www.slackware.com/~msimons/slackware/grfx/|Slackware web site]] was not (and the orb is //much// nicer to look at).\\ I ran these commands to download it and convert it to a 128x128 pixel bitmap: <code>
 +wget http://www.kde-look.org/content/pre1/11377-1.png
 +convert 11377-1.png -resize 128x128 blueorb_128.png
 +cat blueorb_128.png > /path/to/dokuwiki/lib/tpl/monobook/wiki-dokuwiki-128.png
 +</code> Note that the monobook template redefines the location of the site's logo bitmap. The default bitmap for dokuwiki is ''./data/media/wiki/dokuwiki-128.png''
 +
 +  * I added my own links to the "navigation" and "toolbox" boxes on the left. This is as easy as editing the "user-modifiable" files found in ''./lib/tpl/monobook/user/*.php''
 +
 +  * <del>I added a few lines to monobook's main.css file that makes the Wiki links appear in //red// when they point to a not yet existing Wiki page.</del> The 14-mar-2006 version of MonoBook has a doku.css which contains the "missing wikilink" style definition. It now works out of the box.
 +
 +  * The blog plugin has a bland color scheme. I found a better looking {{:slackware:style.css|style.css}} in [[http://doogie.in-space.de/dokuwiki/|Doogie's blog]] and used that to replace ''./lib/plugins/blog/style.css''
 +
 +  * To silence Apache in it's error_log, I also copied a favicon.ico file to the DokuWiki image library: <code>cp /path/to/documentroot/favicon.ico /path/to/dokuwiki/lib/images/</code>
 +
 +
 +=== Adding an editor toolbar button ===
 +
 +I missed a toolbar button for quickly inserting ''<code></code>'' tags. This is what is needed to add such a button to the toolbar:
 +
 +  * Create a toolbar button (dimension 16x16 pixels) and call it "code.png" This is the resulting bitmap: [{{:slackware:code.png|code.png}}]
 +  * Copy the newly created "code.png" button image to ''./lib/images/toolbar/''
 +  * Add this array element for the new button to the file ''./inc/toolbar.php'':<file>
 +       array(
 +            'type'   => 'format',
 +            'title'  => $lang['qb_syntax'],
 +            'icon'   => 'code.png',
 +            'key'    => 's',
 +            'open'  => '<code>',
 +            'close'   => '</code>',
 +            ),
 +</file>
 +  * Add this text to the english language file  ''inc/lang/en/lang.php'' (for other languages the corresponding texts have not yet been updated): <code>$lang['qb_syntax' = 'Syntax Code';</code> And voilá!
 Setting up Alien&#039;s DokuWiki ()
SlackDocs