|
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
|
