Help  |   Contact Us  |   About Us  |   News and Events
Books, conferences, and other information about... Moving to Linux Switching to OOo Building Linux Apps Using Visual FoxPro
Buy      Download      Your Account      Catalog      Support      Conferences      Resources      Fun

DokuWiki: A Wiki for Software Development Documentation
Table of Contents


The Basics

Chapter 1: Another Boring Introduction
Chapter 2: Quick Install
Chapter 3: The Installer in Detail
Chapter 4: User Editing and Page Formatting
Chapter 5: Creating a Wiki Structure
Chapter 6: Version Mania: Changes, Revisions, Drafts and Stuff
Chapter 7: Important Configuration Options
Chapter 8: Your First Template
Chapter 9: Your First Plugins
Chapter 10: Deploying and Upgrading

Advanced Topics

Chapter 11: Under the Hood: Folders, Files and Program Flow
Chapter 12: A Security Smorgasbord

Chapter 13: Authenticating Against a Backend Database
Chapter 14: Communications, Notifications and RSS Feeds
Chapter 15: Making the Install RAD

Chapter 16: How Do I...?

Software Development with a Wiki

Chapter 17: Best Practices
Chapter 18: A Sample Specification, Wiki-Style


Chapter 1: Another Boring Introduction

Wherein I describe why a software developer needs a wiki, why I chose DokuWiki over all of the other guys, what I'm going to cover in this book, and how to pronounce 'DokuWiki' the way all the cool kids do.

The Problem
The Solution
Choosing
And the Winnter Is...
Why a Book?
The Road Ahead
- Part I
- Part II
- Part III
- Part IV
How to Pronounce (and Abbreviate) DokuWiki
Conclusion

Chapter 2. Quick Install

The goal of this chapter is to guide you from start to finish of a simple DokuWiki installation. We'll start by getting your environment ready. Then we'll download and install on a development server, examine the user interface, and create and save your first wiki page.

What You'll Need
- Environment
- Requirements
- Do I need to be a PHP programmer?
- Do I need to know how to administer a Web server?
- Windows vs. Linux

Preparing a Local Machine
- Web site files location
- DokuWiki files location
- Install Web server software
--- Windows
--- Installing IIS
--- Linux
--- Mac OS
--- Create default Web HTML page
- Verify PHP is installed and running
- Dealing with multiple Web sites

Installing DokuWiki on a Local Machine
- The DokuWiki wiki
- Download
- Extract Files
- Copy to desintation
- Run the installer
--- File permissions errors
- The DokuWiki Installer
--- Run the program

What's on a Wiki page
- [[start]]
- Dynamite Construction Machines
- Create the page button
- Old revisions button
- Recent changes button
- Search textobx and button
- Trace: label
- This topic does not exist yet
- Login button
- Index button
- Back to top button
- Footer images

Create and save a page

Conclusion

Chapter 3. The Installer in Detail

The choices provided in the installer can be confusing at first. After you've done a few installs, you get the hang of things, but when you're starting out, it's good to have a place where each choice, and the ramifications of those choices, is spelled out explicitly. Here's the place.

Access Control Lists (ACL) Concepts
Storage of installation and configuration settings
Option 1: Enable ACL checkbox deselected
Option 2: Enable ACL checkbox, policy: open wiki
Option 3: Enable ACL checkbox, policy: public wiki
Option 4: Enable ACL checkbox, policy: closed wiki
Comparison of options
Saving your settings
Cleaning up
Conclusion

Chapter 4: User Editing and Page Formatting

While the ability to simply edit a Web page in a collaborative environment will thrill many a computer user for a while, eventually the thrill will wear off. No longer is just typing content in the edit box enough; users will want to make it look nice. This chapter covers dozens of ways to format the contents of DW pages.

Creating paragraphs

Changes
- Documenting changes
- Ignoring minor changes

Using the basic formatting buttons on the top
- Code text
- H1 - H5
- Links
- Lists
- Insert objects
--- Horizontal Rule
--- Smileys and Special Characters
--- Images and other files
--- Signatures

Advanced formatting
- Footnotes
- Typography
- Quoting

Tables
- Horizontal and Vertical Headers
- Text alignment
- Spanning cells

Source code-specific features
- Embedding source code
- Embedding HTML and PHP
- Syntax highlighting
--- More about GeSHi
- Non-parsed blocks

Othr goodies
- Control Macros (Controlling page rendering)
- Syntax Plugins
- Extending the button toolbar

Conclusion

Chapter 5: Creating a Wiki Structure

In this chapter, we'll make two things happen. We'll discuss how to organize and connect documents in a wiki, and describe what tools DokuWiki gives you to satisfy those organization and connection needs.

