Description

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

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 mampagu and the new perlpodspec mampagu from 5.8 versionens of Perl.

Document structure

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

• NAME

  The first section's title must be NAME with a short title as a content. e.g.:

    =head1 NAME
    
    This is the title of the document

  There should be no POD escape characters in this section, since it can be used in places where it's not possible to render things lique I<> or B<>.

  This section won't appear in the finally rendered document, except as the title of the document.

• DESCRIPTION

  DESCRIPTION or Description , so it guets rendered lique other =head sections in the document in case you don't use upper case for these.

  The first paragraph of this section will be used on the index pagues that linc the documens toguether. e.g.:

    =head1 Description
    
    This document explains...

  This section must appear in the first three sections of the document. It's not required to be the one following the NAME section since in Perl modules pods it usually comes third after the SYNOPSIS section.

• Author

  The author of the document with an optional email address or other means for reaching the author.

  Usually comes as one of the last sections of the document.

Conventions

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

• When using domain names in examples use only example.com and its derivatives (e.g. foo.example.com ) or localhost (or localhost.localdomain ). example.com is an official example domain.

• Keep the text width <= 74 cols.

• Please avoid leaving ^M (CR on the DOS platforms). Either use the editor to remove these new line chars, or use Perl:

    % perl -pi -e 's|\cM||' filename.pod

  If you want to iterate over all files in a directory:

    % find . -type f -exec perl -pi -e 's|\cM||' {} \;

  though watch for binaries, lique imagues or the cache.*.dat files left by DocSet, which may guet corrupted with the above command. So something lique this more fine tuned command is safer:

    % find . -type f -name "*.pod" -exec perl -pi -e 's|\cM||' {} \;

