You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2002/01/23 07:53:27 UTC
cvs commit: modperl-docs/admin style.pod
stas 02/01/22 22:53:27
Modified: admin style.pod
Log:
- add the guidelines for document layout
Revision Changes Path
1.4 +48 -0 modperl-docs/admin/style.pod
Index: style.pod
===================================================================
RCS file: /home/cvs/modperl-docs/admin/style.pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- style.pod 27 Dec 2001 07:32:42 -0000 1.3
+++ style.pod 23 Jan 2002 06:53:27 -0000 1.4
@@ -16,6 +16,54 @@
formats. You can learn the syntax of this format from the I<perlpod>
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<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 like I<> or
+B<>.
+
+This section won't appear in the finally rendered document
+
+=item DESCRIPTION
+
+C<DESCRIPTION> or C<Description>, 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<NAME>
+section since in Perl modules pods it usually comes third after the
+C<SYNOPSIS> 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:
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org