mod_perl logo perl icon
no previous pagepage up: How to Contribute to the Documentationnext page: Changes File Specs

Documentation Style Guide






Practical mod_perl

Practical mod_perl

By Stas Bekman, Eric Cholet
The mod_perl Developer's Cookbook

The mod_perl Developer's Cookbook

By Geoffrey Young, Paul Lindner, Randy Kobes
mod_perl Pocket Reference

mod_perl Pocket Reference

By Andrew Ford
Writing Apache Modules with Perl and C

Writing Apache Modules with Perl and C

By Lincoln Stein, Doug MacEachern
Embedding Perl in HTML with Mason

Embedding Perl in HTML with Mason

By Dave Rolsky, Ken Williams
mod_perl2 User's Guide

mod_perl2 User's Guide

By Stas Bekman, Jim Brandt


Table of Contents

Description

This document defines the style the authors should follow when writing a documentation for the mod_perl documentation project.



TOP

Formatting

The documentation format is plain POD (Plain Old Documentation), which then will be converted into HTML, PS, PDF and other formats. You can learn the syntax of this format from the perlpod manpage and the new perlpodspec manpage from 5.8 versions of Perl.



TOP

Document structure

The document should be constructed from at least the following =head1 sections.



TOP

Conventions

Please try to use the following conventions when writing the docs:



TOP

Review process

If you want to send a review of a document to the document maintainer, please follow the following guidelines:



TOP

Diff or not Diff?

Since the text is changing a lot it's much harder to apply patches, especially if you happen to make a patch against an older version.

Therefore we have found that it's much better for the docs maintainers to receive the whole document which is already corrected the way you think it should be and possible extra comments, as explained in the next section.

Once we receive such a document we can use visual diff programs to make an easy merge, even if the document that you have modified has been changed since then. I suggest to use emacs's Ediff module for visual merges. I'm sure other editors provide similar functionality.

[Stas: if you know about these functionalities, please let me know so we can share the knowledge with others who don't use emacs.]

To submit normal patches (when they are minor changes, and you're sure the document hasn't changed), use the svn diff method:

  % svn diff src/docs/1.0/...pod

If you're adding a file, especially if it needs a new directory, it might be a good idea to submit a patch against /dev/null, which will automatically create the new directory, like this.

  % diff -u /dev/null newdir/newfilename.pod

Or on Windows:

  % diff -u NUL newdir/newfilename.pod


TOP

Adding Inline Remarks



TOP

Maintainers

Maintainer is the person(s) you should contact with updates, corrections and patches.

Stas Bekman [http://stason.org/]



TOP

Authors






TOP
no previous pagepage up: How to Contribute to the Documentationnext page: Changes File Specs