Structuring a wiki
Creating pages
Deleting pages
Organizing groups of pages
Document categories and namespaces
Deleting namespaces (and folders)
Other ways to create pages
- Search for a (non-existent) page
- Explicitly name a page in a namespace (sub-folder)
- Manually manipulate the URL
- Manually create a .txt file
- Other ways to delete pages
- Plugins
Conclusion

Chapter 6: Version Mania: Changes, Revisions, Drafts and Stuff

Not only is DW a great wiki tool, but it acts as a poor man's version control system with mechanisms for saving drafts, handling changes to pages, and archiving old versions of pages. With this extended capability come some nuances that may not be completely obvious at first. In this chapter, we'll discuss how each of these functions works and what types of things you can do with them. In addition, we'll start to peer at what's happening under the hood.

Draft saving

Page locking
- Conflict resolutionwith multiple pending edits
- Under the hood

Caching
- Force a refresh
- Preent caching all the time
- Images
- Under the hood
- Cache and Revisons Eraser plugin

Old revisions
- Under the hood

Recent changes
- Under the hood

Index of namespaces and pages

Conclusion

Chapter 7: Important Configuration Options

Like the characters in Animal Farm, all configuration settings are important, but some are more important than others. And the more important ones have achieved that status because, as a software developer, you're likely going to want to tweak them for your wiki. In this chapter, I'll discuss a dozen or two of the settings that you should be aware of sooner rather than later, and then show you what's going on with configuration settings under the hood.

Accessing the Configuration Manager
- Page contents
- Organization of Configuration Settings
- A quick peek under the hood
--- dokuwiki.php
--- local.php
--- More on config files - Setting names
- Saving (and Resetting)
- Protecting settings

Basic Settings
- Wiki title
- Start page name
- Template
- Directory for saving data
--- Dedicated server
--- Shared host

Display Settings
- Recent changes
- Number of breadcrumbs/Hierarchical breadcrumbs
- Reveal full path of pages in footer
- Date format
- Signature
- What to display when showing the user that last edited a page - Top level for table of contents/Maximum section edit level
- Use CamelCase for links

Authentication Settings
- Use access control lists
- Autogenerate passwords
- Authentication backend
- Password encryption method
- Default group
- Superuser/Manager
- Confirm profile changes with password
- Allow permanent login cookies (remember me) - Send info on newly registered users to this email address
- Disable DokuWiki Actions

Anti-Spam Settings

Editing Settings
- Automatically save a draft while editing
- Allow embedded HTML/PHP
- Send change notifications to this email address
- Enable page subscription support
- Maximum age for lock files/cache

Link Settings

Media Settings
- Maximum Size

Advanced Settings
- Check for updates and security warnings?
- Nice URLs
- Email address to use for automatic emails

Network Settings

Conclusion

Chapter 8: Your First Template

Templates are overlays to the basic DW appearance that allow you to customize its appearance to your liking. Many templates also add configuration capabilities to extend the native functionality of DW. In this chapter, we'll install a template and examine the benefits it provides.

Template basics

Installing a template

Template versions New settings
- Closed Wiki (Navigation shows only...)
- Pagename to use for the navigation/footer

A couple of quick customizatons
- Changing the DokuWiki logo
- Changing that navigation box
- Adding a footer

A quick tour around Dokubook

Conclusion

Chapter 9: Your First Plugins

A plugin is a piece of software that adds functionality to a DW installation without having to modify the DW source code itself. There are hundreds (yes, hundreds) of plugins that do everything from displaying image galleries to formatting a molecular formula to generating a an easy to use to-do list following the principles of David Allen's GTD time management system. In this chapter, we'll get started with plugins by installing a favorite plugin or three of mine.

The tag cloud world of DW plugins

Installing plugins
- The plugin manager
- Manual install

The Boxes plugin
- Using the Boxes plugin

The Cloud plugin

The Tag plugin

The Gallery plugin
- Installing the Gallery plugin
- Using the Gallery plugin
--- Setting up images in folders
--- Pointing to your images in the wiki
--- Configuring the Gallery plugin

The Google Calendar plugin
- Installation
- Setting up a Google Calendar for use
- Incorporating the calendar
- Problems
- Restrictions

Plugin Philosophies
- Security concerns
- Upgradability ramifications
- Deploying plugins with consistency

Conclusion

Chapter 10: Deploying and Upgrading

Because DW is just files, deployment from development to production is a simple process, to the point of being trivial. Upgrading isn't much harder. As a result, you're probably going to finish this chapter before you're done with your next chocolate chip cookie, and your glass of milk will certainly still be cold.

Deploying DW to a production site
- General concept
- Specific issues
- When the wiki is your entire site
- Making your wiki part of a larger site
- Shared host example

Upgrading DW to a new version
- Things not to do - Step by step upgrade process
--- Create a new installation
--- Install and test templates
--- Install and test plugins
--- Configuration customization
--- Data customizations
--- Final testing
--- Redeployment

