Overview

The Document Management System in Comserv provides a flexible and powerful way to manage documentation files. It automatically discovers, routes, and serves documentation files from the Documentation directory.

The system is built around the Comserv::Controller::Documentation controller, which handles all aspects of document management including file discovery, routing, and rendering.

How It Works

File Discovery

When the application starts, the Documentation controller scans the root/Documentation directory for all files. It processes both template files (.tt) and other file types (JSON, HTML, images, etc.).

For each file found, the controller creates a route that allows the file to be accessed via a URL. For example, a file named user_guide.tt would be accessible at /Documentation/user_guide.

Route Generation

Routes are generated dynamically based on the files found in the Documentation directory. The controller uses several mechanisms to ensure that routes are valid and don't conflict with existing routes:

• Reserved Name Handling - Names that conflict with Perl built-ins or existing packages are handled safely
• Valid Identifier Check - Ensures that route names are valid Perl identifiers
• Safe Prefixing - Problematic names are prefixed with "doc_" to avoid conflicts

Content Serving

The controller serves different types of content appropriately:

• Template Files (.tt) - Rendered using the Template Toolkit engine
• JSON Files - Served with the appropriate content type for JSON
• HTML Files - Served as HTML content
• Images - Served with the appropriate image content type
• Other Files - Served as plain text or with an appropriate content type

Adding New Documentation

Adding new documentation is simple:

1. Create a new file in the root/Documentation directory
2. For template files, use the .tt extension and include the PageVersion information
3. Restart the application (or wait for automatic route generation)

Template Format

Template files should include the PageVersion information at the top:

This helps track the file version and location, and is displayed when debug mode is enabled.

Documentation Index

The Documentation Index page (/Documentation) provides a comprehensive list of all available documentation pages. It organizes the pages alphabetically and provides links to each page.

The index is generated dynamically based on the files found in the Documentation directory, so it's always up-to-date with the latest documentation.

Controller Implementation

The Documentation controller implements several key methods:

• BUILD - Initializes the controller and scans for documentation files
• index - Displays the documentation index page
• view - Displays a specific documentation page
• auto - Handles automatic routing for documentation pages
• register_actions - Registers dynamic routes for all documentation files

It also includes explicit routes for common documentation pages to ensure they're always available even if the files don't exist yet.

Error Handling

The system includes robust error handling:

• If a requested documentation page doesn't exist, a friendly error page is displayed
• If there are issues with route generation, errors are logged but don't prevent the application from starting
• File paths are sanitized to prevent directory traversal attacks