=head1 mod_perl Documentation project's Style Guide
=head1 Introduction
This document defines the style the authors should follow when writing
a documentation for the mod_perl documentation project.
To read this document in the proper way, run:
% perldoc ./style.pod
Or convert it to HTML:
% pod2html --infile=style.pod --outfile=style.html
=head1 Formatting
The documentation format is a 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 I manpage.
=head1 Document structure
The document should be constructed from at least the following
C<=head1> sections.
=over
=item NAME
The first section's title must be C 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 like
IEE or BEE.
This section won't appear in the finally rendered document
=item DESCRIPTION
C or C, so it gets rendered like 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 pages
that link the documents together. 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 C
section since in Perl modules pods it usually comes third after the
C section.
=item 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.
=back
=head1 Conventions
Please try to use the following conventions when writing the docs:
=over
=item *
When using domain names in examples use only I and its
derivatives (e.g. I) or I (or
I). I is an official example
domain.
=item *
Keep the text width <= 74 cols.
=item *
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, like images, which may get corrupted with
the above command. So something like more fine tuned command is
safer:
% find . -type f -name "*.pod" -exec perl -pi -e 's|\cM||' {} \;
=item *
Use CEModuleE 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 CE"GET"E,
but just CEGETE).
Some older documentation uses BEE for module names. This was
because C didn't make CEE stand out enough. If you
spot any of these, please replace them with CEE. Use
BEE for stressing very important things. Use them
infrequently, since if there are many phrases in bold the original
intention is getting lost.
=item *
Use IEfilenameE for filenames, URIs and things that are
generally written in italics.
=item *
Use BEstressE for stressing things, but you should avoid using
this tag unless you think things are very important. Over-use of the
bold text reduces it's original intention -- make things stand out.
=item *
Use EEgtE for encoding C<$r-Efilename> as in
CE$r-EEgtEfilenameE. Note that with some Perl versions
C and some other C are broken and don't correctly
interpret this tag.
=item *
URLs are left unmarked. Pod2Html automatically identifies and
highlights them. If later we would like to do that inline, we can have
an easy C one liner.
=item *
Linking between items in the same doc and across documents: Currently
use the technique explained in perlpod man page. It's not very
sophisticated, but we will have to think about some better technique.
Currently, you can do this: for example, if editing the document
I, you can link to the I one by
using
L
or
L
[the second example doesn't work yet, need to be fixed]
There are some other linking limitations; e.g. you can't link directly
to the I of a section, and you can't link using relative
URIs. The latter limitation comes from the perlpodspec and hopefully
will be improved in the future.
=item *
Command line examples. Please use the following prompts to be
consistent.
I mode prompt:
ai% ls -l
I mode prompt:
ai# ls -l
(ai for A.I., short and sweet)
=item *
Titles and subtitles:
Use the head tags:
=head(1,2,3...)
Please try to avoid titles in B. Use caps like B, which
are a little more I.
=item *
Code examples:
META: not implemented yet! Currently use FEE
A new pod tag:
=example 1.1 This is a title
becomes:
Example 1.1: This is a title
=item *
Figures (images):
META: not implemented yet! Currently use =for html
A new pod tag:
=figure figure1.1.png This is a title
becomes:
Figure 1.1: This is a title
The index is extracted automatically from the file name.
=item *
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 make it a correct footnote.
=item *
META: not implemented yet!
Sidebars. Just like footnotes - it's not defined yet. Use [S] sidebar
[/S] for now.
=item *
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 make sure that
you don't leave any spaces on this line. Otherwise the two paragraphs
will be rendered as one. Especially remember to put a new empty line
between text and code snippets.
=item *
Code snippets
As you know 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 get 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.
=item *
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 make
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 beginning you might think that it might be a good idea to
keep all the code in sync with the doc, but very soon you will find
out that you change the code in the text and move the chapters and
sections around, which makes 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 CGI;
my $q = new CGI;
print "Hi";
So as I've said before we must not forget to add 2 space characters
indentation to empty lines with no code in them, so that the parser
picks up the whole code, removes the header with the filename and
separator, puts back 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 make the release broken. Another approach is to add some tail
(ending token), but it's a mess I think. I develop the text using
I in xemacs which shows all space characters not
followed by any text - this helps a lot!
=item *
Changes: In many directories, you will find a file named
I. This file contains the latest changes to a certain
documentation section, sorted by date (newest first). If you have made
any changes and sending a patch, it would be nice of you to include
the updated I file together with the patch.
A typical entry would look like this:
=head1 Fri 19 Apr 18:37:00 CET 2002
* Fixed some things and then other things, and then some other
things bla bla bla. [John Doe Ejohn.doe (at) aol.comE]
* Other changes to I, and to I. [stas]
Please try to keep things correctly aligned here (ie. the first
characters on each line should be vertically aligned with eachother),
as this file will most often be viewed as text.
=back
=head1 Review process
If you want to send a review of a document to the document maintainer,
please follow the following guidelines:
=head2 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 C 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.]
=head2 Adding Inline Remarks
=over 4
=item *
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 makes it easy to see what things
aren't yet complete and mark things that we want to work on later. So
please use something like:
[META: this should be completed]
=item *
Review Comments:
If you review some document and you want to comment on something, just
embed a paragraph with your comments enclosed in [] and with your name
prepended. E.g:
[Stas: This document needs a review.
But it looks OK 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 questions.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
Stas Bekman Estas (at) stason.orgE
=head1 Authors
=over
=item * Stas Bekman Estas (at) stason.orgE
=back
=cut