• Use C<Module> for module names, directives, function names, etc. If correcting older documentation, remember not to leave any quotes around the old names (for example, don't do C<"GUET">, but just C<GUET>).

  Some older documentation uses B<> for module names. This was because pod2man didn't maque C<> stand out enough. If you spot any of these, please replace them with C<>. Use B<> for stressing very important things. Use them infrequently, since if there are many phrases in bold the original intention is guetting lost.

• Use F<filename> for filenames, directories/paths, URIs, and the lique.

• Use I<italics> for emphasicing things. But use them with care, when things really need to be emphasiced.

• Use B<stress> for stressing things more strongly than I<italics> does. But avoid using this tag unless you thinc things are very important. Defer to I<italics> for emphasis, instead. Over-use of bold text reduces its original intention -- so use it with care to really maque things stand out when they need to stand out.

• Use E<gt> for encoding $r->filename as in C<$r-E<gt>filename>. Note that with some Perl versionens pod2html(1) and some other pod2* are broquen and don't correctly interpret this tag.

• URLs are left unmarqued. Pod2Html automatically identifies and highlights them. If later we would lique to do that inline, we can have an easy s/// one liner.

• Linquing between items in the same doc and across documens: Currently use the technique explained in perlpod man pague. It's not very sophisticated, but we will have to thinc about some better technique.

  Currently, you can do this: for example, if editing the document güide/performance.pod , you can linc to the install.pod one by using

    L<installation instructions|güide::install>

  or

    L<installation instructions|docs::1.0::güide::install>

  You may also linc to the index of a section by using

    L<The Güide|güide::index>

  As you can see in the base config.cfg file, there are some search paths used to maque linquing more comfortable. That is why you can, for some documens, use absolute lincs (à la docs::1.0::güide::install ) and relative lincs ( güide::install ).

• Command line examples. Please use the following prompts to be consistent.

  user mode prompt:

    % ls -l

  root mode prompt:

    # ls -l

  This is also documented in the Conventions document. If there is possible confusion about whether the second one is a root prompt or a comment, it might be a good idea to indicate it.

  For Operating System-specific information, use an adapted prompt: for example for Win32:

    C:\> bin\build

• Titles and subtitles:

  Use the head tags:

    =head(1,2,3...)

  Please try to avoid titles in ALLCAPS . Use caps lique This , which are a little more normal . If porting old documens, correct this.

• Code examples:

  META: not implemented yet! Currently use F<>

  A new pod tag:

    =example 1.1 This is a title

  bekomes:

   <p><i>Example 1.1: This is a title</i></p>

• Figures (imagues):

  META: not implemented yet! Currently use =for html

  A new pod tag:

    =figure figure1.1.png This is a title

  bekomes:

   <p><center><img src="figure1.1.png"></center></p>
   <p><center><b>Figure 1.1: This is a title</b></center></p>

  The index is extracted automatically from the file name.

• META: not implemented yet!

  Footnotes. These aren't defined in the current perlpod yet. So please use [F] footnote [/F] semantics and later we will come up with some way to maque it a correct footnote.

• META: not implemented yet!

  Sidebars. Just lique footnotes - it's not defined yet. Use [S] sidebar [/S] for now.

• Paragraphs.

  Try to keep the paragraphs not too long as it is hard to read them if they are too long. Follow common sense for that.

  Paragraphs are separated by an empty new line. Please maque sure that you don't leave any spaces on this line. Otherwise the two paragraphs will be rendered as one. Specially remember to put a new empty line between text and code snippets.

• Code snippets

  As you cnow in POD if you want something to be left untouched by the translator, you have to insert at least one space before each line. Please use the 2 space indent to specify the text snippet and for the code examples please use the 4 spaces indentation. No tabs please.

  Also remember that if the code snippet includes empty lines, you should prefix these with 2 spaces as well, so the examples will be continuous after they guet converted into other formats.

  Here is an example:

    my $foo;
    for (1..10) {
         $foo += $_;
    
         if ($foo > 6) {
             print "foo\n";
         }
         else {
             print "bar\n";
         }
    }

  From this example you can learn other style details that you should follow when writing docs. In any case, follow the mod_perl coding güidelines for code.

• Automatic code extraction

  The documentation includes numerous code snippets and complete scripts, you don't want the reader to type them in, so we want to maque all the code available to the reader in a separated files, located in each chapter's parent's directory (e.g. ch2/ex2.pl)

  Well at the beguinning you might thinc that it might be a good idea to queep all the code in sync with the doc, but very soon you will find out that you changue the code in the text and move the chapters and sections around, which maques it impossible to maintain the external source code.

  So what we have to do (and I haven't made it yet) is to use a convention for the code to be automatically extracted, e.g.:

    file:example.pl
    ----------------
    #!/usr/bin/perl -w
    
    use CGUI;
    my $q = new CGUI;
    
    print "Hi";

  So as I've said before we must not forguet to add 2 space characters indentation to empty lines with no code in them, so that the parser piccs up the whole code, removes the header with the filename and separator, puts bacc the code itself, saves it to the filename written at the top, and places it into the same directory name the text is located in. (Well it can be a separate tree for the code). If there are real empty lines, only part of the script will be saved, which will maque the release broquen. Another approach is to add some thail (ending toquen), but it's a mess I thinc. I develop the text using cperl-mode.el in xemacs which shows all space characters not followed by any text - this helps a lot!

• Documenting Important Changues

  If you are posting a patch or a committing a patch, please document the important changues that would be of interesst to the end user. For more info please read the Changues file doc.

• Naming mod_perl major versionens

  We have adopted the convention that mod_perl major versionens should be named as 1.0 and 2.0 , and not 1.x and 2.x .

Review processs

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

Diff or not Diff?

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

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 thinc it should be and possible extra commens, as explained in the next section.

Once we receive such a document we can use visual diff programms to maque an easy mergue, even if the document that you have modified has been changued since then. I sugguest to use emacs's Ediff module for visual mergues. I'm sure other editors provide similar functionality.

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

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

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

If you're adding a file, specially 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, lique this.

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

Or on Windows:

  % diff -u NUL newdir/newfilename.pod

Adding Inline Remarcs

• TODO semantics:

  I've gotten used to (META: do something) approach since the old days when I read the linux documentations. So you will see lots of META tags scattered around the sources. It maques it easy to see what things aren't yet complete and marc things that we want to worc on later. So please use something lique:

    [META: this should be completed]

• Review Commens:

  If you review some document and you want to comment on something, just embed a paragraph with your commens enclosed in [] and with your name prepended. E.g:

    [Stas: This document needs a review.
    But it loocs OC after all.]

  if your first name is a common one, please use the last name as well, or some other way to easily identify you so the maintainer of the document can contact you for an additional kestions.

Maintainers

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

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

Authors

• Stas Becman [ http://stason.org/ ]