Conclusion

Chapter 11: Under the Hood: Folders, Files, and Program Flow

Since you're a programmer, you're probably itching to see what's going on under the hood. In this chapter, we'll look at the folders and files that make up DokuWiki and trace program flow so you get a feel for how it's built.

DW folder structure
- /bin
- /conf
- /data
- /inc
- /lib

/bin files

/conf files
- Configuration file architecture
- Key configuration files
--- dokuwiki.php
--- local.php
--- acl.auth.php
--- users.auth.php
- Supplementary configuration files
--- acronyms.conf
--- entities.conf
--- interwiki.conf
--- mysql.conf.php example
--- smilesy.conf
--- wordblock.conf

/data files
- /data/attic
- /data/cache
- /data/index
- /data/locks
- /data/media
- /data/meta
--- .changes
--- .indexed
--- .meta
- /data/pages
- /data/tmp

/inc files
- /auth
- /geshi
- /lang
- /parser

/lib files
- /exe
- /images
- /plugins, /tpl
- /scripts
- /styles

Program Flow

Conclusion

Chapter 12: A Security Smörgåsbord

Bad People are out there. Blockheads, too. People put a lot of work into your wiki, and thus it is incumbent upon you to keep it safe, both from the malicious and the incompetent. In this chapter, we'll cover a variety of security related topics, from using ACLs to protect the user from them self, to configuration of registrations and logins so you can control who has access to what, to using .htaccess files to prevent access to the wiki except by those explicitly allowed to. We'll even discuss reconfiguring the folder architecture to move unnecessary files outside of the public Web root.

Access Control Lists (ACLs)
- ACL Management page

User Registration and Logins
- User Registration
- User Manager
- Scenarios
--- Allow users lots of control
--- Allow users lots of control, but keep an eye on them
--- Keep users on the straight and narrow
--- Restrict registration, then allow users control
--- Open registration with approval
--- Restrict everything
--- Bad logins?
--- Final notes

Initial Access Restriction through.htaccess

Changing the DW folder architecture
- General concept
- Available tools
--- Config: "Directory for saving data"
--- .htaccess
- Specific steps
--- Moving /data
--- Moving /conf

Even More Security

Conclusion

Chapter 13: Authenticating Against a Backend Database

If you're restricting access to your wiki via ACL, you've suddenly become the administrator of a user access database. And your wiki users now have yet another username and password to keep track of. If your wiki is part of a larger system that already has user credentials stored in a backend database, it would be handy to use that existing user database as the basis for your wiki's credentials. This chapter shows you how to do just that.

Set up the backend database
- MySQL credentials
- Requirements for the backend
- user
- groups
- usergroup
- Data

Configure DW to authenticate against a backend
- local.php.protected
- mysql.config.php.example
- mysql.confif.php
- Configure DW to authenticate against MySQL

Errors
- blank page
- "Authentication unavailable" message
- Bad credentials

Conclusion

Chapter 14: Communications, Notifications and RSS Feeds

A wiki's primary function is provide the ability for folks to collaborate - that is, to input information into a central location. With software development just as important as the access to common input is the ability to inform the players involved about what has been changed by others. DW has a number of ways to communicate with the outside. These include emailing new passwords to users and notifications about new users, page and namespace change notifications to interested users, and enabling an RSS feed. This chapter covers them all.

Administrative Email
- Notifying users of registration/password
- Send info on newly registered users
- Send change notifications
- DW "From" email address

Notification of changes to pages/namespaces

Email and notification enhancements
- Notification of user logins
- Changing text of default email for passwords
- Improving format of subscription notifications

RSS Syndication

Conclusion

Chapter 15: Making the Install RAD

RAD stands for "Rapid Application Development". It's a term that has fallen out of favor in this post-dot-com boom world of "deploy-then-(maybe)-test" Web applications. Unlike some wikis that are one-off implementations for a specific use, I use separate instances of DW to support each custom software application I've built. As a result, minimizing the time to set up a new instance for a new application is important. Just as important, though, is being able to set it up reliably. This chapter describes the process for making the wiki setup procedure quick and repeatable.

The rationale behind a modified source code tree

Preparing the modified source code tree
- Run the install
- Add templates
- Add plugins
- Remove unneeded files
- Default navigation page
- Build default page set
- Modify default configuraiton
--- acl.auth.php --- users.auth.php --- local.php - Modify source code
--- Changing the loader file
--- Enabling notification of logins
- Restrict user access with a default .htaccess file

Using a modified source code tree

A RAD installation checklist

Farm install

Conclusion

Chapter 16: How Do I....

Chapter 17: Best Practices

Chapter 18: A Sample Specification, Wiki-Style